> ## 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.

# Release Escrow Allocation

> Release held escrow funds for a specific merchant allocation upon successful order fulfillment.

# Release Escrow Allocation

Release held escrow funds for a specific merchant allocation once the corresponding product or service has been fulfilled.

In marketplace scenarios where an order is split across multiple vendors, each merchant's allocation can be released independently as their items are shipped or delivered.

## Endpoint

```http theme={null}
POST /trdp/escrow/release
```

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

### escrowId

The unique identifier of the escrow transaction returned during order creation.

Type: `string` — Required

Example:

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

***

### merchantId

The merchant ID corresponding to the allocation you want to release.

Type: `string` — Required

Example:

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

***

## Example Request

```bash theme={null}
curl --request POST \
  --url https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/release \
  --header 'Content-Type: application/json' \
  --header 'x-api-secret: SplFeYdc/Hc5S1CGmVDtETLYUJY/10a38ejamzwb1YH30h+u8sOK2fpTlyKitpPk' \
  --data '{
    "escrowId": "59667344",
    "merchantId": "01344351"
  }'
```

***

## Response

### Success Response (`200 OK`)

```json theme={null}
{
  "status": "success",
  "timestamp": "2026-07-29T11:00:00Z",
  "message": "Escrow allocation released successfully",
  "data": {
    "escrowId": "59667344",
    "merchantId": "01344351",
    "amount": 3000,
    "releaseStatus": "RELEASED",
    "releasedAt": "2026-07-29T11:00:00Z"
  }
}
```

***

## Notes & Best Practices

* **Partial Releases**: If an order contains multiple merchant allocations, you can call this endpoint separately for each merchant as they fulfill their part of the order.
* **Idempotency**: Releasing an allocation that has already been released will return the existing release confirmation or an error indicating the allocation was previously settled.
* **Unreleased Allocations**: Any remaining unreleased allocations continue to be held securely in escrow until explicitly released or cancelled.


## OpenAPI

````yaml POST /trdp/escrow/release
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/release:
    post:
      tags:
        - Escrow
      summary: Release Escrow Allocation
      description: >-
        Release held escrow funds for a specific merchant allocation upon
        successful order fulfillment.
      operationId: releaseEscrowAllocation
      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 ID and merchant ID identifying the allocation to release.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleaseEscrowAllocationRequest'
      responses:
        '200':
          description: Escrow allocation released successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscrowReleaseResponse'
        '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("{\"escrowId\": \"59667344\",
            \"merchantId\": \"01344351\"}", Encoding.UTF8, "application/json");

            var response = await
            client.PostAsync("https://sandbox-api.starpayethiopia.com/v1/starpay-api/trdp/escrow/release",
            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/release',
            {
              method: 'POST',
              headers: {
                'Content-Type': 'application/json',
                'x-api-secret': 'YOUR_API_SECRET'
              },
              body: JSON.stringify({
                escrowId: '59667344',
                merchantId: '01344351'
              })
            });

            const data = await response.json();

            console.log(data);
components:
  schemas:
    ReleaseEscrowAllocationRequest:
      type: object
      properties:
        escrowId:
          type: string
          example: '59667344'
          description: Unique escrow transaction identifier.
        merchantId:
          type: string
          example: '01344351'
          description: Merchant ID to receive payout.
      required:
        - escrowId
        - merchantId
    EscrowReleaseResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        timestamp:
          type: string
          format: date-time
          example: '2026-07-29T11:00:00Z'
        message:
          type: string
          example: Escrow allocation released successfully
        data:
          type: object
          properties:
            escrowId:
              type: string
              example: '59667344'
            merchantId:
              type: string
              example: '01344351'
            amount:
              type: number
              example: 3000
            releaseStatus:
              type: string
              example: RELEASED
            releasedAt:
              type: string
              format: date-time
              example: '2026-07-29T11:00:00Z'
      required:
        - status
        - timestamp
        - message
        - data
    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'

````