Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
Payment Refunds

Create a refund

Create a refund for a completed payment

post/v2/payment/refunds

Headers

x-client-idstring required

The API client id generated by UQPAY

x-on-behalf-ofstring

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts API. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

x-idempotency-keystring uuid

A unique identifier (UUID) used to maintain operation idempotency, ensuring that repeated executions of the same operation do not result in unintended effects or duplication. It helps preserve data consistency in the face of network errors, retries, or failures.

Request body

payment_intent_idstring required

The ID of the payment intent to refund

payment_attempt_idstring

The ID of the payment attempt to refund

amountstring required

The amount to refund

reasonstring required

The reason for the refund

metadataobject

Additional metadata for the refund

Example request

{
  "payment_intent_id": "PI1234567890123456789",
  "payment_attempt_id": "PA1234567890123456789",
  "amount": "10.01",
  "reason": "Return good",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_6789"
  }
}

Response

Refund created successfully

payment_refund_idstring

The unique identifier for the refund

payment_attempt_idstring

The ID of the payment attempt that was refunded

amountstring

The amount refunded

currencystring iso-4217

The three-letter currency code (ISO 4217)

refund_status'INITIATED' | 'PROCESSING' | 'SUCCEEDED' | 'FAILED' | 'REVERSAL_INITIATED' | 'REVERSAL_PROCESSING' | 'REVERSAL_SUCCEEDED'

The current status of the refund.

  • INITIATED: The refund has been initiated.
  • PROCESSING: The refund is being processed.
  • SUCCEEDED: The refund was successfully completed.
  • FAILED: The refund attempt failed.
  • REVERSAL_INITIATED: The reversal of the refund has been initiated.
  • REVERSAL_PROCESSING: The reversal of the refund is currently being processed.
  • REVERSAL_SUCCEEDED: The reversal of the refund was successfully completed.
create_timestring date/time
update_timestring date/time
reasonstring

The reason for the refund

metadataobject

Additional metadata associated with the refund. User-defined key-value pairs.

Example response

{
  "payment_refund_id": "RF123456789",
  "payment_attempt_id": "PA123456789",
  "amount": "10.01",
  "currency": "USD",
  "refund_status": "SUCCEEDED",
  "create_time": "2024-03-01T00:00:00+08:00",
  "update_time": "2024-03-01T00:00:00+08:00",
  "reason": "Order 1234 has been returned",
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_6789"
  }
}