Refund a fiat order

POST /api/v1/partner/fiat-orders/{orderKey}/refunds

Required scope: refunds:write. Also requires the refunds capability on the relationship that owns the order.

Sends money back to the buyer who paid the order — fully, or partially, as many times as the remaining balance allows. The identifier is order_key, the short integer returned on the order, and there is no customer id in the path: a partner that stored nothing but the key can refund.

Refunds are issued against the processor that took the payment, on the merchant account that holds the order. You never name a destination — it is the order’s own original payer, which is why this call needs no signed second factor, unlike a withdrawal or a payout-wallet change.

Request

curl -X POST https://www.niftipay.com/api/v1/partner/fiat-orders/1001/refunds \
  -H "Authorization: Bearer <partner_api_key>" \
  -H "Idempotency-Key: <uuid>" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 400, "description": "Item returned" }'

An order_lines array may not be empty — send null or omit the field when you have no lines to name.

Idempotency-Key is required: money moves on this call, and a caller that retried after a socket timeout cannot know whether the first attempt landed. On a retry, reuse the same key; a fresh key is a second refund.

Response 201

{
  "request_id": "req-1",
  "api_version": "2026-08-01",
  "data": {
    "order_key": "1001",
    "currency": "EUR",
    "refund": {
      "amount_cents": 400,
      "status": "partially_refunded"
    },
    "service_fee_payer": "customer",
    "max_refundable_cents": 1025,
    "refunded_cents": 400,
    "remaining_refundable_cents": 625
  }
}

The order’s own status becomes refunded once remaining_refundable_cents reaches 0; a partial refund leaves it unchanged.

How much can be refunded

The ceiling depends on who paid the service fee, which is on the order itself:

refunded_cents is read from the processor on every call, not from our own records, so a refund issued outside this API still counts against the ceiling.

Preconditions

• The order must be a real order — a payment link cannot be refunded (409 not_refundable).
• Its status must be paid or completed (409 order_not_paid).
• It must have reached the processor at all; an order with no processor-side payment answers 409 not_refundable.

Some processors refund full value only

One processor exposes no partial-refund API. On such an order, an amount_cents that is not exactly remaining_refundable_cents is refused with 409 refund_full_value_only, and details[0].remaining_refundable_cents carries the one amount that would be accepted:

{
  "error": {
    "code": "refund_full_value_only",
    "message": "This provider only supports a full refund of the remaining balance. See details for the amount that would be accepted.",
    "request_id": "req-1",
    "details": [
      {
        "remaining_refundable_cents": 1025
      }
    ]
  }
}

Retry with that figure. Nothing is substituted silently — a machine caller sees only the number it sent, so refunding a different amount without saying so would be worse than a refusal.

Every miss is the same 404

Four different situations answer identically: the order key does not exist, it belongs to another partner on the same merchant, it belongs to a merchant you never onboarded, or the refunds capability is not granted on the relationship that owns it.

{
  "error": {
    "code": "resource_not_found",
    "message": "No partner-visible fiat order exists for this order key.",
    "request_id": "req-1"
  }
}

Note the last case: unlike every other rail, a missing grant here is a 404, not 403 capability_not_enabled. order_key is a small consecutive integer from a shared sequence, so anything that told the cases apart would not require guessing ids — you could count. Read capabilities to find out whether refunds is granted; do not infer it from this endpoint.

A capability that is granted but not currently usable is a separate 409 capability_unavailable — reaching that check already proves the order is yours, so the distinction reveals nothing.

Errors

“Key released” means the Idempotency-Key can be reused after fixing the request: it is released only for refusals decided before anything was sent to the processor. Once the processor has been contacted the key is consumed, because the outcome of the first attempt is no longer certain — replay the same key to read what happened rather than sending a second refund. Refusals marked n/a are decided before the key is recorded at all.

The event

A successful refund emits two webhook events: refund.completed, keyed on the refund, and payment.refunded, the order’s status twin. Both carry the order’s identifiers and status, not the refunded amount — use this call’s own response, re-read the order for refunded_cents, or call List an order’s refunds for the per-refund breakdown. See Webhooks.