Marketplace

Server

Compatibility residue — not a live Wallet consumer contract

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/marketplace/my

Wallet GET /marketplace/my remains on the wallet host as compatibility residue. Wallet mobile is money-only: it does not mount a Marketplace tab and does not advertise this route as a customer contract.

When called, it resolves the authenticated wallet phone to one active marketplace participant inside the JWT business entity. Ambiguous or absent participant links return no assignments.

Business mobile and the Marketplace SPA live-read standalone GET /api/v1/marketplace/my on the Marketplace product host. Operator writes stay on wallet Plane B (/internal/marketplace/*). Do not invent a Marketplace write API.

Compatibility residue — not a live Wallet consumer contract › Responses

Compatibility residue read model. Not a live Wallet consumer contract.

MarketplaceMineResponse

required

MarketplaceOpportunity[] · required

MarketplaceAssignmentWithOpportunity[] · required

GET/marketplace/my

curl https://sandbox-heritagepay-api.paypm.net/api/v1/marketplace/my \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "participant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "participantRef": "participantRef",
    "displayName": "displayName",
    "role": "role",
    "status": "status",
    "walletPhone": "walletPhone",
    "contactEmail": "contactEmail",
    "countryIso2": "countryIso2",
    "notes": "notes",
    "assignable": true,
    "isActive": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  },
  "openOpportunities": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "opportunityRef": "opportunityRef",
      "programmeRef": "programmeRef",
      "title": "title",
      "description": "description",
      "buyerName": "buyerName",
      "location": "location",
      "currency": "currency",
      "estimatedValueMinor": 0,
      "status": "status",
      "isActive": true,
      "contractable": true,
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ],
  "assignments": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "opportunityRef": "opportunityRef",
      "participantRef": "participantRef",
      "role": "role",
      "status": "status",
      "notes": "notes",
      "assignedAt": "2024-08-25T15:00:00Z",
      "locksOpportunity": true,
      "isActive": true,
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z",
      "opportunity": {
        "id": "00000000-0000-0000-0000-000000000000",
        "opportunityRef": "opportunityRef",
        "programmeRef": "programmeRef",
        "title": "title",
        "description": "description",
        "buyerName": "buyerName",
        "location": "location",
        "currency": "currency",
        "estimatedValueMinor": 0,
        "status": "status",
        "isActive": true,
        "contractable": true,
        "createdAt": "2024-08-25T15:00:00Z",
        "updatedAt": "2024-08-25T15:00:00Z"
      }
    }
  ]
}

json

application/json

List marketplace programmes

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/internal/marketplace/programmes

List marketplace programmes › query Parameters

status

string · enum

Enum values:

draft

active

paused

completed

cancelled

programmeRef

string

limit

integer · min: 1 · max: 100

Default: 50

List marketplace programmes › Responses

200

Marketplace programmes.

MarketplaceProgrammeListResponse

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

MarketplaceProgrammeRequest

programmeRef

string · required

name

string · required

description

string

status

string · enum

Enum values:

draft

active

paused

completed

cancelled

Default: draft

Create or update a marketplace programme › Responses

Programme stored.

success

boolean · required

MarketplaceProgramme · required

POST/internal/marketplace/programmes

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/programmes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "programmeRef": "PRG-CIV-RESTAURANTS-2026",
  "name": "Youth Restaurant Buildout",
  "description": "description",
  "status": "draft"
}'

Example Request Body

{
  "programmeRef": "PRG-CIV-RESTAURANTS-2026",
  "name": "Youth Restaurant Buildout",
  "description": "description",
  "status": "draft"
}

json

Example Responses

{
  "success": true,
  "programme": {
    "id": "00000000-0000-0000-0000-000000000000",
    "programmeRef": "programmeRef",
    "name": "name",
    "description": "description",
    "status": "status",
    "isActive": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List marketplace opportunities

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/internal/marketplace/opportunities

List marketplace opportunities › query Parameters

status

string · enum

Enum values:

draft

open

assigned

in_progress

completed

cancelled

programmeRef

string

opportunityRef

string

limit

integer · min: 1 · max: 100

Default: 50

List marketplace opportunities › Responses

200

Marketplace opportunities.

MarketplaceOpportunityListResponse

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

MarketplaceOpportunityRequest

opportunityRef

string · required

title

string · required

programmeRef

string

description

string

buyerName

string

location

string

currency

string

estimatedValueMinor

integer · min: 0

status

string · enum

Enum values:

draft

open

assigned

in_progress

completed

cancelled

Default: draft

Create or update a marketplace opportunity › Responses

Opportunity stored.

success

boolean · required

MarketplaceOpportunity · required

POST/internal/marketplace/opportunities

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/opportunities \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "opportunityRef": "OPP-CIV-RESTAURANTS-2026",
  "programmeRef": "PRG-CIV-RESTAURANTS-2026",
  "title": "Build 5 restaurants in Abidjan",
  "description": "description",
  "buyerName": "buyerName",
  "location": "Abidjan",
  "currency": "XOF",
  "estimatedValueMinor": 0,
  "status": "draft"
}'

Example Request Body

{
  "opportunityRef": "OPP-CIV-RESTAURANTS-2026",
  "programmeRef": "PRG-CIV-RESTAURANTS-2026",
  "title": "Build 5 restaurants in Abidjan",
  "description": "description",
  "buyerName": "buyerName",
  "location": "Abidjan",
  "currency": "XOF",
  "estimatedValueMinor": 0,
  "status": "draft"
}

json

Example Responses

{
  "success": true,
  "opportunity": {
    "id": "00000000-0000-0000-0000-000000000000",
    "opportunityRef": "opportunityRef",
    "programmeRef": "programmeRef",
    "title": "title",
    "description": "description",
    "buyerName": "buyerName",
    "location": "location",
    "currency": "currency",
    "estimatedValueMinor": 0,
    "status": "status",
    "isActive": true,
    "contractable": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List marketplace participants

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/internal/marketplace/participants

List marketplace participants › query Parameters

role

string · enum

Enum values:

buyer

supplier

contractor

verifier

funder

operator

status

string · enum

Enum values:

draft

active

suspended

archived

participantRef

string

limit

integer · min: 1 · max: 100

Default: 50

List marketplace participants › Responses

200

Marketplace participants.

MarketplaceParticipantListResponse

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

MarketplaceParticipantRequest

participantRef

string · required

displayName

string · required

role

string · enum

Enum values:

buyer

supplier

contractor

verifier

funder

operator

Default: supplier

status

string · enum

Enum values:

draft

active

suspended

archived

Default: draft

walletPhone

string

contactEmail

string · email

countryIso2

string

notes

string

Create or update a marketplace participant › Responses

Participant stored.

success

boolean · required

MarketplaceParticipant · required

POST/internal/marketplace/participants

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/participants \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "participantRef": "SUP-CI-BEN-OUATTARA",
  "displayName": "Ben Ouattara SARL",
  "role": "supplier",
  "status": "draft",
  "walletPhone": "+2250748805663",
  "contactEmail": "test@example.com",
  "countryIso2": "CI",
  "notes": "notes"
}'

Example Request Body

{
  "participantRef": "SUP-CI-BEN-OUATTARA",
  "displayName": "Ben Ouattara SARL",
  "role": "supplier",
  "status": "draft",
  "walletPhone": "+2250748805663",
  "contactEmail": "test@example.com",
  "countryIso2": "CI",
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "participant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "participantRef": "participantRef",
    "displayName": "displayName",
    "role": "role",
    "status": "status",
    "walletPhone": "walletPhone",
    "contactEmail": "contactEmail",
    "countryIso2": "countryIso2",
    "notes": "notes",
    "assignable": true,
    "isActive": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List marketplace opportunity assignments

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/internal/marketplace/assignments

List marketplace opportunity assignments › query Parameters

opportunityRef

string

participantRef

string

role

string · enum

Enum values:

supplier

contractor

verifier

funder

operator

status

string · enum

Enum values:

proposed

assigned

accepted

declined

cancelled

completed

limit

integer · min: 1 · max: 100

Default: 50

List marketplace opportunity assignments › Responses

200

Marketplace opportunity assignments.

MarketplaceAssignmentListResponse

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

MarketplaceAssignmentRequest

opportunityRef

string · required

participantRef

string · required

role

string · enum

Enum values:

supplier

contractor

verifier

funder

operator

Default: supplier

status

string · enum

Enum values:

proposed

assigned

accepted

declined

cancelled

completed

Default: assigned

notes

string

Assign a marketplace participant to an opportunity › Responses

Assignment stored.

success

boolean · required

MarketplaceAssignment · required

POST/internal/marketplace/assignments

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/assignments \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "opportunityRef": "OPP-CIV-RESTAURANTS-2026",
  "participantRef": "SUP-CI-BEN-OUATTARA",
  "role": "supplier",
  "status": "assigned",
  "notes": "notes"
}'

Example Request Body

{
  "opportunityRef": "OPP-CIV-RESTAURANTS-2026",
  "participantRef": "SUP-CI-BEN-OUATTARA",
  "role": "supplier",
  "status": "assigned",
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "assignment": {
    "id": "00000000-0000-0000-0000-000000000000",
    "opportunityRef": "opportunityRef",
    "participantRef": "participantRef",
    "role": "role",
    "status": "status",
    "notes": "notes",
    "assignedAt": "2024-08-25T15:00:00Z",
    "locksOpportunity": true,
    "isActive": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List marketplace milestones

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/internal/marketplace/milestones

List marketplace milestones › query Parameters

opportunityRef

string

contractRef

string

milestoneRef

string

status

string · enum

Enum values:

planned

in_progress

pending_review

approved

rejected

completed

blocked

limit

integer · min: 1 · max: 100

Default: 50

List marketplace milestones › Responses

200

Marketplace milestones.

MarketplaceMilestoneListResponse

MarketplaceMilestone[] · required

GET/internal/marketplace/milestones

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/milestones \
  --header 'X-Plug-Wallet-Api-Key: <api-key>'

Example Responses

{
  "milestones": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "milestoneRef": "milestoneRef",
      "opportunityRef": "opportunityRef",
      "contractRef": "contractRef",
      "title": "title",
      "expectedCount": 0,
      "completedCount": 0,
      "progressLabel": "0/5",
      "status": "status",
      "evidenceRequired": true,
      "paymentRule": "paymentRule",
      "dueDate": "2024-08-25",
      "notes": "notes",
      "readyForReview": true,
      "isActive": true,
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

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

MarketplaceMilestoneRequest

milestoneRef

string · required

opportunityRef

string · required

title

string · required

contractRef

string

expectedCount

integer · min: 1 · max: 1000

Default: 1

completedCount

integer · min: 0 · max: 1000

Default: 0

status

string · enum

Enum values:

planned

in_progress

pending_review

approved

rejected

completed

blocked

Default: planned

evidenceRequired

boolean

Default: true

paymentRule

string

dueDate

string · date

notes

string

Create or update a marketplace milestone › Responses

Milestone stored.

success

boolean · required

MarketplaceMilestone · required

POST/internal/marketplace/milestones

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/milestones \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "milestoneRef": "MS-CIV-REST-FOUNDATION",
  "opportunityRef": "OPP-CIV-RESTAURANTS-2026",
  "contractRef": "CIV-REST-2026-001",
  "title": "Foundation approved",
  "expectedCount": 1,
  "completedCount": 0,
  "status": "planned",
  "evidenceRequired": true,
  "paymentRule": "paymentRule",
  "dueDate": "2024-08-25",
  "notes": "notes"
}'

Example Request Body

{
  "milestoneRef": "MS-CIV-REST-FOUNDATION",
  "opportunityRef": "OPP-CIV-RESTAURANTS-2026",
  "contractRef": "CIV-REST-2026-001",
  "title": "Foundation approved",
  "expectedCount": 1,
  "completedCount": 0,
  "status": "planned",
  "evidenceRequired": true,
  "paymentRule": "paymentRule",
  "dueDate": "2024-08-25",
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "milestone": {
    "id": "00000000-0000-0000-0000-000000000000",
    "milestoneRef": "milestoneRef",
    "opportunityRef": "opportunityRef",
    "contractRef": "contractRef",
    "title": "title",
    "expectedCount": 0,
    "completedCount": 0,
    "progressLabel": "0/5",
    "status": "status",
    "evidenceRequired": true,
    "paymentRule": "paymentRule",
    "dueDate": "2024-08-25",
    "notes": "notes",
    "readyForReview": true,
    "isActive": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List marketplace milestone evidence

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/internal/marketplace/evidence

List marketplace milestone evidence › query Parameters

milestoneRef

string

participantRef

string

evidenceRef

string

evidenceType

string · enum

Enum values:

photo

pdf

report

receipt

note

other

status

string · enum

Enum values:

submitted

under_review

approved

rejected

attachmentStatus

string · enum

Enum values:

referenced

uploaded

verified

missing

storageProvider

string · enum

Enum values:

vault

object_storage

signed_url

partner

manual

limit

integer · min: 1 · max: 100

Default: 50

List marketplace milestone evidence › Responses

200

Marketplace evidence rows.

MarketplaceEvidenceListResponse

MarketplaceEvidence[] · required

GET/internal/marketplace/evidence

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/evidence \
  --header 'X-Plug-Wallet-Api-Key: <api-key>'

Example Responses

{
  "evidence": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "evidenceRef": "evidenceRef",
      "milestoneRef": "milestoneRef",
      "participantRef": "participantRef",
      "evidenceType": "evidenceType",
      "title": "title",
      "uri": "uri",
      "checksumSha256": "checksumSha256",
      "contentType": "contentType",
      "storageProvider": "storageProvider",
      "objectKey": "objectKey",
      "byteSize": 0,
      "attachmentStatus": "attachmentStatus",
      "visibility": "visibility",
      "retentionPolicy": "retentionPolicy",
      "verifiedAt": "2024-08-25T15:00:00Z",
      "status": "status",
      "notes": "notes",
      "reviewNote": "reviewNote",
      "rejectionReason": "rejectionReason",
      "reviewedAt": "2024-08-25T15:00:00Z",
      "reviewClosed": true,
      "isActive": true,
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

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

MarketplaceEvidenceRequest

evidenceRef

string · required

milestoneRef

string · required

title

string · required

participantRef

string

evidenceType

string · enum

Enum values:

photo

pdf

report

receipt

note

other

Default: other

uri

string

Vault, object storage, signed URL, or partner evidence reference.

checksumSha256

string · pattern: ^[a-fA-F0-9]{64}$

contentType

string

storageProvider

string · enum

Enum values:

vault

object_storage

signed_url

partner

manual

Default: vault

objectKey

string

Object key or vault path without credentials.

byteSize

integer · min: 0 · max: 2147483647

attachmentStatus

string · enum

Enum values:

referenced

uploaded

verified

missing

Default: referenced

visibility

string · enum

Enum values:

operator_only

participant_visible

wallet_holder_visible

Default: operator_only

retentionPolicy

string · enum

Enum values:

standard

contract_lifetime

regulatory_hold

delete_after_review

Default: standard

status

string · enum

Enum values:

submitted

under_review

approved

rejected

Default: submitted

notes

string

reviewNote

string

rejectionReason

string

Required when status is rejected.

Create, update, or review milestone evidence › Responses

Evidence stored.

success

boolean · required

MarketplaceEvidence · required

POST/internal/marketplace/evidence

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/evidence \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "evidenceRef": "EVD-CIV-REST-FOUNDATION-PHOTO-001",
  "milestoneRef": "MS-CIV-REST-FOUNDATION",
  "participantRef": "SUP-CI-BEN-OUATTARA",
  "evidenceType": "other",
  "title": "Foundation photos and site report",
  "uri": "vault://contracts/CIV-REST-2026/evidence/001",
  "checksumSha256": "checksumSha256",
  "contentType": "application/pdf",
  "storageProvider": "vault",
  "objectKey": "contracts/CIV-REST-2026/evidence/001.jpg",
  "byteSize": 0,
  "attachmentStatus": "referenced",
  "visibility": "operator_only",
  "retentionPolicy": "standard",
  "status": "submitted",
  "notes": "notes",
  "reviewNote": "reviewNote",
  "rejectionReason": "rejectionReason"
}'

Example Request Body

{
  "evidenceRef": "EVD-CIV-REST-FOUNDATION-PHOTO-001",
  "milestoneRef": "MS-CIV-REST-FOUNDATION",
  "participantRef": "SUP-CI-BEN-OUATTARA",
  "evidenceType": "other",
  "title": "Foundation photos and site report",
  "uri": "vault://contracts/CIV-REST-2026/evidence/001",
  "checksumSha256": "checksumSha256",
  "contentType": "application/pdf",
  "storageProvider": "vault",
  "objectKey": "contracts/CIV-REST-2026/evidence/001.jpg",
  "byteSize": 0,
  "attachmentStatus": "referenced",
  "visibility": "operator_only",
  "retentionPolicy": "standard",
  "status": "submitted",
  "notes": "notes",
  "reviewNote": "reviewNote",
  "rejectionReason": "rejectionReason"
}

json

Example Responses

{
  "success": true,
  "evidence": {
    "id": "00000000-0000-0000-0000-000000000000",
    "evidenceRef": "evidenceRef",
    "milestoneRef": "milestoneRef",
    "participantRef": "participantRef",
    "evidenceType": "evidenceType",
    "title": "title",
    "uri": "uri",
    "checksumSha256": "checksumSha256",
    "contentType": "contentType",
    "storageProvider": "storageProvider",
    "objectKey": "objectKey",
    "byteSize": 0,
    "attachmentStatus": "attachmentStatus",
    "visibility": "visibility",
    "retentionPolicy": "retentionPolicy",
    "verifiedAt": "2024-08-25T15:00:00Z",
    "status": "status",
    "notes": "notes",
    "reviewNote": "reviewNote",
    "rejectionReason": "rejectionReason",
    "reviewedAt": "2024-08-25T15:00:00Z",
    "reviewClosed": true,
    "isActive": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

List marketplace payment-control instructions

GET

https://sandbox-heritagepay-api.paypm.net/api/v1

/internal/marketplace/payment-controls

List marketplace payment-control instructions › query Parameters

controlRef

string

milestoneRef

string

evidenceRef

string

status

string · enum

Enum values:

draft

release_eligible

pending_approval

approved

submitted

settled

failed

blocked

rail

string · enum

Enum values:

wallet

mobile_money

bank

manual

other

limit

integer · min: 1 · max: 100

Default: 50

List marketplace payment-control instructions › Responses

200

Marketplace payment-control instructions.

MarketplacePaymentControlListResponse

MarketplacePaymentControl[] · required

GET/internal/marketplace/payment-controls

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/payment-controls \
  --header 'X-Plug-Wallet-Api-Key: <api-key>'

Example Responses

{
  "paymentControls": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "controlRef": "controlRef",
      "milestoneRef": "milestoneRef",
      "evidenceRef": "evidenceRef",
      "contractRef": "contractRef",
      "beneficiaryParticipantRef": "beneficiaryParticipantRef",
      "amountMinor": 0,
      "currency": "currency",
      "rail": "rail",
      "status": "status",
      "approvalNote": "approvalNote",
      "rejectionReason": "rejectionReason",
      "externalReference": "externalReference",
      "approvedAt": "2024-08-25T15:00:00Z",
      "submittedAt": "2024-08-25T15:00:00Z",
      "settledAt": "2024-08-25T15:00:00Z",
      "notes": "notes",
      "executionApproved": true,
      "terminal": true,
      "isActive": true,
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

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

MarketplacePaymentControlRequest

controlRef

string · required

milestoneRef

string · required

amountMinor

integer · min: 0 · required

currency

string · required

evidenceRef

string

Approved evidence reference backing release eligibility.

contractRef

string

beneficiaryParticipantRef

string

rail

string · enum

Enum values:

wallet

mobile_money

bank

manual

other

Default: manual

status

string · enum

Enum values:

draft

release_eligible

pending_approval

approved

submitted

settled

failed

blocked

Default: draft

approvalNote

string

rejectionReason

string

externalReference

string

notes

string

Create or update a marketplace payment control › Responses

Payment control stored.

success

boolean · required

MarketplacePaymentControl · required

POST/internal/marketplace/payment-controls

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/payment-controls \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "controlRef": "PAY-CIV-REST-FOUNDATION-001",
  "milestoneRef": "MS-CIV-REST-FOUNDATION",
  "evidenceRef": "EVD-CIV-REST-FOUNDATION-PHOTO-001",
  "contractRef": "CIV-REST-2026-001",
  "beneficiaryParticipantRef": "SUP-CI-BEN-OUATTARA",
  "amountMinor": 2500000,
  "currency": "XOF",
  "rail": "manual",
  "status": "draft",
  "approvalNote": "approvalNote",
  "rejectionReason": "rejectionReason",
  "externalReference": "externalReference",
  "notes": "notes"
}'

Example Request Body

{
  "controlRef": "PAY-CIV-REST-FOUNDATION-001",
  "milestoneRef": "MS-CIV-REST-FOUNDATION",
  "evidenceRef": "EVD-CIV-REST-FOUNDATION-PHOTO-001",
  "contractRef": "CIV-REST-2026-001",
  "beneficiaryParticipantRef": "SUP-CI-BEN-OUATTARA",
  "amountMinor": 2500000,
  "currency": "XOF",
  "rail": "manual",
  "status": "draft",
  "approvalNote": "approvalNote",
  "rejectionReason": "rejectionReason",
  "externalReference": "externalReference",
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "paymentControl": {
    "id": "00000000-0000-0000-0000-000000000000",
    "controlRef": "controlRef",
    "milestoneRef": "milestoneRef",
    "evidenceRef": "evidenceRef",
    "contractRef": "contractRef",
    "beneficiaryParticipantRef": "beneficiaryParticipantRef",
    "amountMinor": 0,
    "currency": "currency",
    "rail": "rail",
    "status": "status",
    "approvalNote": "approvalNote",
    "rejectionReason": "rejectionReason",
    "externalReference": "externalReference",
    "approvedAt": "2024-08-25T15:00:00Z",
    "submittedAt": "2024-08-25T15:00:00Z",
    "settledAt": "2024-08-25T15:00:00Z",
    "notes": "notes",
    "executionApproved": true,
    "terminal": true,
    "isActive": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

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.

List marketplace payment execution attempts › query Parameters

executionRef

string

controlRef

string

provider

string · enum

Enum values:

wallet_gateway

mobile_money_gateway

bank_gateway

blnk

manual

partner

providerExecutionRef

string

status

string · enum

Enum values:

queued

submitted

settled

failed

cancelled

manual_review

limit

integer · min: 1 · max: 100

Default: 50

List marketplace payment execution attempts › Responses

200

Marketplace payment execution attempts.

MarketplacePaymentExecutionListResponse

MarketplacePaymentExecution[] · required

GET/internal/marketplace/payment-executions

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/payment-executions \
  --header 'X-Plug-Wallet-Api-Key: <api-key>'

Example Responses

{
  "paymentExecutions": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "executionRef": "executionRef",
      "controlRef": "controlRef",
      "provider": "provider",
      "providerExecutionRef": "providerExecutionRef",
      "status": "status",
      "attemptNumber": 0,
      "amountMinor": 0,
      "currency": "currency",
      "responseCode": "responseCode",
      "responseMessage": "responseMessage",
      "submittedAt": "2024-08-25T15:00:00Z",
      "settledAt": "2024-08-25T15:00:00Z",
      "failedAt": "2024-08-25T15:00:00Z",
      "metadata": {},
      "notes": "notes",
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

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

MarketplacePaymentExecutionRequest

executionRef

string · maxLength: 100 · required

controlRef

string · maxLength: 80 · required

provider

string · enum

Enum values:

wallet_gateway

mobile_money_gateway

bank_gateway

blnk

manual

partner

Default: manual

providerExecutionRef

string · maxLength: 160

External gateway or provider execution id when available.

status

string · enum

Enum values:

queued

submitted

settled

failed

cancelled

manual_review

Default: queued

attemptNumber

integer · min: 1 · max: 100

Default: 1

responseCode

string · maxLength: 80

responseMessage

string · maxLength: 1000

Provider-safe response message. Do not include secrets or raw PII.

submittedAt

string · date-time

settledAt

string · date-time

failedAt

string · date-time

object

Small safe metadata object. Do not include secrets.

notes

string · maxLength: 1000

Create or update a marketplace payment execution attempt › Responses

Payment execution stored.

success

boolean · required

MarketplacePaymentExecution · required

object · required

POST/internal/marketplace/payment-executions

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/payment-executions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "executionRef": "EXEC-CIV-REST-FOUNDATION-001",
  "controlRef": "PAY-CIV-REST-FOUNDATION-001",
  "provider": "manual",
  "providerExecutionRef": "gateway:payment:123",
  "status": "queued",
  "attemptNumber": 1,
  "responseCode": "ACCEPTED",
  "responseMessage": "responseMessage",
  "submittedAt": "2024-08-25T15:00:00Z",
  "settledAt": "2024-08-25T15:00:00Z",
  "failedAt": "2024-08-25T15:00:00Z",
  "metadata": {},
  "notes": "notes"
}'

Example Request Body

{
  "executionRef": "EXEC-CIV-REST-FOUNDATION-001",
  "controlRef": "PAY-CIV-REST-FOUNDATION-001",
  "provider": "manual",
  "providerExecutionRef": "gateway:payment:123",
  "status": "queued",
  "attemptNumber": 1,
  "responseCode": "ACCEPTED",
  "responseMessage": "responseMessage",
  "submittedAt": "2024-08-25T15:00:00Z",
  "settledAt": "2024-08-25T15:00:00Z",
  "failedAt": "2024-08-25T15:00:00Z",
  "metadata": {},
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "paymentExecution": {
    "id": "00000000-0000-0000-0000-000000000000",
    "executionRef": "executionRef",
    "controlRef": "controlRef",
    "provider": "provider",
    "providerExecutionRef": "providerExecutionRef",
    "status": "status",
    "attemptNumber": 0,
    "amountMinor": 0,
    "currency": "currency",
    "responseCode": "responseCode",
    "responseMessage": "responseMessage",
    "submittedAt": "2024-08-25T15:00:00Z",
    "settledAt": "2024-08-25T15:00:00Z",
    "failedAt": "2024-08-25T15:00:00Z",
    "metadata": {},
    "notes": "notes",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  },
  "paymentControl": {
    "controlRef": "controlRef",
    "status": "status",
    "externalReference": "externalReference",
    "submittedAt": "2024-08-25T15:00:00Z",
    "settledAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

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

MarketplacePaymentProviderEventRequest

provider

string · enum · required

Provider that emitted the callback or reconciliation result.

Enum values:

wallet_gateway

mobile_money_gateway

bank_gateway

blnk

manual

partner

providerExecutionRef

string · maxLength: 160 · required

External provider execution id already stored on a marketplace payment execution.

status

string · enum · required

Provider state to apply to the existing execution.

Enum values:

queued

submitted

settled

failed

cancelled

manual_review

responseCode

string · maxLength: 80

responseMessage

string · maxLength: 1000

Provider-safe response detail. Do not include secrets or raw PII.

occurredAt

string · date-time

Timestamp supplied by the provider or reconciliation run.

submittedAt

string · date-time

settledAt

string · date-time

failedAt

string · date-time

object

Small safe metadata object. Do not include secrets.

notes

string · maxLength: 1000

Apply a provider callback or reconciliation event › Responses

Provider event applied to the payment execution.

success

boolean · required

MarketplacePaymentExecution · required

object · required

POST/internal/marketplace/payment-executions/provider-events

curl https://sandbox-heritagepay-api.paypm.net/api/v1/internal/marketplace/payment-executions/provider-events \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Plug-Wallet-Api-Key: <api-key>' \
  --data '{
  "provider": "mobile_money_gateway",
  "providerExecutionRef": "gateway:payment:123",
  "status": "settled",
  "responseCode": "SETTLED",
  "responseMessage": "responseMessage",
  "occurredAt": "2024-08-25T15:00:00Z",
  "submittedAt": "2024-08-25T15:00:00Z",
  "settledAt": "2024-08-25T15:00:00Z",
  "failedAt": "2024-08-25T15:00:00Z",
  "metadata": {},
  "notes": "notes"
}'

Example Request Body

{
  "provider": "mobile_money_gateway",
  "providerExecutionRef": "gateway:payment:123",
  "status": "settled",
  "responseCode": "SETTLED",
  "responseMessage": "responseMessage",
  "occurredAt": "2024-08-25T15:00:00Z",
  "submittedAt": "2024-08-25T15:00:00Z",
  "settledAt": "2024-08-25T15:00:00Z",
  "failedAt": "2024-08-25T15:00:00Z",
  "metadata": {},
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "paymentExecution": {
    "id": "00000000-0000-0000-0000-000000000000",
    "executionRef": "executionRef",
    "controlRef": "controlRef",
    "provider": "provider",
    "providerExecutionRef": "providerExecutionRef",
    "status": "status",
    "attemptNumber": 0,
    "amountMinor": 0,
    "currency": "currency",
    "responseCode": "responseCode",
    "responseMessage": "responseMessage",
    "submittedAt": "2024-08-25T15:00:00Z",
    "settledAt": "2024-08-25T15:00:00Z",
    "failedAt": "2024-08-25T15:00:00Z",
    "metadata": {},
    "notes": "notes",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  },
  "paymentControl": {
    "controlRef": "controlRef",
    "status": "status",
    "externalReference": "externalReference",
    "submittedAt": "2024-08-25T15:00:00Z",
    "settledAt": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Aliases Contract vault