docs

Get refund by ID

Retrieves a refund with all details including ledger info.

GET
/refunds/{id}

Retrieves a refund with all details including ledger info.

Authorization

api-key
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

Refund ID

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/refunds/string"
Empty
{
  "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": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such refund: re_abc123",
    "doc_url": "https://docs.xpay.app/integrate/errors/api-error-codes#resource_missing"
  },
  "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"
}

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)

Balance Transaction

A Balance Transaction records every movement of money in or out of your xpay balance: successful charges, refunds, payouts, processing fees, and adjustments. Each Balance Transaction links back to its `source` (the Charge, Refund, or Payout that produced it) and breaks down `gross`, `fee`, and `net` amounts. Use Balance Transactions to reconcile what was paid into your account against what was settled to your bank.