Receive and process refund requests
Availability pending confirmation
Merchant access to payment details and refund creation, retrieval, listing and cancellation remains unconfirmed. Execute the funds steps below only after the full flow is enabled for your account and target environment. Until then, record support requests, inspect the original order and assign an owner; do not promise automatic refunds or a fixed receipt time.
A refund targets an actual payment item rather than the business order amount. The current contract fixes the original network, stablecoin and refund recipient. A merchant cannot substitute an address supplied in chat. Refunds use direct ERC-20 transfers rather than IPP private payments. The merchant pays Gas separately and the payer receives the full refund amount.
Receive the support request
- Record the order, Checkout, reason and requested resolution. Check delivery and earlier refund requests.
- Treat service cancellation, entitlement removal, accounting adjustments and funds return separately. Canceling an order does not refund money.
- Confirm access to both payment details and the refund flow. If unavailable, retain a pending case and agree next steps through a verified channel.
Once the flow is enabled
- Retrieve the original Checkout's payment items and identify
attempt_id. Only finalized funds count toward refundable receipt; Checkout success alone does not establish refund eligibility. - Check current
amount_refundable, which already excludes successful refunds and amounts reserved by pending refunds. Use an agreed partial amount or the current remaining allowance to refund in full; handle different payment items separately. - Check for an existing pending refund. At most one
requires_actionorprocessingrefund is allowed per Payment Intent, including across its payment items. - Have an authorized operator approve the amount and reason. The integration must persist the support case, parameters and operation's idempotency key before creating the refund. Save its Refund ID; creation is not completion.
- Open the actual returned
next_action.url, verify the original payment association and amount, then use the merchant wallet. Do not construct the page URL or ask for the customer's private key. - Query the original task until its outcome is established, then update the case and customer.
Use exact decimal amounts meeting the original asset's precision and transfer range, with a general maximum of eight decimal places. Do not use floating-point calculations or automatically round to two decimals.
Follow the result
| Result | Action |
|---|---|
requires_action | Await wallet action; if a transaction was already sent, inspect that execution before another transfer |
processing | Await verification; do not resend or cancel |
succeeded | Transfer is finalized; record completion and refunded amount |
canceled | The reservation is released; do not execute this Refund again |
| Timeout, rejected signature or closed page | Not proof of completion; query the original task and preserve its association |
A confirmed execution failure is reported through last_execution_error; it is not a separate failed Refund status. Retry signing within the same Refund only after the platform confirms the old execution failed, no other execution is unknown, and status returns to requires_action. Funds remain reserved during failure handling.
Only requires_action permits a cancellation request, and cancellation is effective only when confirmed by the system. Signing can race with cancellation, so clicking cancel does not authorize a replacement refund. Recover uncertain results through the original operation rather than issuing another refund under a new key.
Resolve problems
For insufficient allowance, inspect pending reservations and completed refunds. Resolve high Gas or wallet balance requirements without deducting Gas from the customer's amount. This flow does not allow changing network, asset or recipient. Identify duplicate and late funds using payment exceptions, then reconcile through fees.