Refunds

Refunds let you return money after a paid order, whether you are handling a return, cancellation, duplicate charge, damaged item, fraud report, or customer-support adjustment. They are order-rooted records: you refund specific paid order line items, and Inttegro sends money back through the order’s original payment method.

When to create a refund

Create a refund when money should move back to the customer after an order has already been paid. A refund is appropriate for:

Returned, damaged, missing, or not-as-described items
Full or partial order cancellation after payment
Duplicate or mistaken charges
Fraudulent transactions that need reversal
Customer-support adjustments tied to specific order line items

Do not create a refund for an unpaid order. Cancel or update the order instead, depending on where it is in the order lifecycle.

How refunds work

A refund starts from a paid order. Your server selects one or more order line items and the amount to return for each line. Inttegro validates that the order belongs to your application, the line items belong to that order, the currencies match, and the requested amounts do not exceed what remains refundable.

When the request is accepted, Inttegro creates a durable refund record with status: "pending". Processing runs asynchronously against the original payment method, then the refund moves through processing to either succeeded or failed.

Resource	What it represents
Order	The paid customer transaction being adjusted
Order line item	The specific part of the order being refunded
Refund	The durable request to return money for selected line items
Refund line item	The immutable allocation for one refunded order line item

note

Refunds do not accept a destination or payment ID. Inttegro resolves the execution path from the paid order so the money returns through the original payment method.

Full and partial refunds

A full refund returns the paid amount for every refundable line item on the order. A partial refund returns less than the paid amount or covers only some line items.

Line-item allocation matters because it keeps later reporting and support work clear. When a customer returns one item from a multi-item order, refund only that line. When shipping or fees were paid and should also be returned, include the corresponding refundable lines explicitly.

Each order line item can appear only once in a refund request, and each requested amount must be positive. If a line has already been partially refunded, the next refund can only cover the remaining refundable amount.

Reasons and support context

Every refund has an overall reason. Supported reasons include duplicate charges, fraud, damaged items, item-not-received cases, returned items, order cancellations, customer requests, and custom support reasons.

Use line-level reasons when different items in the same refund need different explanations. Line-level reasons do not inherit from the overall reason, so include them only when they add useful support or reconciliation context.

If the reason is custom, include reason_details at the same level. Keep details factual and concise; they can be useful later when a support agent, finance operator, or merchant reviews the refund.

Balance and eligibility

Refund creation depends on the order and the merchant balance being ready:

The order must be paid and belong to the authenticated application.
The order must have a customer and an original payment method available for refund execution.
The selected line items must belong to the order.
Each refund amount must use the same currency as its order line item.
The merchant balance must be initialized and sufficient for the requested total.

If the order is not refundable yet, wait for the payment or balance state to catch up before retrying. If the refundable amount changed concurrently, look up the current order and refund history before submitting a new request.

Operational flow

Look up the paid order and capture the order_id plus the order_line_item_id values you intend to refund.
Calculate the amount to refund per line item in the currency’s smallest unit.
Create the refund from your server with a stable idempotency key.
Store the returned rf_... refund ID.
Poll lookup, or refresh your internal support view, until the refund reaches succeeded or failed.
Use the final refund record for customer support, accounting, and reconciliation.

Use POST /refunds/create for new integrations. POST /orders/refund exists as a compatibility alias with the same request and response behavior; do not alternate between both paths for one logical refund.

Statuses

Status	Meaning
`pending`	The refund was durably accepted and is waiting for processing.
`processing`	Refund execution has started.
`succeeded`	Money was returned successfully.
`failed`	Processing ended without completing the refund.

Treat the refund record as the source of truth for the refund lifecycle. The order remains the source of truth for the original sale and fulfillment state.