Refund a payment

Refund a card payment, whole or in part.

POSTCopy URL: https://api.avvio.xyz/business/api/v1/checkout/organizations/{orgId}/payments/{paymentId}/refund

POST/checkout/organizations/{orgId}/payments/{paymentId}/refund

Open in explorer

curl

IDEMPOTENCY_KEY=$(uuidgen)  # new key per call; reuse it only to retry this exact request
curl -s -X POST "$AVVIO_BASE_URL/checkout/organizations/$AVVIO_ORG_ID/payments/$paymentId/refund" \
  -H "x-api-key: $AVVIO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "content-type: application/json" \
  -d '{
        "amount": "12.50",
        "reason": "requested_by_customer",
        "note": "Session moved to next week"
      }'

Node

const paymentId = '<paymentId>';
const idempotencyKey = crypto.randomUUID(); // new key per call; reuse it only to retry this exact request

const res = await fetch(`${process.env.AVVIO_BASE_URL}/checkout/organizations/${process.env.AVVIO_ORG_ID}/payments/${paymentId}/refund`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
    'Idempotency-Key': idempotencyKey,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    "amount": "12.50",
    "reason": "requested_by_customer",
    "note": "Session moved to next week"
  }),
});
console.log(res.status, await res.json());

Python

import os
import uuid
import requests

paymentId = "<paymentId>"
idempotency_key = str(uuid.uuid4())  # new key per call; reuse it only to retry this exact request

res = requests.post(
    f"{os.environ['AVVIO_BASE_URL']}/checkout/organizations/{os.environ['AVVIO_ORG_ID']}/payments/{paymentId}/refund",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
        "Idempotency-Key": idempotency_key,
    },
    json={
        "amount": "12.50",
        "reason": "requested_by_customer",
        "note": "Session moved to next week"
    },
)
print(res.status_code, res.json())

Try it

200OKResponse status200 OK400 Bad Request401 Unauthorized403 Forbidden404 Not Found409 Conflict429 Too Many Requests500 Internal Server Error

{
  "id": "cmf9x1b2c0003q8b7h6j8k0lm",
  "kind": "card",
  "acceptor": "sandbox",
  "externalId": "pay_01J8",
  "amountBase": "15000",
  "currency": "USD",
  "decimals": 2,
  "feeBase": "435",
  "netBase": "14565",
  "applicationFeeBase": "150",
  "refundedBase": null,
  "refunds": [],
  "disputeSubstatus": null,
  "status": "paid",
  "failureCode": null,
  "reviewReason": null,
  "clientReferenceId": "order_1042",
  "paidAt": "2026-09-12T10:00:04.000Z",
  "reversedAt": null,
  "settledAt": null,
  "createdAt": "2026-09-12T09:59:58.000Z"
}

Path parameters

• orgIdstringRequired

  The opaque organization id issued to you, normally CUID-shaped (for example cmsx…). It is not an org_-prefixed alias. Pass it unchanged in every organization-scoped path.

• paymentIdstringRequired

  The payment's id, or the acquirer's externalId.

Headers

• Idempotency-KeystringRequired

  A unique value per logical operation, 1-255 chars of A-Z a-z 0-9 _ . : -.

  More

  Reuse it to retry. Same key with the same body replays the stored response; same key with a different body is a 409, because answering with the first call's result would hand you a receipt for a payout you did not request. A 4xx releases the key, so you can fix the body and reuse it.

  Reuse it; do not generate one per attempt. A key minted per attempt defeats replay entirely: every retry looks like a new request, so every retry pays. We also watch for an identical body arriving under a different key within 15 minutes and refuse it with DUPLICATE_REQUEST_DETECTED.

  Records are kept for 7 days. That is a retention window only: there is no path where an expired key is re-executed.

• X-Allow-DuplicatestringOptional

  Set to true to send a request that is byte-identical to one you sent within the last 15 minutes under a different key. true is the only accepted value. It switches off the guard that catches a retry arriving under a fresh key, so send it only when you mean to pay twice.

Body

This endpoint expects a JSON object, or no body.

• amountstringOptional

  Decimal string in the payment's currency, at most as many decimal places as the currency has. Omit for everything remaining.

• reasonstringOptional

  The four refund reasons most card APIs use.

  Allowed values:requested_by_customerduplicatefraudulentother
• notestringOptional

  For your own team. Never shown to the buyer; echoed on the event.

Behavior

Moves money out of your balance and back to the buyer's card. Omit amount to refund everything still refundable; pass a decimal string in the payment's currency to refund part of it. paymentId is the payment's id from GET /links/{linkId}/payments (the acquirer's externalId is accepted too).

The key needs the refunds scope. It is a consent an owner or admin grants when the key is issued (scopes: ["write", "refunds"]); a key without it, including one issued before scopes existed, gets 403 INSUFFICIENT_SCOPE and nothing moves.

Idempotency-Key is required, and the acquirer's refund endpoint has no idempotency of its own, so the key is what makes a retry safe: reuse it. A byte-identical refund of the same payment under a different key within fifteen minutes is refused with DUPLICATE_REQUEST_DETECTED; a genuine second refund of the same amount sends X-Allow-Duplicate: true. One refund is in flight per payment at a time: a second one while the first is still being confirmed is 409 REFUND_IN_PROGRESS; read the payment and try again once refundedBase has moved.

When the outcome is unknown (the card processor did not answer definitively) the answer is 500 PAYOUT_OUTCOME_UNKNOWN. The refund may have gone through. Do not resend it, and never under a new Idempotency-Key: read the payment first. refundedBase moves, and checkout_payment.refunded or .partially_refunded follows, if it did. A replay of the same key answers 409 PAYOUT_OUTCOME_UNKNOWN until we resolve it. (The shared message speaks of a payout and GET /orders; for a refund, read the payment instead.)

A full refund publishes checkout_payment.refunded; a partial one publishes checkout_payment.partially_refunded (opt-in, like the rest of the family). Both carry the refund just made in refund. Every payment read lists its refunds under refunds.

Responses

200The payment after the refund, with the refund that was just made.

Body · RefundCheckoutPaymentResponse

• idstringRequired
• kindstringRequired

  How a buyer may pay. card is the hosted card page (card, wallets and PayPal in one).

  Allowed values:cardbankcryptocashapp
• acceptorstringOptional

  Which side recorded it: sandbox for a simulated payment, manual for one you recorded in the dashboard. A live card payment carries an internal label for the card processor, which can change without notice. Do not branch on it.

• externalIdstringOptional

  The acceptor's id for it. Opaque.

• amountBasestringRequired

  Gross, base units.

• currencystringRequired
• decimalsintegerRequired
• feeBasestringRequired

  Processing fee, base units. "0" when none was stated.

• netBasestring | nullOptional

  What reached your balance, when the acceptor stated it.

• applicationFeeBasestringOptional

  Our fee, base units.

• refundedBasestring | nullOptional

  Cumulative refunded, or null when nothing has been.

• refundsarray of objectRequired

  Every refund on this payment, oldest first, with who asked for it and why. Empty when none.

  Show 11 properties

  • idstringRequired
  • paymentIdstringRequired
  • amountBasestringRequired

    This refund, base units.

  • currencystringRequired
  • decimalsintegerRequired
  • reasonstring | nullRequired

    The four refund reasons most card APIs use.

    Allowed values:requested_by_customerduplicatefraudulentother
  • notestring | nullRequired
  • sourcestringRequired
    Allowed values:dashboardapiacquirer
  • statusstringRequired
    Allowed values:pendingsucceeded
  • actorstring | nullRequired

    A teammate's name, or the API key's name. Null for a refund made at the acquirer.

  • createdAtstring<date-time>Required
• disputeSubstatusstring | nullOptional

  Set while a dispute is open. No event fires until it resolves.

• statusstringRequired

  paid is not final: refunded and reversed (a chargeback) can follow, weeks later. pending on a bank payment that has settled means it is held (short of the total, or in the wrong currency) and reviewReason says why; it moves when someone accepts it in the dashboard.

  Allowed values:pendingprocessingpaidfailed

  Show 2 more values

  reversedrefunded
• failureCodestring | nullOptional
• reviewReasonstring | nullOptional

  Why a settled bank deposit is held in pending, in words. Null on anything not held.

• clientReferenceIdstring | nullOptional

  The ?client_reference_id= the buyer's visit carried (card rail only). The link-level one is on the link.

• paidAtstring<date-time> | nullOptional
• reversedAtstring<date-time> | nullOptional
• settledAtstring<date-time> | nullOptional

  Null in this version; the money is in your balance at the processor and we do not see it move from there.

• createdAtstring<date-time>Required
• refundobject | nullRequired

  One refund on a payment: the piece that moved, not the cumulative figure (that is refundedBase on the payment). source says who asked for it: dashboard, api, or acquirer for a refund made at the card processor's own tools that nobody initiated here. pending is a refund we asked for and have not yet seen come back; do not branch on values beyond pending and succeeded.

  Show 11 properties

  • idstringRequired
  • paymentIdstringRequired
  • amountBasestringRequired

    This refund, base units.

  • currencystringRequired
  • decimalsintegerRequired
  • reasonstring | nullRequired

    The four refund reasons most card APIs use.

    Allowed values:requested_by_customerduplicatefraudulentother
  • notestring | nullRequired
  • sourcestringRequired
    Allowed values:dashboardapiacquirer
  • statusstringRequired
    Allowed values:pendingsucceeded
  • actorstring | nullRequired

    A teammate's name, or the API key's name. Null for a refund made at the acquirer.

  • createdAtstring<date-time>Required

Errors

• 400

  VALIDATION_ERROR (a malformed amount, more decimal places than the currency has, an unknown reason, a note over 255 characters), REFUND_EXCEEDS_REMAINING (more than amountBase - refundedBase), REFUND_NOT_ALLOWED (the payment is not paid: already refunded in full, charged back, failed or still pending), REFUND_DISPUTED (a dispute is open; it decides where the money goes), PROVIDER_REJECTED (the card processor refused, with its words), or IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID. Nothing moved on any of them.

• 401

  The key was refused. Nothing ran.

  • UNAUTHORIZED: missing, invalid or revoked, or a key on a route that does not accept one.
  • KEY_EXPIRED: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated.
  • KEY_IP_NOT_ALLOWED: the key is pinned to source addresses and this request came from another.
• 403

  INSUFFICIENT_SCOPE (the key is read-only or lacks the refunds scope), FORBIDDEN (a key for a different organization), ACCOUNT_BLOCKED, or LIVE_KEY_ORG_NOT_APPROVED. Refunds are not held back by business verification.

• 404

  No such link or product in this organization, or the id belongs to another one.

• 409

  REFUND_IN_PROGRESS (another refund on this payment is still being confirmed at the acquirer; nothing further was sent), CONFLICT (in the sandbox, another refund landed a moment earlier; read the payment again), or an idempotency conflict: IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_KEY_REQUEST_IN_PROGRESS, DUPLICATE_REQUEST_DETECTED, or PAYOUT_OUTCOME_UNKNOWN on a replay of a key whose first call answered 500 (the refund may have gone through; read the payment, do not resend).

• 429

  Too many requests. The default ceiling is 100 requests per minute per API credential on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies.

  Obey Retry-After; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same Idempotency-Key.

• 500

  PAYOUT_OUTCOME_UNKNOWN: the call failed after the money may have moved, and we cannot yet say whether it did. Do not retry with a new Idempotency-Key; that is how a payment goes out twice. Look the outcome up first (the operation says where), or replay the same key, which answers 409 PAYOUT_OUTCOME_UNKNOWN until we resolve it. Send support the requestId.

  Every other 500 is INTERNAL: nothing was recorded under the key, and retrying with the same key is safe.

Error body · Error

• typestringRequired

  Stable machine-readable code.

• detailstringRequired

  What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.

  More

  This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.

• messagestringRequired

  The same text as detail, kept for integrations written before detail existed. Read detail.

• resolutionstringOptional

  What to do about it, when there is a specific answer. It is not on every error (it is absent on BAD_REQUEST, NOT_FOUND, PAYOUT_NOT_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.

• statusintegerRequired

  HTTP status, repeated in the body.

• statusCodeintegerRequired

  The same value as status, kept for integrations written before status existed. Read status.

• requestIdstringRequired

  Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.

• errorsarray of stringOptional

  Present on VALIDATION_ERROR; names each field that failed.

• originalIdempotencyKeystringOptional

  On DUPLICATE_REQUEST_DETECTED only. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.

• originalPayoutIdstringOptional

  On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.

• originalBatchIdstringOptional

  On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.

• originalRequestIdstringOptional

  On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.

• existingRecipientIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.

• existingMethodIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Checkout · Payments & refunds · operation refundCheckoutPayment

Try it: Refund a payment

POST https://api.avvio.xyz/business/api/v1/checkout/organizations/{orgId}/payments/{paymentId}/refund

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

orgId pathRequired

paymentId pathRequired

Idempotency-Key headerRequired

X-Allow-Duplicate headerOptional

Body JSON{ "amount": "12.50", "reason": "requested_by_customer", "note": "Session moved to next week" }

Send request