Payment items and refunds API
Check API availability and confirm access in your target environment before integrating.
| Operation | Method and route | Availability |
|---|---|---|
| Create a refund | POST /v1/refunds | Availability pending |
| Retrieve a refund | GET /v1/refunds/{id} | Availability pending |
| List refunds | GET /v1/refunds | Availability pending |
| Cancel a refund | POST /v1/refunds/{id}/cancel | Availability pending |
Payment-item retrieval and refund operations remain pending availability. Confirm availability for your account and target environment before integrating. See API availability.
Select a payment item using its attempt_id, then create a Refund for a return, price adjustment or duplicate payment. Each Refund permanently references one payment item. The platform determines its recipient, network and stablecoin from that item.
After creation, the merchant signs through the platform's wallet page. A Refund does not change the original Payment Intent's primary state. Amounts, timestamps and metadata follow common conventions.
Payment items
Query a Checkout's payment items and choose an attempt_id for the refund. Repeated receipts for the same payment item increase that item's cumulative received amount; different payment items are shown separately. Historical payments and subsequent receipts remain queryable after the Checkout has ended.
Attributes
| Attribute | Type | Description |
|---|---|---|
attempt_id | string | Payment identifier used to create a refund |
amount_received | string | Cumulative received amount that has reached finalized confirmation |
amount_refunded | string | Amount successfully refunded |
amount_refundable | string | Current refundable amount, excluding successful refunds and amounts reserved by ongoing refunds |
currency | string | Payment stablecoin: usdc or usdt |
chain | integer | Payment network's EIP-155 chain ID |
Amounts use currency units and may be "0"; other formatting follows common conventions. Receipts that have not reached finalized confirmation do not count toward amount_received or refundable funds.
Payment item example
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "20",
"amount_refunded": "2.5",
"amount_refundable": "17.5",
"currency": "usdc",
"chain": 56
}
List payment items
GET /v1/checkouts/{id}/payments
Returns detected payment items for the specified Checkout owned by the current merchant. Sort order is descending payment-item creation time, then descending attempt_id when timestamps match.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Checkout identifier |
page_size | query | integer | No | Page size; default 20, range 1–100 |
page_token | query | string | No | Previous response's next_page_token; omit on the first page |
A missing or inaccessible Checkout returns 404. No Idempotency-Key or body is required. Follow pagination conventions; returned amounts can change with new payments or refund progress.
Request example:
GET /v1/checkouts/checkout_example/payments?page_size=20
Authorization: Bearer inv_test_...
Response: 200 OK. Each data entry is a complete payment item. An empty next_page_token ends pagination.
{
"data": [
{
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"amount_received": "20",
"amount_refunded": "2.5",
"amount_refundable": "17.5",
"currency": "usdc",
"chain": 56
}
],
"next_page_token": ""
}
If no payment has been detected, return {"data":[],"next_page_token":""}.
Refund eligibility and amounts
Only received amounts that have reached finalized confirmation are refundable. Checkout status succeeded alone does not establish eligibility. When a payment item includes unfinalized receipts, its already-finalized refundable portion can still be refunded.
Each item supports partial and repeated refunds. Its current amount_refundable equals cumulative finalized receipts minus successful refunds and funds reserved by ongoing refunds. Use the current payment-item value rather than computing availability from the original order amount.
Repeated receipts for one item may be refunded together in one Refund. Different payment items require separate Refunds. Total refunds for one Payment Intent may exceed its amount due, but refunded plus reserved amounts for each item must not exceed that item's finalized receipts.
At most one Refund per Payment Intent may be in requires_action or processing. Create another only after the preceding Refund succeeds or is canceled, subject to remaining funds. This concurrency boundary applies to the Payment Intent, not merely the selected attempt_id.
Refunds awaiting merchant action or processing retain their reservation. A failed execution retries within the original Refund without releasing funds. Successful cancellation releases the reservation; successful refund increases amount_refunded.
Amounts must be exactly representable at the original asset's precision and within its transfer amount range. The API never rounds. Invalid precision or range returns a 400 parameter error without creating a Refund. Amount is immutable after creation; to change it, first successfully cancel and then create another Refund.
An unfinished Refund may request cancellation where allowed by the operation result. Cancellation is forbidden while an execution outcome is unknown. A timeout or closed page does not cancel a Refund or release funds.
Refund attributes
| Attribute | Type | Description |
|---|---|---|
id | string | Unique refund identifier |
attempt_id | string | Selected payment identifier; immutable |
payment_intent | string | Original payment's identifier; the ongoing-refund limit covers all its payment items |
amount | string | Immutable decimal amount in currency units actually received by the payer |
currency | string | usdc or usdt |
status | string | Refund lifecycle status, below |
payment_method | object | Immutable refund method and destination |
next_action | object / null | Required merchant action; null when none is required |
last_execution_error | object / null | Latest confirmed execution failure, containing code/message; null before any failure or after success |
description | string / null | Merchant description |
metadata | object | String key/value pairs; empty {} when absent. Maximum 50 pairs, key length 40 characters, value length 500 characters |
created_at | string | Creation time in UTC RFC 3339 |
updated_at | string | Last update time in UTC RFC 3339 |
The merchant pays gas separately; it is not deducted from amount.
Status
| Value | Meaning |
|---|---|
requires_action | Waiting for merchant wallet execution, including retry after a confirmed previous failure |
processing | An execution outcome remains unknown while chain results are reconciled |
succeeded | Refund transfer has reached finalized confirmation |
canceled | Refund canceled; execution ends and reserved funds are released |
A Refund expresses the refund goal. One failed execution does not end it. It returns from processing to requires_action only after the previous execution is confirmed failed and no other execution remains unresolved, allowing a new signature on the same Refund.
Rejected signing or closing the signing page leaves requires_action. Unknown broadcast results, a transaction temporarily not found, or rollback before finality leave processing; they do not justify a new transfer. Closing the page does not revoke an already-signed transaction. Reconcile the original execution first to avoid duplicate refunds. succeeded and canceled are terminal and cannot execute again.
payment_method
| Attribute | Type | Description |
|---|---|---|
type | string | Currently erc20_transfer: a direct ERC-20 refund outside IPP private payment |
erc20_transfer | object | ERC-20 transfer details |
erc20_transfer.chain | integer | EIP-155 network of the selected attempt_id |
erc20_transfer.recipient_address | string | Platform-determined original payer refund address; immutable |
The merchant selects type=erc20_transfer. The platform derives network, stablecoin asset and recipient from attempt_id; merchants cannot override them. Creation is rejected if the refund recipient cannot be established reliably.
next_action
| Attribute | Type | Description |
|---|---|---|
type | string | redirect: open the platform page |
url | string | Platform page where the merchant signs with a wallet |
Present only for requires_action; otherwise null. Opening the page or signing does not establish success: use status.
last_execution_error
Records the latest confirmed execution failure without ending the Refund. A new failure replaces the previous value. It persists during retry or cancellation and clears after refund success.
| Attribute | Type | Description |
|---|---|---|
code | string | Stable lowercase snake_case failure code |
message | string | English explanation; do not match its wording programmatically |
| Code | Meaning |
|---|---|
transaction_reverted | Finalized refund transaction reverted without completing the transfer |
transaction_replaced | Original transaction was conclusively replaced and the replacement did not complete this refund |
Invalid API requests use HTTP error, without setting this field. Rejected signatures, insufficient wallet funds or gas before submission, and unknown outcomes do not create an execution error. Determine retry permission from status.
Refund example
{
"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"
}
Create a refund
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"
}
Retrieve a refund
GET /v1/refunds/{id}
Read current status, signing entry and latest execution error to restore a signing page or reconcile results.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Refund identifier |
Only the current merchant's Refund is readable. Missing or inaccessible refunds return 404 under common error conventions. No Idempotency-Key or body is required.
Request:
GET /v1/refunds/re_example
Authorization: Bearer inv_test_...
Response: 200 OK, the complete Refund. This example has succeeded and needs no wallet action:
{
"id": "re_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "succeeded",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": null,
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:05:00Z"
}
List refunds
GET /v1/refunds
Returns the current merchant's Refunds in descending creation time, then descending ID. All statuses are included unless filtered. Multiple filters are combined.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
payment_intent | query | string | No | Filter by original payment identifier |
attempt_id | query | string | No | Filter by payment identifier |
status | query | string | No | requires_action, processing, succeeded or canceled |
page_size | query | integer | No | Default 20; range 1–100 |
page_token | query | string | No | Prior next_page_token; omit on first page |
Keep filters unchanged when paginating. No Idempotency-Key or body is required.
Request:
GET /v1/refunds?payment_intent=pi_example&status=succeeded&page_size=20
Authorization: Bearer inv_test_...
Response: 200 OK, complete Refund objects in data; an empty next_page_token ends pagination.
{
"data": [
{
"id": "re_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "succeeded",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": null,
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:05:00Z"
}
],
"next_page_token": ""
}
No matches returns {"data":[],"next_page_token":""}.
Cancel a refund
POST /v1/refunds/{id}/cancel
Only requires_action may request cancellation; the result determines whether cancellation is permitted. processing and succeeded reject cancellation. Canceling an already canceled Refund returns its current object.
| Attribute | Location | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | Yes | Unique operation key; retain for retries |
id | path | string | Yes | Refund identifier |
Send {} as the body. Only the current merchant may operate the Refund; missing or inaccessible objects return 404. Errors and idempotency follow common conventions.
Successful cancellation releases reserved funds before a replacement Refund can be created. If cancellation times out or is unknown, retry with the same key. A valid replay returns the first result.
Request:
POST /v1/refunds/re_cancel_example/cancel
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: ec3a7e90-673e-41a1-94d0-6724fba6a339
{}
Response: 200 OK, complete canceled Refund with next_action=null. Cancellation retains any previous execution error and does not add one:
{
"id": "re_cancel_example",
"attempt_id": "8b8fbb6b-4ec7-48d1-92a1-3b20c24b0c21",
"payment_intent": "pi_example",
"amount": "2.5",
"currency": "usdc",
"status": "canceled",
"payment_method": {
"type": "erc20_transfer",
"erc20_transfer": {
"chain": 56,
"recipient_address": "0x1234567890abcdef1234567890abcdef12345678"
}
},
"next_action": null,
"last_execution_error": null,
"description": "Price adjustment",
"metadata": {
"return_id": "RETURN_001"
},
"created_at": "2026-10-27T08:00:00Z",
"updated_at": "2026-10-27T08:01:00Z"
}
Refund webhook events
Configured webhook endpoints receive lightweight events. related_object.type is refund and related_object.id is the Refund ID. Retrieve the Refund for complete details.
| Event type | Trigger |
|---|---|
refund.requires_action | Refund created or reenters requires_action after failed execution |
refund.processing | Enters processing while the result is reconciled |
refund.succeeded | Enters succeeded after finalized confirmation |
refund.canceled | Enters canceled after successful cancellation |
Repeated checks of one state do not create new events; reentering it creates a new event. Retrieve last_execution_error for execution failure details.
Event example:
{
"id": "evt_refund_example",
"type": "refund.succeeded",
"related_object": {
"id": "re_example",
"type": "refund"
},
"created_at": "2026-10-27T08:05:00Z"
}
Deliveries may repeat or arrive out of order. Deduplicate by event id and retrieve current state; do not overwrite newer state with an older event. Retries of the same event retain its identifier and content. Receiving, signature verification and delivery retries follow the webhook contract.
Error codes
These errors use the common error envelope.
| error.code | HTTP status | Meaning | Operation |
|---|---|---|---|
checkout_not_found | 404 | Missing or inaccessible Checkout | List payment items |
refund_not_found | 404 | Missing or inaccessible Refund | Retrieve, cancel |
payment_attempt_not_found | 404 | Missing or inaccessible payment identifier | Create |
payment_not_finalized | 400 | Item has no finalized receipts | Create |
refund_amount_exceeded | 400 | Amount exceeds remaining refundable balance, including exhausted funds | Create |
refund_in_progress | 409 | Same Payment Intent has an ongoing Refund | Create |
refund_method_unsupported | 400 | Unsupported refund method | Create |
refund_not_cancelable | 400 | Refund cannot currently be canceled | Cancel |
These rejected requests do not set last_execution_error, which records execution failures only. Parameter, authentication, throttling and idempotency errors follow common conventions. Valid retries of the original request do not return refund_in_progress. Canceling an already canceled Refund returns its current object rather than refund_not_cancelable.