Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yuvexpay.com/llms.txt

Use this file to discover all available pages before exploring further.

A refund returns funds from your YuvexPay balance back to the payer’s source of funds. 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.
ConditionEffect
Payment is PAIDRefundable.
Payment is PARTIAL_REFUNDRefundable up to the remaining amount.
Payment is EXPIRED, CANCELLED, REFUNDED, CHARGEBACK, or MED_FROZENNot refundable.
Payment is anticipatedRefunds are blocked until the anticipation is settled (REFUND_BLOCKED_BY_ANTICIPATION).
Payment was processed via a non-refundable providerREFUND_NOT_SUPPORTED.
Insufficient available balance to cover the refundINSUFFICIENT_BALANCE_FOR_REFUND.
A refund issued for a non-eligible payment returns a 400 with one of the codes above.

​
Issue a refund

Currently only full refunds are supported. Send no amount to refund the full remaining balance, or send the exact remaining refundable amount. 
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"
  }
}

​
Refund lifecycle

A refund can be in one of these statuses:
StatusMeaning
PROCESSINGThe refund was accepted and is being executed at the underlying network.
COMPLETEDThe refund cleared and the payment moved to REFUNDED (or PARTIAL_REFUND if there is remaining balance).
FAILEDThe 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

CodeMeaning
INVALID_STATUSThe payment is not in a refundable status.
PARTIAL_REFUND_NOT_SUPPORTEDOnly full refunds are supported. Either omit amount or send the full remaining refundable amount.
ALREADY_REFUNDEDA previous refund has already returned the full balance.
REFUND_IN_PROGRESSA refund is currently in flight against this payment. Retry once it settles.
REFUND_NOT_SUPPORTEDThis payment was processed via a method or route that doesn’t support refunds via API.
INSUFFICIENT_BALANCE_FOR_REFUNDYour available balance is too low to cover the refund.
PSP_REFUND_FAILEDThe underlying network rejected the refund. The funds remain on your balance and you can retry.
REFUND_BLOCKED_BY_ANTICIPATIONThe payment was anticipated; refunds are blocked until anticipation settles.