Refunds

Refunds let you return money for a paid order without rewriting the sale that already happened. They are line-item based, asynchronous, and tied to the customer’s original payment method.

Review and manage refunds with MCP

An authenticated AI agent can review a paid order and refundable lines, create a refund after confirming every amount and reason, check its current state, or attempt to cancel it while still pending.

MCP tools: get_order, get_refund_options, create_refund, get_refund or cancel_refund

Confirmed MCP actions require explicit form confirmation before Inttegro changes state.

Use this page to understand the refund product. Use the Refunds API reference for the exact request contract, response shape, and errors.

What refunds solve

A refund is the right tool when money has already been collected and some or all of it needs to go back to the customer.

Use refunds for:

returned items;
damaged, missing, or not-as-described items;
duplicate or mistaken charges;
order cancellations after payment;
fraud-related reversals; and
support adjustments tied to a paid order.

Do not edit a paid order to represent returned money. The order remains the record of the original sale. The refund becomes the record of the money sent back.

The refund model

Refunds are rooted in orders, but they have their own lifecycle.

Object	Role
Order	Original paid transaction.
Order line item	Specific part of the sale being refunded.
Refund	Durable request to return money for one or more order line items.
Refund line item	Allocation of one refund amount to one order line item.
Balance transaction	Financial evidence for reconciliation after money moves.

The API does not accept a refund destination or payment ID. Inttegro resolves those from the paid order so the money goes back through the original payment method.

Full and partial refunds

A full refund means you include every refundable line item for its remaining refundable amount. A partial refund returns only selected line items, or less than the remaining amount on those line items.

Line-item allocation is the key design choice. It lets support and finance answer exactly what was refunded later:

one returned product from a multi-item order;
shipping or fees associated with a return;
a partial goodwill adjustment; or
the entire paid order.

Each refund line amount must be positive, use the same currency as the original order line item, and fit within that line item’s remaining refundable amount. If a line has already been partially refunded, only the remaining refundable amount is available for later refunds.

Eligibility

Refund creation succeeds only when the order, line items, and merchant balance can support it.

The usual checks are:

the order is paid;
the order has a customer and an original payment method;
every order_line_item_id belongs to that order;
each order line item appears at most once in the request;
the requested amounts are positive and within what remains refundable;
the merchant balance is ready and sufficient; and
the request stays within the configured order line-item limit, currently 64 by default.

The current endpoint expects paid amounts that can be allocated exactly to supported refundable line types. Orders containing discounts, donations, subscriptions, or taxes are not currently refundable through this endpoint.

Reasons and evidence

Refunds require an overall reason. Use line-level reasons only when different items in the same refund need different explanations.

Choose the standard reason that best fits the case. Use custom only when the standard reasons are not specific enough, and include concise reason_details so the decision is understandable later.

Good refund records help three teams:

support can explain what happened to the customer;
finance can reconcile the returned amount; and
operations can detect product, fulfillment, or fraud patterns.

How refunds affect balances and payouts

Refunds affect two things at once: the order line item’s remaining refundable capacity and the merchant balance that could otherwise be paid out.

When Inttegro accepts a refund, it records a pending refund and reserves the needed capacity. That reservation prevents the same paid line item from being refunded twice, and prevents the same merchant funds from being selected for a payout while the refund is still unresolved.

Read the effect by lifecycle:

Refund state	Balance effect	Payout effect
`pending`	Refund capacity and merchant funds are reserved for the refund. A balance snapshot may show less available balance, refund activity, or reserved funds depending on timing.	Payout selection should not use the funds needed for that refund.
`processing`	Refund execution has started and the reservation is no longer cancellable.	Treat those funds as unavailable for new payouts.
`succeeded`	Balance transactions become the reconciliation evidence for the returned money.	The refunded funds are no longer available for payout.
`failed`	Read the sanitized `failure.reason`, `failure.detail`, and `failure.retryable` values before creating a new refund.	Do not schedule a replacement payout from assumptions; verify current balance and payout eligibility first.
`canceled`	If cancellation happens before refund execution starts, Inttegro releases the merchant balance hold and restores the reserved refundable capacity.	Released funds can be considered again by future payout selection if they satisfy the normal payout rules. They are not retroactively added to payouts already scheduled or executing.

This is why a payout can be lower than the dashboard number an operator expected. Between the time someone checks balance and the time payout selection runs, refunds can reserve or consume funds. Existing open payouts can also allocate funds first.

For operations, compare four records before explaining a difference: the refund, the current balance snapshot, related balance transactions, and any open or recent payouts for the same currency.

See How payouts use your balance for partial-allocation examples and how to reconcile a payout after a refund uses some of a source payment.

Lifecycle

Refund processing is asynchronous.

Status	Meaning	What to do
`pending`	The refund was accepted and is waiting for processing.	Store the refund ID and monitor it.
`processing`	Execution has started.	Do not cancel; wait for a terminal state.
`succeeded`	Money was returned successfully.	Notify the customer and reconcile.
`failed`	The refund did not complete.	Inspect the sanitized failure. Create a new refund only after resolving a retryable condition.
`canceled`	The refund was canceled before execution started.	Treat it as stopped; no money should move for that refund.

Poll Lookup a refund when your workflow needs the final result. Lifecycle timestamps are omitted until the transition happens.

Failed refunds include a caller-safe failure object. Its reason is a stable public category rather than a provider code, and unknown is the fail-closed fallback for an unclassified internal failure. Raw provider messages, routing details, credentials, and risk signals are never returned. An uncertain provider outcome stays processing while Inttegro reconciles it; it is not reported as a failed refund.

Create and cancel safely

Use Create a refund for refund integrations.

Cancellation is narrow by design. Only a pending refund without a processing attempt or processing timestamp can be canceled. After processing starts, use the final refund status and support workflow instead of trying to undo it.

Always use stable idempotency keys for create and cancel requests. If the network fails after submission, retry with the same key and the same body so Inttegro can return the original result instead of creating a second logical refund.

Where MCP helps

MCP can help with the full assisted refund workflow:

look up the paid order and current refundable options;
create an asynchronous line-item refund after confirming the exact amount for each line, any line-level reasons, and the required overall reason;
look up the refund to determine its current state; and
attempt cancellation only while the refund is still pending, after confirming its current amount, order, and reason.

For unattended integrations, use the Refunds API reference from your trusted backend. An MCP action still requires its own confirmation; a pending result is not proof that money has returned.

Implementation checklist

Before using refunds in production:

expose order line-item IDs in support tooling;
show the remaining refundable amount per line item;
require a reason before submission;
calculate refund amounts in integer minor units;
use idempotency keys;
store the returned rf_... refund ID;
poll lookup until terminal state when your workflow needs confirmation;
notify the customer only from an accepted or final state that matches your policy; and
reconcile successful refunds through balance transactions.

Refunds API reference - Exact refund operation contract.
Create a refund - Canonical refund creation endpoint.
Cancel a refund - Stop a refund before execution starts.
Lookup a refund - Refresh refund lifecycle state.
Orders - Understand the original sale being adjusted.
Balances - Understand aggregate balance effects.
Balance transactions - Understand refund-linked money movement.