> ## Documentation Index
> Fetch the complete documentation index at: https://developer.starpayethiopia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Escrow Order

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

# 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

```http theme={null}
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:

```http theme={null}
x-api-secret: SplFeYdc/Hc5S1CGmVDtETLYUJY/10a38ejamzwb1YH30h+u8sOK2fpTlyKitpPk
```

***

## Request Body

### orderId

Unique merchant order identifier for tracking the order across systems.

Type: `string` — Required

Example:

```json theme={null}
"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:

```json theme={null}
10000
```

***

### currency

The currency code used for the transaction.

Currently supported: `ETB`

Type: `string` — Required

Example:

```json theme={null}
"ETB"
```

***

### customerName

The full name of the customer making the payment.

Type: `string` — Required

Example:

```json theme={null}
"John Doe"
```

***

### customerPhoneNumber

The customer's phone number. Used for payment initiation (USSD push, OTP) and verification.

Type: `string` — Required

Example:

```json theme={null}
"+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.   |
| `item_name`  | `string`  | Yes      | Display name of the product.                    |
| `quantity`   | `integer` | Yes      | Number of units purchased.                      |
| `unit_price` | `number`  | Yes      | Price per single unit.                          |
| `image_url`  | `string`  | No       | Direct URL to the product image.                |
| `stock_unit` | `string`  | No       | Unit of measurement (e.g., `pcs`, `kg`, `box`). |

Example:

```json theme={null}
[
  {
    "productId": "PROD-001",
    "item_name": "Apple MacBook Pro M3",
    "image_url": "https://example.com/images/macbook.jpg",
    "quantity": 1,
    "unit_price": 8000,
    "stock_unit": "pcs"
  },
  {
    "productId": "PROD-002",
    "item_name": "USB-C Adapter",
    "image_url": "https://example.com/images/adapter.jpg",
    "quantity": 2,
    "unit_price": 1000,
    "stock_unit": "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:

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

***

### callbackURL

Server-to-server notification URL that StarPay calls when payment status changes.

Type: `string` (URI) — Optional

Example:

```json theme={null}
"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:

```json theme={null}
"https://merchant.example.com/payment/success"
```

***

### customerEmail

Customer email address for notifications and receipts.

Type: `string` (email) — Optional

Example:

```json theme={null}
"john.doe@example.com"
```

***

### description

A short description of the escrow order.

Type: `string` — Optional

Example:

```json theme={null}
"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:

```json theme={null}
"2026-12-31T23:59:59Z"
```

***

### metadata

Custom key-value pairs for attaching internal application context to the transaction.

Type: `object` — Optional

Example:

```json theme={null}
{
  "orderType": "escrow",
  "platform": "Marketplace",
  "customerId": "CUS-1001"
}
```

***

## Example Request

```bash theme={null}
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",
    "items": [
      {
        "productId": "PROD-001",
        "item_name": "Apple MacBook Pro M3",
        "image_url": "https://example.com/images/macbook.jpg",
        "quantity": 1,
        "unit_price": 8000,
        "stock_unit": "pcs"
      },
      {
        "productId": "PROD-002",
        "item_name": "USB-C Adapter",
        "image_url": "https://example.com/images/adapter.jpg",
        "quantity": 2,
        "unit_price": 1000,
        "stock_unit": "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`)

```json theme={null}
{
  "status": "success",
  "timestamp": "2026-07-29T10:00:00Z",
  "message": "Escrow order created successfully",
  "data": {
    "escrowId": "59667344",
    "orderId": "ESCROW-20260729-001",
    "amount": 10000,
    "currency": "ETB",
    "status": "PENDING",
    "paymentUrl": "https://pay.starpayethiopia.com/checkout/59667344",
    "allocations": [
      {
        "merchantId": "01346141",
        "amount": 7000,
        "metadata": {
          "merchantName": "Merchant A",
          "purpose": "Product Payment"
        }
      },
      {
        "merchantId": "01344351",
        "amount": 3000,
        "metadata": {
          "merchantName": "Merchant B",
          "purpose": "Shipping Fee"
        }
      }
    ],
    "expiredAt": "2026-12-31T23:59:59Z"
  }
}
```

***

## Escrow Lifecycle & Next Steps

1. **Redirect Customer**: Direct the customer to the `paymentUrl` returned in the response to complete payment.
2. **Handle Webhook**: Listen for the incoming payment callback to verify that funds are held in escrow.
3. **Fulfill & Release**: Once an item or service is delivered, call [Release Escrow Allocation](/api/endpoint/escrow-release) with the respective `merchantId` and `escrowId`.
4. **Cancel if Needed**: If the buyer cancels or an issue occurs before fulfillment, call [Cancel Escrow](/api/endpoint/escrow-cancel) to trigger a refund.


## OpenAPI

````yaml POST /trdp/escrow/order
openapi: 3.1.0
info:
  title: StarPay API
  version: 1.0.0
  description: >
    StarPay API is a RESTful API that provides access to various functionalities
    of the StarPay system.

    This API allows users to manage product categories, including creating,
    updating, deleting, and retrieving product categories.

    The API uses JWT for thirdparty and supports various response formats.
servers:
  - url: https://sandbox-api.starpayethiopia.com/v1/starpay-api
    description: Sandbox server
security: []
tags:
  - name: thirdparty
  - name: Escrow
  - name: Merchant
paths:
  /trdp/escrow/order:
    post:
      tags:
        - Escrow
      summary: Create Escrow Order
      description: >-
        Initiate a new escrow payment order with customizable multi-merchant
        fund allocations.
      operationId: createEscrowOrder
      parameters:
        - in: header
          name: x-api-secret
          required: true
          description: Your StarPay API secret key.
          schema:
            type: string
            example: SplFeYdc/Hc5S1CGmVDtETLYUJY/10a38ejamzwb1YH30h+u8sOK2fpTlyKitpPk
      requestBody:
        required: true
        description: >-
          Escrow order creation payload including items and multi-merchant
          allocations.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEscrowOrderRequest'
      responses:
        '201':
          description: Escrow order created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscrowOrderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
        - lang: csharp
          label: C#
          source: >
            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());
        - lang: javascript
          label: JavaScript
          source: >
            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);
components:
  schemas:
    CreateEscrowOrderRequest:
      type: object
      properties:
        orderId:
          type: string
          example: ESCROW-20260729-001
        redirectUrl:
          type: string
          format: uri
          example: https://merchant.example.com/payment/success
        amount:
          type: number
          example: 10000
        currency:
          type: string
          example: ETB
        customerName:
          type: string
          example: John Doe
        customerPhoneNumber:
          type: string
          example: '+251912345678'
        customerEmail:
          type: string
          format: email
          example: john.doe@example.com
        callbackURL:
          type: string
          format: uri
          example: https://merchant.example.com/api/payment/callback
        description:
          type: string
          example: Escrow payment for marketplace order
        expiredAt:
          type: string
          format: date-time
          example: '2026-12-31T23:59:59Z'
        items:
          type: array
          items:
            $ref: '#/components/schemas/EscrowItem'
        metadata:
          type: object
          example:
            orderType: escrow
            platform: Marketplace
            customerId: CUS-1001
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/EscrowAllocation'
      required:
        - orderId
        - amount
        - currency
        - customerName
        - customerPhoneNumber
        - items
        - allocations
    EscrowOrderResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        timestamp:
          type: string
          format: date-time
          example: '2026-07-29T10:00:00Z'
        message:
          type: string
          example: Escrow order created successfully
        data:
          type: object
          properties:
            escrowId:
              type: string
              example: '59667344'
            orderId:
              type: string
              example: ESCROW-20260729-001
            amount:
              type: number
              example: 10000
            currency:
              type: string
              example: ETB
            status:
              type: string
              example: PENDING
            paymentUrl:
              type: string
              format: uri
              example: https://pay.starpayethiopia.com/checkout/59667344
            allocations:
              type: array
              items:
                $ref: '#/components/schemas/EscrowAllocation'
            expiredAt:
              type: string
              format: date-time
              example: '2026-12-31T23:59:59Z'
      required:
        - status
        - timestamp
        - message
        - data
    EscrowItem:
      type: object
      properties:
        productId:
          type: string
          example: PROD-001
        item_name:
          type: string
          example: Apple MacBook Pro M3
        image_url:
          type: string
          format: uri
          example: https://example.com/images/macbook.jpg
        quantity:
          type: integer
          example: 1
        unit_price:
          type: number
          example: 8000
        stock_unit:
          type: string
          example: pcs
      required:
        - productId
        - item_name
        - quantity
        - unit_price
    EscrowAllocation:
      type: object
      properties:
        merchantId:
          type: string
          example: '01346141'
        amount:
          type: number
          example: 7000
        metadata:
          type: object
          properties:
            merchantName:
              type: string
              example: Merchant A
            purpose:
              type: string
              example: Product Payment
      required:
        - merchantId
        - amount
    BadRequestError:
      type: object
      properties:
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: BadRequestException
            message:
              type: string
              example: Missing required payload data, pk and payload is required
    thirdpartyError:
      type: object
      properties:
        message:
          type: string
          example: Something wrong
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: GEN_004
            message:
              type: string
              example: An unexpected server error occurred.
    NotFoundError:
      type: object
      properties:
        message:
          type: string
          example: Something wrong
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: ABC_001
            message:
              type: string
              example: not found
    serverError:
      type: object
      properties:
        message:
          type: string
          example: Something wrong
        status:
          type: string
          example: error
        timestamp:
          type: string
          example: '2025-05-07T07:31:30.824Z'
        path:
          type: string
          example: /v2/starpay-api/
        error:
          type: object
          properties:
            code:
              type: string
              example: GEN_004
            message:
              type: string
              example: An unexpected server error occurred.
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    Unauthorized:
      description: Unauthorized.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/thirdpartyError'
    NotFound:
      description: Not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    ServerError:
      description: internal.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/serverError'

````