docs

List refunds

Lists refunds with optional filters for charge and pagination.

GET
/refunds

Lists refunds with optional filters for charge and pagination.

Authorization

api-key
AuthorizationBearer <token>

API key for merchant integrations. Send as Authorization: Bearer <your key>.

In: header

Query Parameters

chargeId?string

Filter by charge ID

limit?number

Number of results (max 100)

offset?number

Pagination offset

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/refunds"
{
  "data": [
    {
      "id": "re_abc123",
      "chargeId": "ch_xyz789",
      "amount": "50000",
      "currency": "EGP",
      "status": "succeeded",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "hasMore": false
}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "No valid API key provided.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#authentication_required"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "The API key does not have permission to perform this action.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#permission_denied"
  },
  "request_id": "req_abc123def456"
}
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#internal_error"
  },
  "request_id": "req_abc123def456"
}

Delete a price DELETE

Deletes a price. Only prices that have never been referenced by a line item can be deleted — once a price has been used in any checkout session or payment link, archive it instead. If the price is set as the default price for a product, the default price reference will be cleared.

Create a refund POST

Creates a full or partial refund for a successful charge. Target: provide EXACTLY ONE of `chargeId` or `paymentIntentId`. When `paymentIntentId` is supplied the server resolves it to the unique succeeded charge under that intent; the request is rejected if the intent has zero or multiple succeeded charges. Features: - Full or partial refunds - Ledger reversal (double-entry bookkeeping) - Balance updates (debits available funds) - Updates `charge.amountRefunded` - Updates `paymentIntent.amountRefunded` Refund behaviour: - Hits available balance immediately (no hold period) - Creates negative balance transactions - Reverses the original charge's ledger entries - Platform keeps fees (business decision)