Issue full and partial refunds
Payment-item and refund availability is pending. Confirm your account and environment support payment-item retrieval and refund creation, retrieval and cancellation before enabling this flow. See API availability.
Refund an actual payment item rather than simply returning the order amount due. First retrieve a Checkout's payment items and select attempt_id, then create a Refund. The platform fixes the original network, stablecoin and refund recipient; merchants cannot redirect it. Refunds are direct ERC-20 transfers outside IPP private payment. Merchants pay gas separately and the payer receives the complete amount.
Prepare server-side values
Before starting, confirm the test environment enables the required payment-item and refund operations. Replace the Key, Checkout/Refund IDs and example attempt_id with actual values. Replace example idempotency keys with your own persisted keys for new operations. Keep the Key on your server and deliver only necessary interaction information to the wallet frontend.
export API_BASE='https://connect-dev.invisipay.fi'
export API_KEY='inv_test_REPLACE_WITH_YOUR_SERVER_KEY'
export CHECKOUT_ID='checkout_REPLACE_WITH_YOUR_CHECKOUT_ID'
export REFUND_ID='re_REPLACE_WITH_CREATED_REFUND_ID'
export REFUND_CREATE_KEY='550e8400-e29b-41d4-a716-446655440000'
export REFUND_CANCEL_KEY='ec3a7e90-673e-41a1-94d0-6724fba6a339'
1. Select an item and refundable amount
curl --fail-with-body --silent --show-error --get \
"$API_BASE/v1/checkouts/$CHECKOUT_ID/payments" \
-H "Authorization: Bearer $API_KEY" \
--data-urlencode 'page_size=20'
Example payment item, shown without the surrounding pagination envelope:
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "20",
"amount_refunded": "2.5",
"amount_refundable": "17.5",
"currency": "usdc",
"chain": 56
}
Only finalized receipts count toward amount_received. Checkout succeeded alone does not establish refund eligibility. amount_refundable excludes successful refunds and ongoing reservations. Here 17.5 USDC remains: 2.5 is a partial refund; 17.5 refunds the currently remaining amount in full. Do not refund the original 20 again.
Repeated receipts for one item increase its cumulative amount and may be refunded together. Different attempt_id values require separate Refunds. At most one Refund per Payment Intent may be requires_action or processing, including across different attempts. The Refund payment_intent field identifies the original payment; the ongoing-refund limit spans all its payment items.
Use positive decimal strings in currency units. The common maximum is eight decimal places, but the amount must also fit the original asset's exact precision and transfer range. For a six-decimal asset, a nonzero seventh decimal place is invalid; the service never rounds. Avoid floating point amount calculations.
2. Create and store the Refund
This example uses a placeholder payment item and partially refunds 2.5 USDC. The platform derives payment_intent, currency, network and recipient from attempt_id; do not add those fields:
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/refunds" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $REFUND_CREATE_KEY" \
--data '{"attempt_id":"8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21","amount":"2.5","payment_method":{"type":"erc20_transfer"},"description":"Price adjustment","metadata":{"return_id":"RETURN_001"}}'
HTTP 200 returns a complete Refund initially in requires_action. Store its id, attempt_id, payment_intent, amount and association with the local return case. HTTP success establishes the refund goal, not a completed transfer.
The amount and payment item are immutable. To adjust them, successfully cancel the original Refund before creating another within the remaining allowance. After timeout or crash, reuse the original Idempotency-Key and identical parameters. Valid replay returns the first result rather than current state. After 24 hours, establish the original outcome before considering another operation.
3. Open wallet signing and reconcile
In requires_action, open the returned next_action.url so the merchant can sign through the platform wallet page. Do not construct the URL, and do not call an additional confirm-refund API. Opening, signing or closing the page does not establish refund success.
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/refunds/$REFUND_ID" \
-H "Authorization: Bearer $API_KEY"
| status | Next step |
|---|---|
| requires_action | Await signing; if a transaction was already sent, reconcile it before another execution |
| processing | Platform reconciles an unknown chain outcome; do not transfer again or cancel |
| succeeded | Refund transfer finalized; update the return case without executing again |
| canceled | Reservation released; this Refund cannot execute |
Confirmed execution failures appear in last_execution_error, such as transaction_reverted or transaction_replaced. Retry signing within the same Refund only after the platform confirms the old execution failed, no unresolved execution remains and status returns to requires_action. Funds stay reserved during failure recovery. Rejected signing, insufficient funds/gas before wallet submission and unknown broadcast outcomes are not confirmed chain failures.
4. Cancel or reconcile records
Only requires_action may request cancellation, subject to the result. processing and succeeded reject it. Use a separate cancellation key and {} body; funds release only after successful cancellation:
curl --fail-with-body --silent --show-error \
"$API_BASE/v1/refunds/$REFUND_ID/cancel" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H "Idempotency-Key: $REFUND_CANCEL_KEY" \
--data '{}'
If cancellation is unknown, reconcile/retry using its original key before creating a replacement. Deduplicate refund.* notifications by event ID and authenticate a fresh Refund read so out-of-order events cannot replace current state. Refunds do not rewrite the original Payment Intent's primary state; track refunded order amounts separately.
refund_amount_exceeded indicates insufficient refundable funds, payment_not_finalized means no finalized receipt, and refund_in_progress means another ongoing goal for the same Payment Intent. These request errors do not set last_execution_error. See the complete payment-item and refund API for fields, filters, notifications and errors.