Skip to main content
POST
Create Refund

Authorizations

Authorization
string
header
required

Service (M2M) access token issued by POST /auth/token using the client_credentials grant. Required scopes, where known, are listed on each operation below.

Headers

Idempotency-Key
string

Deduplicates retried requests with the same key and parameters instead of creating a second resource (roughly a 24-hour replay window). Recommended: an opaque, randomly-generated value such as a UUID. A refund is created before the credit note that records it: if the call fails after a refund went through, retry with the same key — the payment provider replays that refund instead of creating a second one, and the retry links it on the credit note. That promise covers a failed credit note; retry a failed call within the 24-hour window, because after it the payment provider treats the retry as a new request and can refund again. On an invoice paid in more than one payment, if one payment's refund is rejected after another's went through, the retry replays the same rejection and the refund that went through stays unlinked: it is not counted against the refundable amount, so contact OpenLoop before retrying under a new key. A same-key retry of a call that already succeeded returns the original refund without refunding again — at any time with a key; the same key with a different amount, balance_amount or reason returns 400. Without a key the scope is derived from amount, balance_amount and reason, and an identical keyless request is treated as a retry of the first for 24 hours after it succeeded; after that it is a new refund — send an Idempotency-Key to issue two equal refunds sooner.

Path Parameters

provider_invoice_id
string
required

Provider invoice id (e.g. test_invoice_id).

Body

application/json
amount
integer
required

Total refund in cents, card and balance together. Positive integer. Its card part (amount − balance_amount) is no greater than the invoice's card-refundable amount: what its paid card payments paid, minus the refunds already linked to credit notes on the invoice. A payment recorded outside the payment provider is not refundable to card.

reason
string
required

One of duplicate, fraudulent, order_change, product_unsatisfactory.

balance_amount
integer

Part of amount, in cents, returned to the billing customer's balance instead of the card. Integer from 0 to amount; absent means 0 (card only). No greater than the credit that was applied to the invoice from the balance, minus what earlier credit notes already returned to the balance — so only the credit-paid part goes back to the balance.

description
string

Free-text note; sent to the provider as the credit note memo.

Response

Success.

data
object
required