Refund held funds

POST

escrows

{escrowId}

refund

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "escrowId": "esc_01hxyz",
    "reference": "order_12345",
    "status": "awaiting_funding",
    "amount": 400,
    "currency": "NGN",
    "releasedAmount": 0,
    "refundedAmount": 0,
    "remainingAmount": 400,
    "feeAmount": 107.5,
    "merchantFee": 100,
    "parties": [
      {
        "customerId": "cus_01hxyz",
        "role": "payer",
        "guest": {
          "email": "[email protected]",
          "name": "John Doe",
          "phone": "+2348012345678"
        }
      }
    ],
    "description": "<string>",
    "cancelledReason": "<string>",
    "fundedAt": null,
    "releasedAt": null,
    "refundedAt": null,
    "pendingProviderRefund": null
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

Authorizations

Authorization

string

header

required

Secret API key. Use sk_test_... for sandbox data or sk_live_... for live data (after verification and live mode). Do not use pk_ keys.

Headers

Idempotency-Key

string

required

Path Parameters

escrowId

string

required

Body

application/json

Optional amount in naira (defaults to remaining held) and optional reason.

amount

number

Amount to refund in naira. Omit to refund the remaining held balance.

Example:

400

reason

string

Why the funds are being refunded.

Example:

"unable_to_fulfill"

Response

Resource created

success

boolean

Example:

true

data

object

Show child attributes

meta

object

Show child attributes

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "escrowId": "esc_01hxyz",
    "reference": "order_12345",
    "status": "awaiting_funding",
    "amount": 400,
    "currency": "NGN",
    "releasedAmount": 0,
    "refundedAmount": 0,
    "remainingAmount": 400,
    "feeAmount": 107.5,
    "merchantFee": 100,
    "parties": [
      {
        "customerId": "cus_01hxyz",
        "role": "payer",
        "guest": {
          "email": "[email protected]",
          "name": "John Doe",
          "phone": "+2348012345678"
        }
      }
    ],
    "description": "<string>",
    "cancelledReason": "<string>",
    "fundedAt": null,
    "releasedAt": null,
    "refundedAt": null,
    "pendingProviderRefund": null
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

customers

escrows

checkout

transactions

wallets

payouts

fees

identity

Authorizations

Headers

Path Parameters

Body

Response