HeritagePay API
​string · enum​string​integer · min: 1 · max: 100
​string · required​string · required​string​string · enum​boolean · required
​string · enum​string​string​integer · min: 1 · max: 100
​string · required​string · required​string​string​string​string​string​integer · min: 0​string · enum​boolean · required
​string · enum​string · enum​string​integer · min: 1 · max: 100
​string · required​string · required​string · enum​string · enum​string​string · email​string​string​boolean · required
​string​string​string · enum​string · enum​integer · min: 1 · max: 100
​string · required​string · required​string · enum​string · enum​string​boolean · required
​string​string​string​string · enum​integer · min: 1 · max: 100
​string · required​string · required​string · required​string​integer · min: 1 · max: 1000​integer · min: 0 · max: 1000​string · enum​boolean​string​string · date​string​boolean · required
​string​string​string​string · enum​string · enum​string · enum​string · enum​integer · min: 1 · max: 100
​string · required​string · required​string · required​string​string · enum​string​string · pattern: ​string​string · enum​string​integer · min: 0 · max: 2147483647​string · enum​string · enum​string · enum​string · enum​string​string​string​boolean · required
​string​string​string​string · enum​string · enum​integer · min: 1 · max: 100
​string · required​string · required​integer · min: 0 · required​string · required​string​string​string​string · enum​string · enum​string​string​string​string​boolean · required
​string​string​string · enum​string​string · enum​integer · min: 1 · max: 100
​string · maxLength: 100 · required​string · maxLength: 80 · required​string · enum​string · maxLength: 160​string · enum​integer · min: 1 · max: 100​string · maxLength: 80​string · maxLength: 1000​string · date-time​string · date-time​string · date-time​string · maxLength: 1000
​string · enum · required​string · maxLength: 160 · required​string · enum · required​string · maxLength: 80​string · maxLength: 1000​string · date-time​string · date-time​string · date-time​string · date-time​string · maxLength: 1000
​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 marketplace programmes
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/programmes
query Parameters
statusEnum values:
draft
active
paused
completed
cancelled
programmeReflimitDefault: 50
List marketplace programmes › Responses
200
Marketplace programmes.
​MarketplaceProgramme[] · required
Create or update a marketplace programme
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/programmes
Create or update a marketplace programme › Request Body
programmeRefnamedescriptionstatusEnum values:
draft
active
paused
completed
cancelled
Default: draft
Create or update a marketplace programme › Responses
Programme stored.
success​MarketplaceProgramme · required
List marketplace opportunities
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/opportunities
query Parameters
statusEnum values:
draft
open
assigned
in_progress
completed
cancelled
programmeRefopportunityReflimitDefault: 50
List marketplace opportunities › Responses
200
Marketplace opportunities.
​MarketplaceOpportunity[] · required
Create or update a marketplace opportunity
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/opportunities
Create or update a marketplace opportunity › Request Body
opportunityReftitleprogrammeRefdescriptionbuyerNamelocationcurrencyestimatedValueMinorstatusEnum values:
draft
open
assigned
in_progress
completed
cancelled
Default: draft
Create or update a marketplace opportunity › Responses
Opportunity stored.
success​MarketplaceOpportunity · required
List marketplace participants
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/participants
query Parameters
roleEnum values:
buyer
supplier
contractor
verifier
funder
operator
statusEnum values:
draft
active
suspended
archived
participantReflimitDefault: 50
List marketplace participants › Responses
200
Marketplace participants.
​MarketplaceParticipant[] · required
Create or update a marketplace participant
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/participants
Create or update a marketplace participant › Request Body
participantRefdisplayNameroleEnum values:
buyer
supplier
contractor
verifier
funder
operator
Default: supplier
statusEnum values:
draft
active
suspended
archived
Default: draft
walletPhonecontactEmailcountryIso2notesCreate or update a marketplace participant › Responses
Participant stored.
success​MarketplaceParticipant · required
List marketplace opportunity assignments
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/assignments
query Parameters
opportunityRefparticipantRefroleEnum values:
supplier
contractor
verifier
funder
operator
statusEnum values:
proposed
assigned
accepted
declined
cancelled
completed
limitDefault: 50
List marketplace opportunity assignments › Responses
200
Marketplace opportunity assignments.
​MarketplaceAssignment[] · required
Assign a marketplace participant to an opportunity
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/assignments
Assign a marketplace participant to an opportunity › Request Body
opportunityRefparticipantRefroleEnum values:
supplier
contractor
verifier
funder
operator
Default: supplier
statusEnum values:
proposed
assigned
accepted
declined
cancelled
completed
Default: assigned
notesAssign a marketplace participant to an opportunity › Responses
Assignment stored.
success​MarketplaceAssignment · required
List marketplace milestones
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/milestones
query Parameters
opportunityRefcontractRefmilestoneRefstatusEnum values:
planned
in_progress
pending_review
approved
rejected
completed
blocked
limitDefault: 50
List marketplace milestones › Responses
200
Marketplace milestones.
​MarketplaceMilestone[] · required
Create or update a marketplace milestone
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/milestones
Create or update a marketplace milestone › Request Body
milestoneRefopportunityReftitlecontractRefexpectedCountDefault: 1
completedCountDefault: 0
statusEnum values:
planned
in_progress
pending_review
approved
rejected
completed
blocked
Default: planned
evidenceRequiredDefault: true
paymentRuledueDatenotesCreate or update a marketplace milestone › Responses
Milestone stored.
success​MarketplaceMilestone · required
List marketplace milestone evidence
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/evidence
query Parameters
milestoneRefparticipantRefevidenceRefevidenceTypeEnum values:
photo
pdf
report
receipt
note
other
statusEnum values:
submitted
under_review
approved
rejected
attachmentStatusEnum values:
referenced
uploaded
verified
missing
storageProviderEnum values:
vault
object_storage
signed_url
partner
manual
limitDefault: 50
List marketplace milestone evidence › Responses
200
Marketplace evidence rows.
​MarketplaceEvidence[] · required
Create, update, or review milestone evidence
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/evidence
Create, update, or review milestone evidence › Request Body
evidenceRefmilestoneReftitleparticipantRefevidenceTypeEnum values:
photo
pdf
report
receipt
note
other
Default: other
uriVault, object storage, signed URL, or partner evidence reference.
checksumSha256^[a-fA-F0-9]{64}$contentTypestorageProviderEnum values:
vault
object_storage
signed_url
partner
manual
Default: vault
objectKeyObject key or vault path without credentials.
byteSizeattachmentStatusEnum values:
referenced
uploaded
verified
missing
Default: referenced
visibilityEnum values:
operator_only
participant_visible
wallet_holder_visible
Default: operator_only
retentionPolicyEnum values:
standard
contract_lifetime
regulatory_hold
delete_after_review
Default: standard
statusEnum values:
submitted
under_review
approved
rejected
Default: submitted
notesreviewNoterejectionReasonRequired when status is rejected.
Create, update, or review milestone evidence › Responses
Evidence stored.
success​MarketplaceEvidence · required
List marketplace payment-control instructions
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/payment-controls
query Parameters
controlRefmilestoneRefevidenceRefstatusEnum values:
draft
release_eligible
pending_approval
approved
submitted
settled
failed
blocked
railEnum values:
wallet
mobile_money
bank
manual
other
limitDefault: 50
List marketplace payment-control instructions › Responses
200
Marketplace payment-control instructions.
​MarketplacePaymentControl[] · required
Create or update a marketplace payment control
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/payment-controls
Records controlled payment intent and approval state. This endpoint does not execute a money transfer by itself.
Create or update a marketplace payment control › Request Body
controlRefmilestoneRefamountMinorcurrencyevidenceRefApproved evidence reference backing release eligibility.
contractRefbeneficiaryParticipantRefrailEnum values:
wallet
mobile_money
bank
manual
other
Default: manual
statusEnum values:
draft
release_eligible
pending_approval
approved
submitted
settled
failed
blocked
Default: draft
approvalNoterejectionReasonexternalReferencenotesCreate or update a marketplace payment control › Responses
Payment control stored.
success​MarketplacePaymentControl · required
List marketplace payment execution attempts
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/payment-executions
Lists provider or gateway handoff attempts linked to approved payment-control instructions.
query Parameters
executionRefcontrolRefproviderEnum values:
wallet_gateway
mobile_money_gateway
bank_gateway
blnk
manual
partner
providerExecutionRefstatusEnum values:
queued
submitted
settled
failed
cancelled
manual_review
limitDefault: 50
List marketplace payment execution attempts › Responses
200
Marketplace payment execution attempts.
​MarketplacePaymentExecution[] · required
Create or update a marketplace payment execution attempt
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/payment-executions
Records provider-neutral execution state for an approved payment control. This is the traceable handoff boundary; concrete gateway callbacks and live settlement adapters remain replaceable modules.
Create or update a marketplace payment execution attempt › Request Body
executionRefcontrolRefproviderEnum values:
wallet_gateway
mobile_money_gateway
bank_gateway
blnk
manual
partner
Default: manual
providerExecutionRefExternal gateway or provider execution id when available.
statusEnum values:
queued
submitted
settled
failed
cancelled
manual_review
Default: queued
attemptNumberDefault: 1
responseCoderesponseMessageProvider-safe response message. Do not include secrets or raw PII.
submittedAtsettledAtfailedAt​object
Small safe metadata object. Do not include secrets.
notesCreate or update a marketplace payment execution attempt › Responses
Payment execution stored.
Apply a provider callback or reconciliation event
POST
https://sandbox-heritagepay-api.paypm.net/api/v1
/internal/marketplace/payment-executions/provider-events
Updates an existing marketplace payment execution by provider and providerExecutionRef, then rolls the linked payment-control status forward and appends the contract timeline event when the control is contract-backed.
Apply a provider callback or reconciliation event › Request Body
providerProvider that emitted the callback or reconciliation result.
Enum values:
wallet_gateway
mobile_money_gateway
bank_gateway
blnk
manual
partner
providerExecutionRefExternal provider execution id already stored on a marketplace payment execution.
statusProvider state to apply to the existing execution.
Enum values:
queued
submitted
settled
failed
cancelled
manual_review
responseCoderesponseMessageProvider-safe response detail. Do not include secrets or raw PII.
occurredAtTimestamp supplied by the provider or reconciliation run.
submittedAtsettledAtfailedAt​object
Small safe metadata object. Do not include secrets.
notesApply a provider callback or reconciliation event › Responses
Provider event applied to the payment execution.
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