Refunds

A refund returns funds to the payer’s source of funds. The money comes out of your YuvexPay balance — or, when the payment carries splits, out of every party’s balance in proportion to what it received. Refunds are issued via POST /v1/payments/{paymentId}/refund.

What can be refunded

The eligibility rules are enforced server-side and surfaced in the payment detail response under refundEligibility.

Condition	Effect
Payment is `PAID`	Refundable.
Payment is `PARTIAL_REFUND`	Refundable up to the remaining amount.
Payment is `EXPIRED`, `CANCELLED`, `REFUNDED`, `CHARGEBACK`, or `MED_FROZEN`	Not refundable.
Payment is anticipated	Refunds are blocked until the anticipation is settled (`REFUND_BLOCKED_BY_ANTICIPATION`).
Payment was processed via a non-refundable provider	`REFUND_NOT_SUPPORTED`.
Insufficient available balance to cover the refund	`INSUFFICIENT_BALANCE_FOR_REFUND`. On a split payment only the originating company’s share is checked.

A refund issued for a non-eligible payment returns a 400 with one of the codes above.

Issue a refund

Send no amount to refund the full remaining balance, or an amount between 0.01 and the remaining refundable amount for a partial refund. Partial refunds are conditional: they require a payment that has already settled and a routing provider that supports them. When either condition is missing the request fails with PARTIAL_REFUND_NOT_SUPPORTED and the payment stays fully refundable. A full refund is always available on a refundable payment.

curl -X POST https://api.yuvexpay.com/v1/payments/5d0f8b6e-3a02-4f5b-9e1c-7c6a4a1b8c9d/refund \
  -H "Authorization: Bearer $YUVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: refund-order-1234" \
  -d '{
    "reason": "Customer requested cancellation"
  }'

The response contains the refund record:

{
  "refund": {
    "id": "fa1c0a85-7c29-4e3a-9e07-5b1a7b6d1234",
    "txId": "REF_3f2a8b9c4e6d1f5a7b3c8d2e9f4a6b1c",
    "amount": 49.90,
    "reason": "Customer requested cancellation",
    "status": "PROCESSING",
    "processedAt": null,
    "createdAt": "2026-05-03T14:21:08.443Z"
  }
}

Refunds on split payments

When the payment carries splits, the refund is apportioned: every party is debited in proportion to what it received, the originating company included. A partial refund uses the same proportions as a full one. A recipient that has already withdrawn its share goes negative. The shortfall is never moved onto the originating company, and INSUFFICIENT_BALANCE_FOR_REFUND is evaluated against the originating company’s share only — a recipient never blocks a refund. When a debit lands on a share that is still in the recipient’s rolling reserve, that payment’s reserve hold is released first and the debit is written against it. A PIX MED freezes each party’s proportional share the same way.

Refund lifecycle

A refund can be in one of these statuses:

Status	Meaning
`PROCESSING`	The refund was accepted and is being executed at the underlying network.
`COMPLETED`	The refund cleared and the payment moved to `REFUNDED` (or `PARTIAL_REFUND` if there is remaining balance).
`FAILED`	The refund could not be executed. The funds are returned to your balance and you can retry.

Listen for PAYMENT_REFUNDED and PAYMENT_REFUND_FAILED webhook events to react to status changes.

Idempotency

Sending POST /v1/payments/{paymentId}/refund requires an X-Idempotency-Key header. Reusing the same key with the same body returns the original response. Reusing the key with a different body returns 409 IDEMPOTENCY_PAYLOAD_MISMATCH. While a refund is being processed for a given payment, additional refund requests fail with 409 REFUND_IN_PROGRESS until the current refund settles.

Listing refunds for a payment

GET /v1/payments/{paymentId}/refunds

Returns every refund that has been attempted or completed against a payment, in chronological order. Useful for reconciling refund flows or showing a history to your operations team.

Common error codes

Code	Meaning
`INVALID_STATUS`	The payment is not in a refundable status.
`PARTIAL_REFUND_NOT_SUPPORTED`	The payment has not settled yet, or its routing provider cannot execute partial refunds. Either omit `amount` or send the full remaining refundable amount.
`ALREADY_REFUNDED`	A previous refund has already returned the full balance.
`REFUND_IN_PROGRESS`	A refund is currently in flight against this payment. Retry once it settles.
`REFUND_NOT_SUPPORTED`	This payment was processed via a method or route that doesn’t support refunds via API.
`INSUFFICIENT_BALANCE_FOR_REFUND`	Your available balance is too low to cover the refund. On a split payment, the check covers your own proportional share only.
`PSP_REFUND_FAILED`	The underlying network rejected the refund. The funds remain on your balance and you can retry.
`REFUND_BLOCKED_BY_ANTICIPATION`	The payment was anticipated; refunds are blocked until anticipation settles.

Getting started

Core concepts

Products

What can be refunded

Issue a refund

Refunds on split payments

Refund lifecycle

Idempotency

Listing refunds for a payment

Common error codes

​What can be refunded

​Issue a refund

​Refunds on split payments

​Refund lifecycle

​Idempotency

​Listing refunds for a payment

​Common error codes

What can be refunded

Issue a refund

Refunds on split payments

Refund lifecycle

Idempotency

Listing refunds for a payment

Common error codes