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

# Cancel Escrow

> Cancel an existing escrow transaction and initiate buyer refund if applicable.

# Cancel Escrow

Cancel an active escrow transaction. When an escrow order is cancelled before fulfillment or release of funds, StarPay marks the transaction as cancelled and initiates the refund workflow for the customer.

## Endpoint

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

## 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 you wish to cancel.

Type: `string` — Required

Example:

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

***

## Example Request

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

***

## Response

### Success Response (`200 OK`)

```json theme={null}
{
  "status": "success",
  "timestamp": "2026-07-29T11:30:00Z",
  "message": "Escrow cancelled successfully",
  "data": {
    "escrowId": "59667344",
    "status": "CANCELLED",
    "cancelledAt": "2026-07-29T11:30:00Z"
  }
}
```

***

## Important Considerations

* **Cancellation Window**: An escrow order can only be cancelled while funds are in the held state and before allocations have been fully released to merchants.
* **Customer Refund**: Depending on the payment method used, the customer will receive an automatic refund or a refund credit in accordance with platform settlement policies.


## OpenAPI

````yaml POST /trdp/escrow/cancel
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/cancel:
    post:
      tags:
        - Escrow
      summary: Cancel Escrow
      description: >-
        Cancel an existing escrow transaction and initiate buyer refund if
        applicable.
      operationId: cancelEscrow
      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 to cancel.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelEscrowRequest'
      responses:
        '200':
          description: Escrow cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscrowCancelResponse'
        '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\"}",
            Encoding.UTF8, "application/json");

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

            const data = await response.json();

            console.log(data);
components:
  schemas:
    CancelEscrowRequest:
      type: object
      properties:
        escrowId:
          type: string
          example: '59667344'
          description: Unique escrow transaction identifier to cancel.
      required:
        - escrowId
    EscrowCancelResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        timestamp:
          type: string
          format: date-time
          example: '2026-07-29T11:30:00Z'
        message:
          type: string
          example: Escrow cancelled successfully
        data:
          type: object
          properties:
            escrowId:
              type: string
              example: '59667344'
            status:
              type: string
              example: CANCELLED
            cancelledAt:
              type: string
              format: date-time
              example: '2026-07-29T11:30: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'

````