Refund — XPay docs

A Refund returns funds from a successful Charge back to the customer's original payment method. Refunds can be full or partial, and a single Charge can be refunded multiple times up to its original amount. The Refund's `status` reflects the processor's progress as the money makes its way back: `pending` while in flight, `succeeded` once the funds have been returned, or `failed` if the processor rejected the request.

id*string

Unique identifier for the refund

object*string

Object type

amount*number

Refund amount in smallest currency unit

chargeId*string

ID of the charge being refunded

paymentIntentId*string

ID of the PaymentIntent being refunded

balanceTransactionId*|

ID of the balance transaction for the refund, null until settled

failureBalanceTransactionId*|

Balance transaction for failed refund reversal, null unless the refund failed

externalRefundId*|

Processor-side refund id, null when not yet reconciled

createdAt*string

Time at which the refund was created (ISO 8601)

currency*string

Three-letter ISO currency code

Value in"EGP" | "USD" | "EUR" | "GBP" | "SAR" | "AED" | "QAR" | "KWD" | "JOD" | "OMR" | "BHD" | "LYD" | "AUD" | "CAD" | "CNY"

presentmentDetails?

Customer-facing view of the refund — amount in the original charge's presentment currency using the charge's LOCKED exchange rate. Populated only when the charge had a presentment currency different from processing.

status*string

Status of the refund (pending, requires_action, succeeded, failed, canceled)

Value in"PENDING" | "REQUIRES_ACTION" | "SUCCEEDED" | "FAILED" | "CANCELED"

reason?string

Reason for the refund

Value in"DUPLICATE" | "FRAUDULENT" | "REQUESTED_BY_CUSTOMER" | "RISK_HOLD_CAPTURE"

failureReason?string

Reason for refund failure

Value in

"lost_or_stolen_card" | "expired_or_canceled_card" | "charge_for_pending_refund_disputed" | "insufficient_funds" | "declined" | "merchant_request" | "unknown"

pendingReason?string

Reason for pending status

Value in"processing" | "insufficient_funds" | "charge_pending"

description?string

Description for non-card refunds

destinationDetails?

Payment method-specific refund details

nextAction?

Next action if requires_action

instructionsEmail?string

Email for refund instructions

receiptNumber?string

Receipt number for email receipts

feeAmount?number

Original platform fee (NOT refunded - kept by platform)

{
  "id": "re_abc123",
  "object": "refund",
  "amount": 50000,
  "chargeId": "ch_xyz789",
  "paymentIntentId": "pi_xyz789",
  "balanceTransactionId": "string",
  "failureBalanceTransactionId": "string",
  "externalRefundId": "string",
  "createdAt": "2025-03-25T12:00:00.000Z",
  "currency": "EGP",
  "presentmentDetails": {
    "amount": 80000,
    "currency": "KWD",
    "exchangeRate": 168.2,
    "exchangeRateId": "exr_3gQWCqaDsihr09Fi5MfwXL"
  },
  "status": "PENDING",
  "reason": "DUPLICATE",
  "failureReason": "lost_or_stolen_card",
  "pendingReason": "processing",
  "description": "string",
  "destinationDetails": {
    "type": "card",
    "card": {
      "reference": "string",
      "referenceStatus": "pending",
      "referenceType": "string",
      "type": "pending"
    },
    "wallet": {
      "reference": "string",
      "provider": "string"
    },
    "bankTransfer": {
      "reference": "string",
      "referenceStatus": "pending"
    },
    "kiosk": {
      "reference": "string",
      "provider": "string"
    }
  },
  "nextAction": {
    "type": "string",
    "displayDetails": {
      "emailSentAt": "string",
      "emailSentTo": "string",
      "expiresAt": "string"
    }
  },
  "instructionsEmail": "string",
  "receiptNumber": "string",
  "feeAmount": 0
}