STstarpayethiopia
Escrow

Create Escrow Order

Changed on

Initiate a new escrow payment order with customizable multi-merchant fund allocations.

post/trdp/escrow/order

Request

  • Base URL
    https://sandbox-api.starpayethiopia.com/v1/starpay-api
  • URL
    https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order
  • Auth
    none declared. Required headers: x-api-secret

Headers

x-api-secretstring required
Example:SplFeYdc/Hc5S1CGmVDtETLYUJY/10a38ejamzwb1YH30h+u8sOK2fpTlyKitpPk

Your StarPay API secret key.

Request body

orderIdstring required
redirectUrlstring uri
amountnumber required
currencystring required
customerNamestring required
customerPhoneNumberstring required
customerEmailstring email
callbackURLstring uri
descriptionstring
expiredAtstring date-time
metadataobject
autoReleaseboolean

Specifies whether escrow allocations are automatically released to merchants once the initial payment is completed.

Example request

{
  "orderId": "ESCROW-20260729-001",
  "redirectUrl": "https://merchant.example.com/payment/success",
  "amount": 10000,
  "currency": "ETB",
  "customerName": "John Doe",
  "customerPhoneNumber": "+251912345678",
  "customerEmail": "john.doe@example.com",
  "callbackURL": "https://merchant.example.com/api/payment/callback",
  "description": "Escrow payment for marketplace order",
  "expiredAt": "2026-12-31T23:59:59Z",
  "items": [
    {
      "productId": "PROD-001",
      "itemName": "Apple MacBook Pro M3",
      "imageUrl": "https://example.com/images/macbook.jpg",
      "quantity": 1,
      "unitPrice": 8000,
      "stockUnit": "pcs"
    }
  ],
  "metadata": {
    "orderType": "escrow",
    "platform": "Marketplace",
    "customerId": "CUS-1001"
  },
  "allocations": [
    {
      "merchantId": "01346141",
      "amount": 7000,
      "metadata": {
        "merchantName": "Merchant A",
        "purpose": "Product Payment"
      }
    },
    {
      "merchantId": "01344351",
      "amount": 3000,
      "metadata": {
        "merchantName": "Merchant B",
        "purpose": "Shipping Fee"
      }
    }
  ]
}

Response

Escrow order created successfully.

statusstring required
timestampstring date-time required
messagestring required

Example response

{
  "status": "success",
  "timestamp": "2026-07-29T10:00:00Z",
  "message": "Escrow order created successfully",
  "data": {
    "escrow_id": "59667344",
    "order_id": "ESCROW-20260729-001",
    "amount": 10000,
    "currency": "ETB",
    "status": "PENDING",
    "payment_url": "https://pay.starpayethiopia.com/checkout/59667344",
    "allocations": [
      {
        "merchant_id": "01346141",
        "amount": 7000,
        "metadata": {
          "merchant_name": "Merchant A",
          "purpose": "Product Payment"
        }
      },
      {
        "merchant_id": "01344351",
        "amount": 3000,
        "metadata": {
          "merchant_name": "Merchant B",
          "purpose": "Shipping Fee"
        }
      }
    ],
    "expired_at": "2026-12-31T23:59:59Z"
  }
}

Changes