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
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.