Escrow API

Canonical MTN escrow example

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

 {
   "amount": "50000.00",
   "currency_code": "UGX",
   "payment_method": "mtn",
   "terms": [
     {
       "type": "delivery_confirmation",
       "data": {
         "deadline": "2026-12-31T23:59:59Z"
       }
     }
   ],
   "user_info": {
     "email": "[email protected]",
     "phone_number": "+256700000000",
     "otp": "123456"
   }
 }

Receiver semantics

Public escrow collection infers the release destination from the authenticated merchant API key.

• omitting receiver_id uses the authenticated merchant Account.id automatically

• if receiver_id is supplied, it must still match the authenticated merchant Account.id

• this public collection route does not use receiver_id to choose some other merchant or platform account

• if you want to hold funds through escrow and later pay an internal or external beneficiary, release into the authenticated merchant wallet first and then create a disbursement

Marketplace sequence

For a platform-managed order or service flow:

1. authenticate as the merchant or platform account that should collect and create the escrow

2. the customer pays into escrow

3. release the escrow to that same authenticated merchant or platform account when the order or service is complete

4. if the final beneficiary should be paid on MTN or Airtel mobile money, create a separate direct disbursement to the beneficiary phone number

This keeps the roles explicit:

• the authenticated merchant receives the escrow release on this public collection route

• recipients[].recipient_id is only for later internal wallet payouts

• external mobile-money payees are handled later through the disbursement routes with phone_number

Choose the right flow

Use direct payment when the authenticated merchant should collect immediately and no later escrow fulfillment is needed.

Use public escrow collection when the authenticated merchant should still be the final collector, but release should wait for payer and merchant actions such as delivery confirmation or meeting verification.

Use direct disbursement when you already control the collected balance and want to pay a beneficiary immediately.

Use escrow disbursement when the payout beneficiary, not the collecting merchant, must satisfy terms before payout. In escrow-disbursement batches the merchant or platform is the escrow sender and the beneficiary becomes the escrow receiver.

If your rule is collect from buyer B now, pay user C later, keep the collection on POST /api/escrows/ with the merchant as receiver, release into the merchant wallet, and then create a direct disbursement or escrow disbursement for user C.

Canonical piaxis_external escrow example

POST /api/escrows/ HTTP/1.1
Host: api.gopiaxis.com
api-key: YOUR_API_KEY
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "amount": "75000.00",
  "currency_code": "UGX",
  "payment_method": "piaxis_external",
  "external_user_id": "platform_user_123",
  "terms": [
    {
      "type": "delivery_confirmation",
      "data": {
        "deadline": "2026-12-31T23:59:59Z"
      }
    }
  ]
}

Guaranteed create response shape

{
  "id": "7680cfa9-b0cf-43a7-974b-108b89bd5ebe",
  "amount": "50000.00",
  "currency_code": "UGX",
  "status": "pending",
  "payment_method": "mtn",
  "sender_id": null,
  "receiver_id": "096b723a-45c5-4957-94d7-747835136265",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z",
  "terms": [],
  "products": [],
  "location": null,
  "required_actions": [],
  "external_user_id": null
}

Role model on this public collection route

For escrows created by POST /api/escrows/ the protected actors are:

• payer or customer = escrow sender

• authenticated merchant collector = escrow receiver

That means:

• buyer-side confirmations must come from the original payer

• seller-side confirmations must come from the authenticated merchant whose account matches receiver_id

• if you want a downstream seller, driver, or beneficiary to become the protected receiver instead, use POST /api/escrow-disbursements rather than trying to route collection escrow directly to that user

Inspect required actions first

Use GET /api/escrows/{escrow_id} and inspect required_actions before building a fulfill UI.

Typical action hints returned by the live code include:

• delivery_confirmation_required with confirmation_method

• delivery_meeting_required with max_distance_km

• agreement_required with agreement_options and current status

• proof_required with proof_type and optional deadline

Term-specific payloads

The outer request shape stays the same, but data keys vary by term_type. The live handler branches on those keys, so send the term-specific payload instead of a generic confirmed flag.

{
  "term_id": "4215567e-6928-4a9d-85d8-c3b1708bdcec",
  "term_type": "delivery_confirmation",
  "data": {
    "confirmation_method": "signature",
    "buyer_device_info": {
      "device_id": "buyer-device-001",
      "platform": "android",
      "app_version": "1.0.0"
    }
  },
  "user_info": {
    "email": "[email protected]",
    "phone_number": "+256700000000",
    "otp": "123456"
  }
}

{
  "term_id": "4215567e-6928-4a9d-85d8-c3b1708bdcec",
  "term_type": "delivery_confirmation",
  "data": {
    "confirmation_method": "signature",
    "seller_device_info": {
      "device_id": "merchant-ops-01",
      "platform": "web"
    }
  }
}

{
  "term_id": "4215567e-6928-4a9d-85d8-c3b1708bdcec",
  "term_type": "meeting_delivery",
  "data": {
    "buyer_latitude": 0.3476,
    "buyer_longitude": 32.5825,
    "device_info": {
      "device_id": "buyer-phone-01",
      "platform": "android"
    }
  },
  "user_info": {
    "email": "[email protected]",
    "phone_number": "+256700000000",
    "otp": "123456"
  }
}

{
  "term_id": "4215567e-6928-4a9d-85d8-c3b1708bdcec",
  "term_type": "meeting_delivery",
  "data": {
    "seller_latitude": 0.3477,
    "seller_longitude": 32.5826,
    "device_info": {
      "platform": "web"
    }
  }
}

Example

{
  "force": true,
  "reason": "Buyer requested immediate release",
  "user_info": {
    "email": "[email protected]",
    "phone_number": "+256700000000",
    "otp": "123456"
  }
}