---
title: "Create Escrow Order"
method: POST
path: "/trdp/escrow/order"
tags: ["Escrow"]
---

# Create Escrow Order

`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`

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

## Headers

- `x-api-secret` string, required

## Request body

- CreateEscrowOrderRequest
  - `orderId` string, required
  - `redirectUrl` string, uri
  - `amount` number, required
  - `currency` string, required
  - `customerName` string, required
  - `customerPhoneNumber` string, required
  - `customerEmail` string, email
  - `callbackURL` string, uri
  - `description` string
  - `expiredAt` string, date-time
  - `items` EscrowItem[], required
    - `productId` string, required
    - `itemName` string, required
    - `imageUrl` string, uri
    - `quantity` integer, required
    - `unitPrice` number, required
    - `stockUnit` string
  - `metadata` object
  - `allocations` EscrowAllocation[], required
    - `merchantId` string, required
    - `amount` number, required
    - `metadata` object
      - `merchantName` string
      - `purpose` string
  - `autoRelease` boolean: Specifies whether escrow allocations are automatically released to merchants once the initial payment is completed.

## Response `201`

Escrow order created successfully.

- EscrowOrderResponse
  - `status` string, required
  - `timestamp` string, date-time, required
  - `message` string, required
  - `data` object, required
    - `escrow_id` string
    - `order_id` string
    - `amount` number
    - `currency` string
    - `status` string
    - `payment_url` string, uri
    - `allocations` EscrowAllocationResponse[]
      - `merchant_id` string, required
      - `amount` number, required
      - `metadata` object
        - `merchant_name` string
        - `purpose` string
    - `auto_release` boolean: Indicates whether allocations are configured to release automatically upon payment completion.
    - `expired_at` string, date-time

## Other responses

- `400`: Bad request.
- `401`: Unauthorized.
- `404`: Not found.
- `500`: internal.

## Changes

- **2026-11-03** `dac09da89d94`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/starpayethiopia/apis/starpay-api/changes/trdp/escrow/order/post.md)

---

[API](https://skmtc.dev/starpayethiopia/apis/starpay-api.md) - [All operations](https://skmtc.dev/starpayethiopia/apis/starpay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/starpayethiopia/apis/starpay-api/revisions/dac09da89d94?raw)