Refunds

Note: This API is currently in Beta

Currently, creating refunds via the API is not supported; refunds are typically initiated through the merchant dashboard or other internal mechanisms.

Authentication

Requests require authentication using your API key in the `X-API-Key` header. See the Authentication guide.

The refund object

Represents a refund issued for a specific transaction. See Data Models for the full structure (Note: This link assumes the object will be added to data-models.mdx).

Endpoints

Get refund details

Retrieves the details of a specific refund by its unique ID.

Endpoint: `GET /refunds/{id}`

Path parameters:

Example response (200 OK):

{
  "success": true,
  "data": {
    "refund_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "transaction_id": "f0e9d8c7-b6a5-4321-fedc-ba9876543210", // Original transaction
    "amount": 5000.00, // Original transaction amount
    "refunded_amount": 5000.00, // Amount actually refunded
    "fee_amount": 150.00, // Original transaction fee
    "reason": "Customer requested refund due to duplicate charge",
    "status": "completed", // Can be: `` `pending` ``, `` `completed` ``, `` `failed` ``
    "metadata": {
      "processed_by": "support@your-company.com",
      "ticket_ref": "ZT-1234"
    },
    "created_at": "2025-04-05T10:30:00.123Z",
    "updated_at": "2025-04-05T10:35:15.456Z"
  },
  "environment": "test"
}

Error handling

Common errors include `400 Bad Request` for an invalid refund ID format, `401 Unauthorized`, `404 Not Found` if the refund ID doesn't exist or belong to the merchant, and `500 Internal Server Error`. Refer to the Errors guide for general structure and handling.