Create a refund
Availability pending. Check applicability.
Object and complete fields · Authentication, amounts and errors · Integration guide
POST /v1/refunds
Create a Refund for one payment item. It initially requires_action. Open next_action.url and sign with the merchant wallet; creation is not refund success.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique operation key; retain for retries |
attempt_id | body | string | Yes | Identifier from payment items, owned by the current merchant with finalized receipts |
amount | body | string | Yes | Positive decimal in original stablecoin units, no greater than the item's amount_refundable; must fit asset precision and transfer range |
payment_method | body | object | Yes | Refund method |
payment_method.type | body | string | Yes | erc20_transfer |
description | body | string | No | Refund description |
metadata | body | object | No | String key/value pairs subject to Refund metadata limits |
Do not supply payment_intent, currency, network or recipient; the platform derives them from attempt_id. Another ongoing Refund for the same Payment Intent blocks creation. Valid original-request idempotent retries return the first operation result under common rules, rather than refund_in_progress.
Request:
POST /v1/refunds
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount": "2.5",
"payment_method": {
"type": "erc20_transfer"
},
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
}
}
Response: 200 OK, the complete Refund. Use next_action.url without an additional confirm-refund API call.
{
"id": "re_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "requires_action",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": {
"type": "redirect",
"url": "https://connect.invisipay.fi/refunds/re_example"
},
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:00:00Z"
}