Refunds

Process full and partial refunds through the Yuno API

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

Node.js

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:

Node.js

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

Status	Description
SUCCEEDED	Refund processed and funds returned
PENDING	Refund submitted, awaiting provider confirmation
FAILED	Refund 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 Method	Typical Timeline
Credit Card	5-10 business days
Debit Card	3-5 business days
PIX	Instant to 1 business day
Bank Transfer	3-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