A valid request URL is required to generate request examples{
"invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment": "live",
"charge_ref": "<string>",
"currency": "BRL",
"amount_minor": 123,
"refunded_minor": 123,
"remaining_minor": 123
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}What an invoice can still refund
Requires billing:read. What the gateway says about the payment behind one invoice: what it collected, what has already been handed back, and what remains.
This is a live read, every time
The invoice mirror stores no refunded amount, and that is deliberate rather than a gap: the mirror is keyed on the invoice and a refund lives on the payment, so a column here would be a partial copy of an object this system does not track — with no way to tell a stale zero from a real one.
So the numbers come from the gateway on every call. They include refunds issued in the gateway’s own dashboard, which is exactly the case the arithmetic you might do instead would miss.
Money is in the payment’s currency and minor units, which is normally the invoice’s own. Where the two differ, the payment is the one that counts — a refund is denominated in what was actually taken.
An invoice the gateway has no payment for answers 409 rather than a zero: nothing to refund and we could not find the payment are different answers, and only one of them should stop somebody looking.
A valid request URL is required to generate request examples{
"invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment": "live",
"charge_ref": "<string>",
"currency": "BRL",
"amount_minor": 123,
"refunded_minor": 123,
"remaining_minor": 123
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Autorizações
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Cabeçalhos
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Parâmetros de caminho
The invoice's id in this system — not the gateway's reference.
Parâmetros de consulta
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Resposta
The payment behind this invoice, as the gateway currently holds it.
The payment behind one invoice, read from the gateway at the moment of asking. Nothing here is stored: the mirror is keyed on the invoice and a refund lives on the payment, so every figure below comes back over the wire — which is what makes a refund issued in the gateway's own dashboard visible here.
live, test The gateway's own id for the payment. Opaque here, and the handle a bank statement or a chargeback is eventually reconciled against.
The payment's currency, which is normally the invoice's own.
"BRL"
What the payment collected, in minor units.
Everything handed back so far. Cumulative — not the last refund.
What may still be handed back. Floored at zero: a goodwill refund larger than the payment does not come back as a negative allowance.