Sign in

v1

latestOpenAPI 3.0.32026-07-264469137.7 KB
Refunds

Create a refund

Create a refund for a completed payment. Only one refund can be created per charge.

post/v1/refunds

Request body

charge_idstring required

The ID of the payment to refund.

referencestring required

Your unique identifier for this refund. Must be unique per organization and environment.

refund_addressstring nullable

Destination wallet address for crypto refunds. Required when the charge currency is a cryptocurrency.

amountstring nullable

Optional partial refund amount in the charge settlement currency. Omit to refund the full remaining refundable balance.

fee_bearer'org' | 'customer' nullable

Who bears the refund processing fee. org (default) charges the fee to your balance; customer deducts it from the amount returned to the customer.

reasonstring nullable

Human-readable reason for the refund.

idempotency_keystring nullable

A key you supply to make this request idempotent. If you send the same idempotency_key twice for the same charge, the second request returns the existing refund.

simulated_outcome'success' | 'failed' nullable

Test mode only. Force a specific refund outcome. Omit to use the default sandbox outcome.

Example request

{
  "charge_id": "chr_1a2b3c4d5e6f",
  "reference": "refund_9876",
  "refund_address": "0xabc123def456",
  "amount": "10.00",
  "fee_bearer": "ORG",
  "reason": "Customer requested cancellation",
  "idempotency_key": "idem_9f8e7d6c5b",
  "simulated_outcome": "success"
}

Response

Success - Refund created

refund_idstring

Unique identifier for this refund.

charge_idstring

The payment this refund is associated with.

referencestring

The reference you supplied on creation.

status'processing' | 'success' | 'failed'

Current refund status. processing = awaiting provider (1-5 business days); success = funds returned to customer; failed = refund rejected.

requested_amountstring

The refund amount you requested, in the charge's settlement currency.

refunded_amountstring nullable

The amount actually returned to the customer. Null until the refund completes or partially settles.

refund_fee_amountstring

Fee charged for this refund, in the charge's settlement currency. "0" if no fee applies.

fee_bearer'org' | 'customer'

Who bears the refund processing fee. org means the merchant absorbs the fee; customer means it is deducted from the refunded amount.

reasonstring nullable

The reason you provided, or null if none was given.

created_atstring date-time

ISO 8601 timestamp when the refund was created.

updated_atstring date-time

ISO 8601 timestamp of the last status update.

completed_atstring date-time nullable

ISO 8601 timestamp when the refund reached a terminal status (SUCCESS or FAILED). Null while still processing.

Example response

{
  "refund_id": "ref_1a2b3c4d5e",
  "charge_id": "chr_1a2b3c4d5e6f",
  "reference": "refund_9876",
  "status": "processing",
  "requested_amount": "29.00",
  "refund_fee_amount": "0.00",
  "fee_bearer": "merchant",
  "reason": "Customer requested cancellation",
  "created_at": "2026-04-27T12:00:00Z",
  "updated_at": "2026-04-27T12:00:00Z"
}