Skip to main content

Payment items and refunds API

Check API availability and confirm access in your target environment before integrating.

OperationMethod and routeAvailability
Create a refundPOST /v1/refundsAvailability pending
Retrieve a refundGET /v1/refunds/{id}Availability pending
List refundsGET /v1/refundsAvailability pending
Cancel a refundPOST /v1/refunds/{id}/cancelAvailability pending
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​

AttributeTypeDescription
attempt_idstringPayment identifier used to create a refund
amount_receivedstringCumulative received amount that has reached finalized confirmation
amount_refundedstringAmount successfully refunded
amount_refundablestringCurrent refundable amount, excluding successful refunds and amounts reserved by ongoing refunds
currencystringPayment stablecoin: usdc or usdt
chainintegerPayment 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.

AttributeLocationTypeRequiredDescription
idpathstringYesCheckout identifier
page_sizequeryintegerNoPage size; default 20, range 1–100
page_tokenquerystringNoPrevious 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​

AttributeTypeDescription
idstringUnique refund identifier
attempt_idstringSelected payment identifier; immutable
payment_intentstringOriginal payment's identifier; the ongoing-refund limit covers all its payment items
amountstringImmutable decimal amount in currency units actually received by the payer
currencystringusdc or usdt
statusstringRefund lifecycle status, below
payment_methodobjectImmutable refund method and destination
next_actionobject / nullRequired merchant action; null when none is required
last_execution_errorobject / nullLatest confirmed execution failure, containing code/message; null before any failure or after success
descriptionstring / nullMerchant description
metadataobjectString key/value pairs; empty {} when absent. Maximum 50 pairs, key length 40 characters, value length 500 characters
created_atstringCreation time in UTC RFC 3339
updated_atstringLast update time in UTC RFC 3339

The merchant pays gas separately; it is not deducted from amount.

Status​

ValueMeaning
requires_actionWaiting for merchant wallet execution, including retry after a confirmed previous failure
processingAn execution outcome remains unknown while chain results are reconciled
succeededRefund transfer has reached finalized confirmation
canceledRefund 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​

AttributeTypeDescription
typestringCurrently erc20_transfer: a direct ERC-20 refund outside IPP private payment
erc20_transferobjectERC-20 transfer details
erc20_transfer.chainintegerEIP-155 network of the selected attempt_id
erc20_transfer.recipient_addressstringPlatform-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​

AttributeTypeDescription
typestringredirect: open the platform page
urlstringPlatform 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.

AttributeTypeDescription
codestringStable lowercase snake_case failure code
messagestringEnglish explanation; do not match its wording programmatically
CodeMeaning
transaction_revertedFinalized refund transaction reverted without completing the transfer
transaction_replacedOriginal 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.

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique operation key; retain for retries
attempt_idbodystringYesIdentifier from payment items, owned by the current merchant with finalized receipts
amountbodystringYesPositive decimal in original stablecoin units, no greater than the item's amount_refundable; must fit asset precision and transfer range
payment_methodbodyobjectYesRefund method
payment_method.typebodystringYeserc20_transfer
descriptionbodystringNoRefund description
metadatabodyobjectNoString 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.

AttributeLocationTypeRequiredDescription
idpathstringYesRefund 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.

AttributeLocationTypeRequiredDescription
payment_intentquerystringNoFilter by original payment identifier
attempt_idquerystringNoFilter by payment identifier
statusquerystringNorequires_action, processing, succeeded or canceled
page_sizequeryintegerNoDefault 20; range 1–100
page_tokenquerystringNoPrior 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.

AttributeLocationTypeRequiredDescription
Idempotency-KeyheaderstringYesUnique operation key; retain for retries
idpathstringYesRefund 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 typeTrigger
refund.requires_actionRefund created or reenters requires_action after failed execution
refund.processingEnters processing while the result is reconciled
refund.succeededEnters succeeded after finalized confirmation
refund.canceledEnters 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.codeHTTP statusMeaningOperation
checkout_not_found404Missing or inaccessible CheckoutList payment items
refund_not_found404Missing or inaccessible RefundRetrieve, cancel
payment_attempt_not_found404Missing or inaccessible payment identifierCreate
payment_not_finalized400Item has no finalized receiptsCreate
refund_amount_exceeded400Amount exceeds remaining refundable balance, including exhausted fundsCreate
refund_in_progress409Same Payment Intent has an ongoing RefundCreate
refund_method_unsupported400Unsupported refund methodCreate
refund_not_cancelable400Refund cannot currently be canceledCancel

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.

Refund workflow · Common conventions