Skip to main content

​
Overview

Refunds return funds to the customer after a payment has been captured. Yuno supports both full refunds (entire amount) and partial refunds (a portion of the original amount).
Refunds can only be issued for payments with status SUCCEEDED. For authorized but uncaptured payments, use Cancel instead (no processing fees).

​
Create a Full Refund

const refund = await fetch(
  `https://api-sandbox.y.uno/v1/payments/${paymentId}/refund`,
  {
    method: 'POST',
    headers: {
      'public-api-key': process.env.YUNO_PUBLIC_KEY,
      'private-secret-key': process.env.YUNO_PRIVATE_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reason: 'Customer requested refund',
    }),
  }
);
const refundResult = await refund.json();

​
Create a Partial Refund

Specify the amount to refund: 
const partialRefund = await fetch(
  `https://api-sandbox.y.uno/v1/payments/${paymentId}/refund`,
  {
    method: 'POST',
    headers: {
      'public-api-key': process.env.YUNO_PUBLIC_KEY,
      'private-secret-key': process.env.YUNO_PRIVATE_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: { currency: 'USD', value: 25.00 },
      reason: 'Partial refund - item returned',
    }),
  }
);

​
Refund Response

{
  "id": "ref_xyz789",
  "payment_id": "pay_abc123",
  "status": "SUCCEEDED",
  "amount": { "currency": "USD", "value": 25.00 },
  "reason": "Partial refund - item returned",
  "created_at": "2026-02-28T14:30:00Z"
}

​
Refund Statuses

StatusDescription
SUCCEEDEDRefund processed and funds returned
PENDINGRefund submitted, awaiting provider confirmation
FAILEDRefund could not be processed

​
Multiple Partial Refunds

You can issue multiple partial refunds against a single payment, as long as the total refunded amount does not exceed the original captured amount: 
Original payment: $100.00
First partial refund:  -$30.00 (remaining: $70.00)
Second partial refund: -$20.00 (remaining: $50.00)
Attempting to refund more than the remaining capturable amount will result in an error. Track cumulative refunds on your side for accurate reconciliation.

​
Refund Timelines

Refund processing time depends on the payment method and provider:
Payment MethodTypical Timeline
Credit Card5-10 business days
Debit Card3-5 business days
PIXInstant to 1 business day
Bank Transfer3-7 business days

​
Best Practices

  • Always include a descriptive reason for audit and reconciliation purposes
  • Use webhooks to track refund status changes asynchronously
  • Implement idempotency keys to prevent duplicate refund requests
  • Prefer cancel/void over refund for same-day reversals to minimize fees
  • Keep a log mapping refund IDs to order/item-level details