Escrow Disbursements API

This page documents the live public escrow-disbursement surface served under https://api.gopiaxis.com/api.

Overview

Public escrow-disbursement routes:

  • POST /api/escrow-disbursements

  • GET /api/escrow-disbursements

  • GET /api/escrow-disbursements/{disbursement_id}

  • POST /api/escrow-disbursements/{disbursement_id}/release

  • POST /api/escrow-disbursements/{disbursement_id}/cancel

Public Contract Notes

The guaranteed create request schema is:

  • recipients

  • currency

  • payment_method

  • description

  • user_location

Each recipient guarantees:

  • recipient_id

  • email

  • phone_number

  • amount

  • terms

  • reference

Recipient resolution works the same way as direct disbursements:

  • recipient_id present: the escrow-disbursement item targets an internal Piaxis beneficiary

  • recipient_id omitted: the escrow-disbursement item targets an external beneficiary through the batch payment_method

  • for MTN and Airtel beneficiary routing, phone_number is the field that matters

  • when present, recipient_id must be a Piaxis Account.id

If the beneficiary is already a Piaxis user, obtain and store that id safely:

  1. send the beneficiary through GET /api/authorize

  2. exchange the code through POST /api/token

  3. persist the returned user_id

  4. use that stored user_id later as recipients[].recipient_id

If the beneficiary should receive funds externally instead, omit recipient_id and provide the payout phone_number.

Business role difference

Escrow disbursement flips the collection-escrow roles:

  • merchant or platform = escrow sender

  • payout beneficiary = escrow receiver

Use it when the beneficiary should become the protected payout recipient that must satisfy terms before funds are released.

If your rule is still collect from buyer B now, pay user C later, keep using merchant collection or collection escrow first, then create the payout or payout escrow afterward.

If you see richer examples elsewhere with keys such as auto_release, metadata, or routing-specific orchestration data, treat those as deployment-specific extensions and not part of the guaranteed public contract.

Authentication

Use merchant API key authentication:

 api-key: YOUR_MERCHANT_API_KEY
 Content-Type: application/json
X-piaxis-Client-ID: YOUR_MERCHANT_CLIENT_ID

Create Escrow Disbursement

POST /api/escrow-disbursements

Canonical example

 POST /api/escrow-disbursements HTTP/1.1
 Host: api.gopiaxis.com
 api-key: YOUR_API_KEY
 Content-Type: application/json
X-piaxis-Client-ID: YOUR_MERCHANT_CLIENT_ID

 {
   "recipients": [
     {
       "recipient_id": "123e4567-e89b-12d3-a456-426614174000",
       "email": "[email protected]",
       "phone_number": "+256700111000",
       "amount": "25000.00",
       "reference": "DELIVERY-001",
       "terms": [
         {
           "type": "delivery_confirmation",
           "data": {
             "deadline": "2026-12-31T23:59:59Z"
           }
         }
       ]
     }
   ],
   "currency": "UGX",
   "payment_method": "piaxis_external",
   "description": "Route A delivery batch",
   "user_location": {
     "latitude": 0.347596,
     "longitude": 32.582520
   }
 }

Guaranteed create response

{
  "disbursement_id": "8db0d705-876f-45aa-8e0c-67120d5550e2",
  "status": "pending",
  "total_amount": "25000.00",
  "currency": "UGX",
  "recipient_count": 1,
  "successful_count": 0,
  "failed_count": 0,
  "pending_count": 1,
  "escrow_items": [
    {
      "recipient_id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "[email protected]",
      "phone_number": "+256700111000",
      "amount": "25000.00",
      "escrow_id": "7680cfa9-b0cf-43a7-974b-108b89bd5ebe",
      "status": "pending",
      "terms_count": 1,
      "reference": "DELIVERY-001"
    }
  ],
  "description": "Route A delivery batch",
  "created_at": "2026-01-15T10:30:00Z"
}

List Escrow Disbursements

GET /api/escrow-disbursements

Supported query parameters:

  • status

  • payment_method

  • offset

  • limit

Get Escrow Disbursement

GET /api/escrow-disbursements/{disbursement_id}

Use this route to fetch the batch plus its escrow items.

Release Escrow Disbursement

POST /api/escrow-disbursements/{disbursement_id}/release

Guaranteed request fields:

  • force

  • reason

  • escrow_ids

Example

{
  "force": true,
  "reason": "Batch approval granted",
  "escrow_ids": [
    "7680cfa9-b0cf-43a7-974b-108b89bd5ebe"
  ]
}

Cancel Escrow Disbursement

POST /api/escrow-disbursements/{disbursement_id}/cancel

This route cancels the batch. Use it when the work should not proceed or the batch was created incorrectly.

Operational Guidance

  • Use escrow disbursements when each recipient must satisfy terms before payout.

  • Use direct disbursements when recipients should be paid immediately.

  • Persist both the batch disbursement_id and each returned escrow_id.

  • Reconcile from both polling and webhooks.