Refunds (Beta)

(Note: This API is currently in Beta)

The Refunds API allows you to retrieve details about refunds processed for transactions associated with your merchant account.

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