PayPM Platform 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 open opportunities and assignments visible to the end-user
GET
https://sandbox-heritagepay-api.paypm.net/api/v1
/marketplace/my
Resolves the authenticated wallet phone to one active marketplace participant inside the JWT business entity. Ambiguous or absent participant links return no assignments. Open opportunities remain browseable and assigned opportunities are not duplicated.
List open opportunities and assignments visible to the end-user › Responses
End-user marketplace read model.
​required
​MarketplaceOpportunity[] · required
​MarketplaceAssignmentWithOpportunity[] · 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.