Refund a payment
Refund a captured payment in full or in part. Opens an internal claim that releases funds back through the same provider.
/api/v1/payments/{id}/refundSelect a stage to see what happens.
/payments/{id}/refund- Authorization
- Bearer ••••••••
- Accept
- application/json
Prepare the request
Use credentials for the selected environment and complete the required parameters.
Illustrative flow · no data is sent
How this endpoint works
Refund a captured payment. Internally opens a `user_dispute` claim against the source transaction so refunds share the exact same atomic ledger movement (freeze → resolve_approved → release) the chargeback flow uses — keeps the books consistent. The `amount` is in the LOCAL CURRENCY of the original transaction (e.g. MXN for a SPEI charge in Mexico) and uses MAJOR units (e.g. `10` = 10 MXN). Same convention as POST /payments. Omit to refund the full transaction amount.
Request parameters
Expand a field to see its format and requirements.
amountnumber
Local-currency major units. Optional — defaults to the full transaction `amountLocal`. Must be ≤ the captured amount remaining.
reasonstring
Free-form ≤500 chars. Surfaces on the claim record and the dashboard. Common values: `requested_by_customer`, `duplicate`, `fraudulent`, `other`.
Integration details
Currency, behavior and additional notes for this operation.
amount is in local-currency major units (the same field type as the original amountLocal you received on POST /payments), NOT cents. If the original payment was 882.17 MXN and you want to refund 100 MXN, send amount: 100. The response echoes the same units back, plus an amountUsd for cross-currency reporting.CLM- reflects that. The field name refundId on the response is the public identifier you store; use it on GET /api/v1/claims/{id} if you need to fetch its resolution state later.