HeritagePay API
​string​string​string​string​string​string · uuid
​string · required​string · required​string · required​string​string · uuid​string​string​string · enum​string · enum​string​integer · min: 0​integer · min: 0​integer · min: 0​string​string · date-time​string · enum​string · enum​string · enum​integer · min: 0
Properties for Variant 1:​string · required​string · uuid​string​string​string​string​string​string · enum​string · enum​string​integer · min: 0​integer · min: 0​integer · min: 0​string​string · date-time​string · enum​string · enum​string · enum​integer · min: 0​boolean · required
​string​string​string​string​string​integer · min: 1 · max: 100
​string · required​string · required​string · required​string​string · enum​string​integer · min: 0 · max: 1000000​integer · min: 0 · max: 1000000​string · enum​string​string · date-time​string · enum​string​string​string​boolean · required
​string​string​boolean​integer · min: 1 · max: 100
​string · required​integer · min: 1 · max: 10000 · required​string · pattern: ​string​string · enum​string​string​string · enum​string · enum​boolean​string · enum​string​string​string​boolean · required
​string · required​integer · min: 1 · max: 10000 · required​string · required​string · required​string · enum · required​string · pattern: ​string​string​string​string · date-time​string​boolean · required​boolean · required
​string​string​integer · min: 1 · max: 10000​string · enum​string​string · enum​integer · min: 1 · max: 100
​string · required​string · required​integer · min: 1 · max: 10000 · required​string[] · minItems: 1 · maxItems: 20 · required​string · enum​string​string · enum​string · enum​string​string​string​string · date-time​string · date-time​string · date-time​string​boolean · required
​string · enum · required​string · required​string · required​string · enum · required​string​string · pattern: ​string · date-time​string · date-time​string · date-time​string​boolean · required
​string​integer · min: 1 · max: 10000​string​string · enum​integer · min: 1 · max: 100
​string · required​integer · min: 1 · max: 10000 · required​string · required​string​string​string · enum​string · enum​string​string · pattern: ​string · date-time​string · date-time​string
​string​string​string​integer · min: 1 · max: 100
​string · required​string · required​string · enum · required​string · required​string​string​integer · min: 1 · max: 10000​string · enum​string​string · date-time
​string​string​string​integer · min: 1 · max: 100
​string · required​string · required​integer · min: 1 · max: 10000​string​string​string​string · enum​string​string​boolean · required
​string · maxLength: 120 · required​string · enum · required​string · maxLength: 1000​boolean · required
List contracts visible to the end-user
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/contract-vault/my
List contracts visible to the end-user › Responses
200
Contract records and milestone state.
​ContractVaultSummary · required
​ContractVaultRecord[] · required
Query marketplace contract-vault records
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault
query Parameters
statusprogrammeNameopportunityRefpaymentControlStatusphoneendUserIdQuery marketplace contract-vault records › Responses
200
Contract records.
​ContractVaultSummary · required
​ContractVaultRecord[] · required
Create or update a marketplace contract-vault record
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault
Create or update a marketplace contract-vault record › Request Body
contractRefInstitution contract or procurement reference.
titlecounterpartyNameSupplier, contractor, or counterparty display name.
phoneWallet holder phone in E.164 format.
endUserIdWallet holder id.
programmeNameopportunityRefMarketplace opportunity, tender, or value-chain lot reference.
participantRoleEnum values:
buyer
supplier
contractor
verifier
funder
operator
statusEnum values:
pending_activation
active
in_progress
pending_review
funded
disbursing
completed
blocked
currencycontractValueMinormilestoneTotalmilestoneCompletednextMilestoneLabelnextMilestoneDueAtcontrolProfileEnum values:
standard
treasury_control
restricted_disbursement
evidence_required
paymentControlStatusEnum values:
not_started
awaiting_evidence
pending_approval
ready_to_disburse
disbursing
disbursed
blocked
anchoringStatusEnum values:
not_anchored
ready_to_anchor
anchored
failed
evidenceCountoneOf
Exactly one variant must match.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: phone | |
| type = object · requires: endUserId |
phoneWallet holder phone in E.164 format.
endUserIdWallet holder id.
contractRefInstitution contract or procurement reference.
titlecounterpartyNameSupplier, contractor, or counterparty display name.
programmeNameopportunityRefMarketplace opportunity, tender, or value-chain lot reference.
participantRoleEnum values:
buyer
supplier
contractor
verifier
funder
operator
statusEnum values:
pending_activation
active
in_progress
pending_review
funded
disbursing
completed
blocked
currencycontractValueMinormilestoneTotalmilestoneCompletednextMilestoneLabelnextMilestoneDueAtcontrolProfileEnum values:
standard
treasury_control
restricted_disbursement
evidence_required
paymentControlStatusEnum values:
not_started
awaiting_evidence
pending_approval
ready_to_disburse
disbursing
disbursed
blocked
anchoringStatusEnum values:
not_anchored
ready_to_anchor
anchored
failed
evidenceCountCreate or update a marketplace contract-vault record › Responses
200
Contract record stored.
success​ContractVaultRecord · required
List structured contract commitments
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/commitments
query Parameters
contractRefcommitmentRefcategorystatussourcelimitList structured contract commitments › Responses
200
Contract commitments.
​ContractCommitmentSummary · required
​ContractCommitment[] · required
Create or update a structured contract commitment
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/commitments
Create or update a structured contract commitment › Request Body
contractRefcommitmentReftitledescriptionClause, operational detail, or extracted text.
categoryEnum values:
deliverable
quantity
payment
compliance
reporting
other
unitLabelexpectedQuantitycompletedQuantitystatusEnum values:
pending
in_progress
satisfied
blocked
cancelled
verifierRefdueDatesourceEnum values:
manual
extracted
imported
extractionRefevidencePolicynotesCreate or update a structured contract commitment › Responses
200
Contract commitment stored.
success​ContractCommitment · required
List contract version proof metadata
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/versions
query Parameters
contractRefstatusisCurrentlimitList contract version proof metadata › Responses
200
Contract versions.
​ContractVersionSummary · required
​ContractVersion[] · required
Create or update contract version proof metadata
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/versions
Create or update contract version proof metadata › Request Body
contractRefversionNumbercontentHash^[A-Fa-f0-9]{64}$ · requiredtitlehashAlgorithmEnum values:
sha256
documentUristorageRefstatusEnum values:
draft
pending_signature
signed
superseded
voided
signatureStatusEnum values:
not_required
pending
partially_signed
signed
rejected
isCurrentsourceEnum values:
manual
upload
extracted
imported
extractionRefsignerSummary​object
notesCreate or update contract version proof metadata › Responses
200
Contract version metadata stored.
success​ContractVersion · required
Apply a provider-neutral proof anchoring event
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/versions/anchor-events
Records an append-only anchor event for a contract version proof and rolls the contract anchoring status forward. Concrete chain, vault, or notary adapters remain replaceable behind this boundary.
Apply a provider-neutral proof anchoring event › Request Body
contractRefversionNumberanchorRefprovideranchoringStatusEnum values:
not_anchored
ready_to_anchor
anchored
failed
contentHash^[A-Fa-f0-9]{64}$chainIdtransactionHashvaultRefoccurredAt​object
notesApply a provider-neutral proof anchoring event › Responses
200
Contract version anchoring event recorded.
successidempotent​object · required
​ContractEvent · required
​object · required
​ContractVersion · required
List external signature provider requests
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/signature-requests
query Parameters
requestRefcontractRefversionNumberproviderEnum values:
manual
provider_gateway
partner_api
wet_signature
qualified_electronic
providerRequestRefstatusEnum values:
requested
sent
viewed
completed
rejected
expired
cancelled
failed
limitList external signature provider requests › Responses
200
External signature provider requests.
​ContractSignatureProviderRequestSummary · required
​ContractSignatureProviderRequest[] · required
Create or update an external signature provider request
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/signature-requests
Create or update an external signature provider request › Request Body
requestRefcontractRefversionNumbersignerRefsproviderEnum values:
manual
provider_gateway
partner_api
wet_signature
qualified_electronic
Default: manual
providerRequestRefstatusEnum values:
requested
sent
viewed
completed
rejected
expired
cancelled
failed
Default: requested
channelEnum values:
email
sms
whatsapp
in_app
manual
Default: manual
titlesignerSummarycallbackUrlexpiresAtsentAtcompletedAt​object
notesCreate or update an external signature provider request › Responses
200
Signature provider request stored and version marked pending signature when applicable.
success​ContractSignatureProviderRequest · required
​object · required
Apply a signature provider callback or reconciliation event
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/signature-requests/provider-events
Updates an existing signature request by provider and providerRequestRef, records the signer receipt, rolls the linked contract version signature state forward, and appends contract history events.
Apply a signature provider callback or reconciliation event › Request Body
providerEnum values:
manual
provider_gateway
partner_api
wet_signature
qualified_electronic
providerRequestRefsignerRefstatusEnum values:
pending
sent
viewed
signed
rejected
expired
proofRefproofHash^[A-Fa-f0-9]{64}$occurredAtsignedAtrejectedAt​object
notesApply a signature provider callback or reconciliation event › Responses
200
Signature provider event applied.
success​ContractSignatureProviderRequest · required
​ContractSignature · required
​object · required
List contract signature ceremony receipts
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/signatures
query Parameters
contractRefversionNumbersignerRefstatusEnum values:
pending
sent
viewed
signed
rejected
expired
limitList contract signature ceremony receipts › Responses
200
Contract signature receipts.
​ContractSignatureSummary · required
​ContractSignature[] · required
Create or update a contract signature ceremony receipt
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/signatures
Create or update a contract signature ceremony receipt › Request Body
contractRefversionNumbersignerRefsignerRolesignerLabelstatusEnum values:
pending
sent
viewed
signed
rejected
expired
Default: pending
methodEnum values:
manual
otp
provider
wet_signature_upload
qualified_electronic
Default: manual
proofRefproofHash^[A-Fa-f0-9]{64}$signedAtrejectedAt​object
notesCreate or update a contract signature ceremony receipt › Responses
200
Contract signature receipt stored and version rollup recalculated.
List append-only contract history events
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/events
query Parameters
contractRefcommitmentRefeventTypelimitList append-only contract history events › Responses
200
Contract history events.
​ContractEventSummary · required
​ContractEvent[] · required
Append an idempotent contract history event
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/events
Append an idempotent contract history event › Request Body
contractRefeventRefeventTypeEnum values:
contract_recorded
version_recorded
signature_requested
signature_recorded
commitment_recorded
commitment_progressed
evidence_recorded
payment_control_recorded
titledescriptioncommitmentRefversionNumbersourceEnum values:
manual
system
extracted
imported
gateway
anchoring
actorRef​object
Small structured metadata. Do not include secrets.
occurredAtAppend an idempotent contract history event › Responses
200
Contract event appended or already present.
List contract extraction runs
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/extractions
query Parameters
contractRefextractionRefstatuslimitList contract extraction runs › Responses
200
Contract extraction runs.
​ContractExtractionSummary · required
​ContractExtraction[] · required
Store extractor output and proposed commitments
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/extractions
Store extractor output and proposed commitments › Request Body
contractRefextractionRefsourceVersionNumberdocumentUristorageRefengineRefstatusEnum values:
received
proposed
accepted
rejected
failed
summary​object
Small structured extractor metadata. Do not include secrets.
notes​ExtractedCommitmentInput[] · maxItems: 50
Store extractor output and proposed commitments › Responses
200
Contract extraction stored.
success​ContractExtraction · required
​ContractCommitment[] · required
Accept or reject a side-service extraction run
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/contract-vault/extractions/decisions
Accept or reject a side-service extraction run › Request Body
extractionRefstatusEnum values:
accepted
rejected
notesAccept or reject a side-service extraction run › Responses
200
Contract extraction decision recorded.
success​ContractExtraction · required
​ContractCommitment[] · required