POST

trdp

escrow

order

using System.Net.Http;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-secret", "YOUR_API_SECRET");
var content = new StringContent("{\"orderId\": \"ESCROW-20260729-001\", \"amount\": 10000, \"currency\": \"ETB\"}", Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

const response = await fetch('https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-secret': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    orderId: 'ESCROW-20260729-001',
    amount: 10000,
    currency: 'ETB'
  })
});
const data = await response.json();
console.log(data);

curl --request POST \
  --url https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order \
  --header 'Content-Type: application/json' \
  --header 'x-api-secret: <x-api-secret>' \
  --data '
{
  "orderId": "ESCROW-20260729-001",
  "amount": 10000,
  "currency": "ETB",
  "customerName": "John Doe",
  "customerPhoneNumber": "+251912345678",
  "items": [
    {
      "productId": "PROD-001",
      "itemName": "Apple MacBook Pro M3",
      "quantity": 1,
      "unitPrice": 8000,
      "imageUrl": "https://example.com/images/macbook.jpg",
      "stockUnit": "pcs"
    }
  ],
  "allocations": [
    {
      "merchantId": "01346141",
      "amount": 7000,
      "metadata": {
        "merchantName": "Merchant A",
        "purpose": "Product Payment"
      }
    },
    {
      "merchantId": "01344351",
      "amount": 3000,
      "metadata": {
        "merchantName": "Merchant B",
        "purpose": "Shipping Fee"
      }
    }
  ],
  "redirectUrl": "https://merchant.example.com/payment/success",
  "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",
  "metadata": {
    "orderType": "escrow",
    "platform": "Marketplace",
    "customerId": "CUS-1001"
  },
  "autoRelease": false
}
'

import requests

url = "https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order"

payload = {
    "orderId": "ESCROW-20260729-001",
    "amount": 10000,
    "currency": "ETB",
    "customerName": "John Doe",
    "customerPhoneNumber": "+251912345678",
    "items": [
        {
            "productId": "PROD-001",
            "itemName": "Apple MacBook Pro M3",
            "quantity": 1,
            "unitPrice": 8000,
            "imageUrl": "https://example.com/images/macbook.jpg",
            "stockUnit": "pcs"
        }
    ],
    "allocations": [
        {
            "merchantId": "01346141",
            "amount": 7000,
            "metadata": {
                "merchantName": "Merchant A",
                "purpose": "Product Payment"
            }
        },
        {
            "merchantId": "01344351",
            "amount": 3000,
            "metadata": {
                "merchantName": "Merchant B",
                "purpose": "Shipping Fee"
            }
        }
    ],
    "redirectUrl": "https://merchant.example.com/payment/success",
    "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",
    "metadata": {
        "orderType": "escrow",
        "platform": "Marketplace",
        "customerId": "CUS-1001"
    },
    "autoRelease": False
}
headers = {
    "x-api-secret": "<x-api-secret>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => 'ESCROW-20260729-001',
    'amount' => 10000,
    'currency' => 'ETB',
    'customerName' => 'John Doe',
    'customerPhoneNumber' => '+251912345678',
    'items' => [
        [
                'productId' => 'PROD-001',
                'itemName' => 'Apple MacBook Pro M3',
                'quantity' => 1,
                'unitPrice' => 8000,
                'imageUrl' => 'https://example.com/images/macbook.jpg',
                'stockUnit' => 'pcs'
        ]
    ],
    'allocations' => [
        [
                'merchantId' => '01346141',
                'amount' => 7000,
                'metadata' => [
                                'merchantName' => 'Merchant A',
                                'purpose' => 'Product Payment'
                ]
        ],
        [
                'merchantId' => '01344351',
                'amount' => 3000,
                'metadata' => [
                                'merchantName' => 'Merchant B',
                                'purpose' => 'Shipping Fee'
                ]
        ]
    ],
    'redirectUrl' => 'https://merchant.example.com/payment/success',
    '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',
    'metadata' => [
        'orderType' => 'escrow',
        'platform' => 'Marketplace',
        'customerId' => 'CUS-1001'
    ],
    'autoRelease' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-secret: <x-api-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-secret", "<x-api-secret>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order")
  .header("x-api-secret", "<x-api-secret>")
  .header("Content-Type", "application/json")
  .body("{\n  \"orderId\": \"ESCROW-20260729-001\",\n  \"amount\": 10000,\n  \"currency\": \"ETB\",\n  \"customerName\": \"John Doe\",\n  \"customerPhoneNumber\": \"+251912345678\",\n  \"items\": [\n    {\n      \"productId\": \"PROD-001\",\n      \"itemName\": \"Apple MacBook Pro M3\",\n      \"quantity\": 1,\n      \"unitPrice\": 8000,\n      \"imageUrl\": \"https://example.com/images/macbook.jpg\",\n      \"stockUnit\": \"pcs\"\n    }\n  ],\n  \"allocations\": [\n    {\n      \"merchantId\": \"01346141\",\n      \"amount\": 7000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant A\",\n        \"purpose\": \"Product Payment\"\n      }\n    },\n    {\n      \"merchantId\": \"01344351\",\n      \"amount\": 3000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant B\",\n        \"purpose\": \"Shipping Fee\"\n      }\n    }\n  ],\n  \"redirectUrl\": \"https://merchant.example.com/payment/success\",\n  \"customerEmail\": \"john.doe@example.com\",\n  \"callbackURL\": \"https://merchant.example.com/api/payment/callback\",\n  \"description\": \"Escrow payment for marketplace order\",\n  \"expiredAt\": \"2026-12-31T23:59:59Z\",\n  \"metadata\": {\n    \"orderType\": \"escrow\",\n    \"platform\": \"Marketplace\",\n    \"customerId\": \"CUS-1001\"\n  },\n  \"autoRelease\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-secret"] = '<x-api-secret>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"orderId\": \"ESCROW-20260729-001\",\n  \"amount\": 10000,\n  \"currency\": \"ETB\",\n  \"customerName\": \"John Doe\",\n  \"customerPhoneNumber\": \"+251912345678\",\n  \"items\": [\n    {\n      \"productId\": \"PROD-001\",\n      \"itemName\": \"Apple MacBook Pro M3\",\n      \"quantity\": 1,\n      \"unitPrice\": 8000,\n      \"imageUrl\": \"https://example.com/images/macbook.jpg\",\n      \"stockUnit\": \"pcs\"\n    }\n  ],\n  \"allocations\": [\n    {\n      \"merchantId\": \"01346141\",\n      \"amount\": 7000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant A\",\n        \"purpose\": \"Product Payment\"\n      }\n    },\n    {\n      \"merchantId\": \"01344351\",\n      \"amount\": 3000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant B\",\n        \"purpose\": \"Shipping Fee\"\n      }\n    }\n  ],\n  \"redirectUrl\": \"https://merchant.example.com/payment/success\",\n  \"customerEmail\": \"john.doe@example.com\",\n  \"callbackURL\": \"https://merchant.example.com/api/payment/callback\",\n  \"description\": \"Escrow payment for marketplace order\",\n  \"expiredAt\": \"2026-12-31T23:59:59Z\",\n  \"metadata\": {\n    \"orderType\": \"escrow\",\n    \"platform\": \"Marketplace\",\n    \"customerId\": \"CUS-1001\"\n  },\n  \"autoRelease\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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"
        }
      }
    ],
    "auto_release": false,
    "expired_at": "2026-12-31T23:59:59Z"
  }
}

{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "BadRequestException",
    "message": "Missing required payload data, pk and payload is required"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "ABC_001",
    "message": "not found"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

Create an Escrow Order

Create a new escrow payment session with multi-merchant fund allocations. The funds paid by the customer remain held in escrow by StarPay until you explicitly release each merchant allocation or cancel the escrow. Use this endpoint for marketplace transactions, multi-vendor checkouts, or service platforms where funds should be held securely until order fulfillment is confirmed.

Endpoint

POST /trdp/escrow/order

Authentication

Include your API secret in the request header. Header:

x-api-secret (string) — Required. Your StarPay API secret key. Generate this key from the Merchant Portal under API Keys.

Example:

x-api-secret: SplFeYdc/Hc5S1CGmVDtETLYUJY/10a38ejamzwb1YH30h+u8sOK2fpTlyKitpPk

Request Body

orderId

Unique merchant order identifier for tracking the order across systems. Type: string — Required Example:

"ESCROW-20260729-001"

amount

Total payment amount to be collected from the customer. The sum of all merchant allocations should match this total amount. Type: number — Required Example:

currency

The currency code used for the transaction. Currently supported: ETB Type: string — Required Example:

"ETB"

customerName

The full name of the customer making the payment. Type: string — Required Example:

"John Doe"

customerPhoneNumber

The customer’s phone number. Used for payment initiation (USSD push, OTP) and verification. Type: string — Required Example:

"+251912345678"

items

Array of item objects representing the products or services purchased in this escrow order. Type: array — Required

Item Fields

Field	Type	Required	Description
`productId`	`string`	Yes	Unique identifier for the product or service.
`itemName`	`string`	Yes	Display name of the product.
`quantity`	`integer`	Yes	Number of units purchased.
`unitPrice`	`number`	Yes	Price per single unit.
`imageUrl`	`string`	No	Direct URL to the product image.
`stockUnit`	`string`	No	Unit of measurement (e.g., `pcs`, `kg`, `box`).

Example:

[
  {
    "productId": "PROD-001",
    "itemName": "Apple MacBook Pro M3",
    "imageUrl": "https://example.com/images/macbook.jpg",
    "quantity": 1,
    "unitPrice": 8000,
    "stockUnit": "pcs"
  },
  {
    "productId": "PROD-002",
    "itemName": "USB-C Adapter",
    "imageUrl": "https://example.com/images/adapter.jpg",
    "quantity": 2,
    "unitPrice": 1000,
    "stockUnit": "pcs"
  }
]

allocations

Array of payout allocations defining how the escrow funds will be distributed among multiple merchants once fulfilled. Type: array — Required

Allocation Fields

Field	Type	Required	Description
`merchantId`	`string`	Yes	The destination merchant ID receiving this portion of funds.
`amount`	`number`	Yes	The amount allocated to this merchant.
`metadata`	`object`	No	Additional metadata such as `merchantName` or payout `purpose`.

Example:

[
  {
    "merchantId": "01346141",
    "amount": 7000,
    "metadata": {
      "merchantName": "Merchant A",
      "purpose": "Product Payment"
    }
  },
  {
    "merchantId": "01344351",
    "amount": 3000,
    "metadata": {
      "merchantName": "Merchant B",
      "purpose": "Shipping Fee"
    }
  }
]

autoRelease

Specifies whether escrow allocations are automatically released once the customer completes payment. When set to true, StarPay automatically releases the allocated funds to the destination merchants immediately after the initial customer transaction is paid. When set to false, funds are held securely in escrow until you explicitly release each allocation or cancel the order. Type: boolean — Optional (Default: false) Example:

false

callbackURL

Server-to-server notification URL that StarPay calls when payment status changes. Type: string (URI) — Optional Example:

"https://merchant.example.com/api/payment/callback"

redirectUrl

The URL where customers are redirected after completing payment on the checkout page. Type: string (URI) — Optional Example:

"https://merchant.example.com/payment/success"

customerEmail

Customer email address for notifications and receipts. Type: string (email) — Optional Example:

"john.doe@example.com"

description

A short description of the escrow order. Type: string — Optional Example:

"Escrow payment for marketplace order"

expiredAt

Expiration timestamp in ISO 8601 format. After this timestamp, the payment link will no longer accept payments. Type: string (date-time) — Optional Example:

"2026-12-31T23:59:59Z"

metadata

Custom key-value pairs for attaching internal application context to the transaction. Type: object — Optional Example:

{
  "orderType": "escrow",
  "platform": "Marketplace",
  "customerId": "CUS-1001"
}

Example Request

curl --request POST \
  --url https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order \
  --header 'Content-Type: application/json' \
  --header 'x-api-secret: SplFeYdc/Hc5S1CGmVDtETLYUJY/10a38ejamzwb1YH30h+u8sOK2fpTlyKitpPk' \
  --data '{
    "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",
    "autoRelease": false,
    "items": [
      {
        "productId": "PROD-001",
        "itemName": "Apple MacBook Pro M3",
        "imageUrl": "https://example.com/images/macbook.jpg",
        "quantity": 1,
        "unitPrice": 8000,
        "stockUnit": "pcs"
      },
      {
        "productId": "PROD-002",
        "itemName": "USB-C Adapter",
        "imageUrl": "https://example.com/images/adapter.jpg",
        "quantity": 2,
        "unitPrice": 1000,
        "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

Success Response (`201 Created`)

{
  "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",
    "auto_release": false,
    "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"
  }
}

Escrow Lifecycle & Next Steps

Redirect Customer: Direct the customer to the payment_url returned in the response to complete payment.
Handle Webhook: Listen for the incoming payment callback to verify that the initial payment is completed.
Fulfill & Release:
- If autoRelease is false (default): Funds remain held in escrow. Once fulfillment is confirmed, call Release Escrow Allocation with the respective merchantId and escrowId.
- If autoRelease is true: Allocations release automatically to the destination merchants immediately after the initial transaction is paid.
Cancel if Needed: If the buyer cancels or an issue occurs before fulfillment or release, call Cancel Escrow to trigger a refund.

Headers

x-api-secret

string

required

Your StarPay API secret key.

Example:

"SplFeYdc/Hc5S1CGmVDtETLYUJY/10a38ejamzwb1YH30h+u8sOK2fpTlyKitpPk"

Body

application/json

Escrow order creation payload including items and multi-merchant allocations.

orderId

string

required

Example:

"ESCROW-20260729-001"

amount

number

required

Example:

10000

currency

string

required

Example:

"ETB"

customerName

string

required

Example:

"John Doe"

customerPhoneNumber

string

required

Example:

"+251912345678"

items

object[]

required

Show child attributes

allocations

object[]

required

Show child attributes

Example:

[
  {
    "merchantId": "01346141",
    "amount": 7000,
    "metadata": {
      "merchantName": "Merchant A",
      "purpose": "Product Payment"
    }
  },
  {
    "merchantId": "01344351",
    "amount": 3000,
    "metadata": {
      "merchantName": "Merchant B",
      "purpose": "Shipping Fee"
    }
  }
]

redirectUrl

string<uri>

Example:

"https://merchant.example.com/payment/success"

customerEmail

string<email>

Example:

"john.doe@example.com"

callbackURL

string<uri>

Example:

"https://merchant.example.com/api/payment/callback"

description

string

Example:

"Escrow payment for marketplace order"

expiredAt

string<date-time>

Example:

"2026-12-31T23:59:59Z"

metadata

object

Example:

{
  "orderType": "escrow",
  "platform": "Marketplace",
  "customerId": "CUS-1001"
}

autoRelease

boolean

default:false

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

Example:

false

Response

Escrow order created successfully.

status

string

required

Example:

"success"

timestamp

string<date-time>

required

Example:

"2026-07-29T10:00:00Z"

message

string

required

Example:

"Escrow order created successfully"

data

object

required

Show child attributes

using System.Net.Http;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-secret", "YOUR_API_SECRET");
var content = new StringContent("{\"orderId\": \"ESCROW-20260729-001\", \"amount\": 10000, \"currency\": \"ETB\"}", Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

const response = await fetch('https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-secret': 'YOUR_API_SECRET'
  },
  body: JSON.stringify({
    orderId: 'ESCROW-20260729-001',
    amount: 10000,
    currency: 'ETB'
  })
});
const data = await response.json();
console.log(data);

curl --request POST \
  --url https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order \
  --header 'Content-Type: application/json' \
  --header 'x-api-secret: <x-api-secret>' \
  --data '
{
  "orderId": "ESCROW-20260729-001",
  "amount": 10000,
  "currency": "ETB",
  "customerName": "John Doe",
  "customerPhoneNumber": "+251912345678",
  "items": [
    {
      "productId": "PROD-001",
      "itemName": "Apple MacBook Pro M3",
      "quantity": 1,
      "unitPrice": 8000,
      "imageUrl": "https://example.com/images/macbook.jpg",
      "stockUnit": "pcs"
    }
  ],
  "allocations": [
    {
      "merchantId": "01346141",
      "amount": 7000,
      "metadata": {
        "merchantName": "Merchant A",
        "purpose": "Product Payment"
      }
    },
    {
      "merchantId": "01344351",
      "amount": 3000,
      "metadata": {
        "merchantName": "Merchant B",
        "purpose": "Shipping Fee"
      }
    }
  ],
  "redirectUrl": "https://merchant.example.com/payment/success",
  "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",
  "metadata": {
    "orderType": "escrow",
    "platform": "Marketplace",
    "customerId": "CUS-1001"
  },
  "autoRelease": false
}
'

import requests

url = "https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order"

payload = {
    "orderId": "ESCROW-20260729-001",
    "amount": 10000,
    "currency": "ETB",
    "customerName": "John Doe",
    "customerPhoneNumber": "+251912345678",
    "items": [
        {
            "productId": "PROD-001",
            "itemName": "Apple MacBook Pro M3",
            "quantity": 1,
            "unitPrice": 8000,
            "imageUrl": "https://example.com/images/macbook.jpg",
            "stockUnit": "pcs"
        }
    ],
    "allocations": [
        {
            "merchantId": "01346141",
            "amount": 7000,
            "metadata": {
                "merchantName": "Merchant A",
                "purpose": "Product Payment"
            }
        },
        {
            "merchantId": "01344351",
            "amount": 3000,
            "metadata": {
                "merchantName": "Merchant B",
                "purpose": "Shipping Fee"
            }
        }
    ],
    "redirectUrl": "https://merchant.example.com/payment/success",
    "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",
    "metadata": {
        "orderType": "escrow",
        "platform": "Marketplace",
        "customerId": "CUS-1001"
    },
    "autoRelease": False
}
headers = {
    "x-api-secret": "<x-api-secret>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'orderId' => 'ESCROW-20260729-001',
    'amount' => 10000,
    'currency' => 'ETB',
    'customerName' => 'John Doe',
    'customerPhoneNumber' => '+251912345678',
    'items' => [
        [
                'productId' => 'PROD-001',
                'itemName' => 'Apple MacBook Pro M3',
                'quantity' => 1,
                'unitPrice' => 8000,
                'imageUrl' => 'https://example.com/images/macbook.jpg',
                'stockUnit' => 'pcs'
        ]
    ],
    'allocations' => [
        [
                'merchantId' => '01346141',
                'amount' => 7000,
                'metadata' => [
                                'merchantName' => 'Merchant A',
                                'purpose' => 'Product Payment'
                ]
        ],
        [
                'merchantId' => '01344351',
                'amount' => 3000,
                'metadata' => [
                                'merchantName' => 'Merchant B',
                                'purpose' => 'Shipping Fee'
                ]
        ]
    ],
    'redirectUrl' => 'https://merchant.example.com/payment/success',
    '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',
    'metadata' => [
        'orderType' => 'escrow',
        'platform' => 'Marketplace',
        'customerId' => 'CUS-1001'
    ],
    'autoRelease' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-secret: <x-api-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order"

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

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-secret", "<x-api-secret>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order")
  .header("x-api-secret", "<x-api-secret>")
  .header("Content-Type", "application/json")
  .body("{\n  \"orderId\": \"ESCROW-20260729-001\",\n  \"amount\": 10000,\n  \"currency\": \"ETB\",\n  \"customerName\": \"John Doe\",\n  \"customerPhoneNumber\": \"+251912345678\",\n  \"items\": [\n    {\n      \"productId\": \"PROD-001\",\n      \"itemName\": \"Apple MacBook Pro M3\",\n      \"quantity\": 1,\n      \"unitPrice\": 8000,\n      \"imageUrl\": \"https://example.com/images/macbook.jpg\",\n      \"stockUnit\": \"pcs\"\n    }\n  ],\n  \"allocations\": [\n    {\n      \"merchantId\": \"01346141\",\n      \"amount\": 7000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant A\",\n        \"purpose\": \"Product Payment\"\n      }\n    },\n    {\n      \"merchantId\": \"01344351\",\n      \"amount\": 3000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant B\",\n        \"purpose\": \"Shipping Fee\"\n      }\n    }\n  ],\n  \"redirectUrl\": \"https://merchant.example.com/payment/success\",\n  \"customerEmail\": \"john.doe@example.com\",\n  \"callbackURL\": \"https://merchant.example.com/api/payment/callback\",\n  \"description\": \"Escrow payment for marketplace order\",\n  \"expiredAt\": \"2026-12-31T23:59:59Z\",\n  \"metadata\": {\n    \"orderType\": \"escrow\",\n    \"platform\": \"Marketplace\",\n    \"customerId\": \"CUS-1001\"\n  },\n  \"autoRelease\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-secret"] = '<x-api-secret>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"orderId\": \"ESCROW-20260729-001\",\n  \"amount\": 10000,\n  \"currency\": \"ETB\",\n  \"customerName\": \"John Doe\",\n  \"customerPhoneNumber\": \"+251912345678\",\n  \"items\": [\n    {\n      \"productId\": \"PROD-001\",\n      \"itemName\": \"Apple MacBook Pro M3\",\n      \"quantity\": 1,\n      \"unitPrice\": 8000,\n      \"imageUrl\": \"https://example.com/images/macbook.jpg\",\n      \"stockUnit\": \"pcs\"\n    }\n  ],\n  \"allocations\": [\n    {\n      \"merchantId\": \"01346141\",\n      \"amount\": 7000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant A\",\n        \"purpose\": \"Product Payment\"\n      }\n    },\n    {\n      \"merchantId\": \"01344351\",\n      \"amount\": 3000,\n      \"metadata\": {\n        \"merchantName\": \"Merchant B\",\n        \"purpose\": \"Shipping Fee\"\n      }\n    }\n  ],\n  \"redirectUrl\": \"https://merchant.example.com/payment/success\",\n  \"customerEmail\": \"john.doe@example.com\",\n  \"callbackURL\": \"https://merchant.example.com/api/payment/callback\",\n  \"description\": \"Escrow payment for marketplace order\",\n  \"expiredAt\": \"2026-12-31T23:59:59Z\",\n  \"metadata\": {\n    \"orderType\": \"escrow\",\n    \"platform\": \"Marketplace\",\n    \"customerId\": \"CUS-1001\"\n  },\n  \"autoRelease\": false\n}"

response = http.request(request)
puts response.read_body

{
  "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"
        }
      }
    ],
    "auto_release": false,
    "expired_at": "2026-12-31T23:59:59Z"
  }
}

{
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "BadRequestException",
    "message": "Missing required payload data, pk and payload is required"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "ABC_001",
    "message": "not found"
  }
}

{
  "message": "Something wrong",
  "status": "error",
  "timestamp": "2025-05-07T07:31:30.824Z",
  "path": "/v2/starpay-api/",
  "error": {
    "code": "GEN_004",
    "message": "An unexpected server error occurred."
  }
}

Get started

Api Reference

Escrow Service

Create Escrow Order

Create an Escrow Order

Endpoint

Authentication

Request Body

orderId

amount

currency

customerName

customerPhoneNumber

items

Item Fields

allocations

Allocation Fields

autoRelease

callbackURL

redirectUrl

customerEmail

description

expiredAt

metadata

Example Request

Response

Success Response (`201 Created`)

Escrow Lifecycle & Next Steps

Headers

Body

Response

​Create an Escrow Order

​Endpoint

​Authentication

​Request Body

​orderId

​amount

​currency

​customerName

​customerPhoneNumber

​items

​Item Fields

​allocations

​Allocation Fields

​autoRelease

​callbackURL

​redirectUrl

​customerEmail

​description

​expiredAt

​metadata

​Example Request

​Response

​Success Response (201 Created)

​Escrow Lifecycle & Next Steps

Headers

Body

Response

Create an Escrow Order

Endpoint

Authentication

Request Body

orderId

amount

currency

customerName

customerPhoneNumber

items

Item Fields

allocations

Allocation Fields

autoRelease

callbackURL

redirectUrl

customerEmail

description

expiredAt

metadata

Example Request

Response

Success Response (`201 Created`)

Escrow Lifecycle & Next Steps