Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.y.uno/llms.txt

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

​
Refunds

Yuno offers a complete suite of refund flows that cover every stage of the customer-money-back journey. There are three supported flows, each designed for a different operational need:
  • Referenced refunds — reverse a single Yuno-captured payment through the API. The standard customer-service reimbursement flow.
  • Batch refunds — process up to 1,000 refunds at once by uploading a CSV in the Yuno Dashboard. Used by operations teams for recall events, fraud sweeps, and bulk reimbursements.
  • Unreferenced refunds — push funds directly to a payment method through the API, without referencing an original Yuno payment. Used for refunding customers whose original charge lives outside Yuno (legacy billing system, external subscription engine) or for sending goodwill / promotional credits.

​
Refund flows Yuno supports

FlowChannelLinked to a Yuno payment?When to use
Referenced refundPOST /v1/payments/{id}/refunds APIYes — requires a payment id and transaction_idReverse a charge made through Yuno. Standard customer-service reimbursement flow.
Batch refundDashboard CSV uploadYes — each row references a Yuno payment_idProcess up to 1,000 refunds at once. Used by operations teams for recall events, fraud sweeps, or bulk reimbursements.
Unreferenced refundPOST /v1/unreferenced-refunds APINo — pushes funds directly to a payment methodRefund customers whose original charge was processed outside Yuno (e.g. legacy billing system, Zuora OPG, subscription correction). Also goodwill / promotional credits.

​
Referenced refund (single, via API)

A referenced refund reimburses a Yuno-captured payment. You call POST /v1/payments/{id}/refunds with the payment’s id, the transaction_id to refund, and an optional amount object. Leave amount empty for a full refund, or specify a value and currency for a partial refund. The refund is credited back to the same payment method that was originally charged. When a referenced refund succeeds, the parent payment transitions to status = REFUNDED / sub_status = REFUNDED, and a new transaction is appended with transaction.type = REFUND and transaction.status = SUCCEEDED. Webhooks fire as usual.
💡 Refund processing time Refunds are processed instantly in Sandbox. In Production, processing time varies depending on the payment method and provider — card refunds typically settle within 1–5 business days, while ACH and SEPA can take 3–10 business days.

​
Batch refund (bulk, via Dashboard)

The batch refund feature in the Yuno Dashboard lets your team process refunds for several transactions simultaneously, saving time and manual effort. Each row in the uploaded CSV references an existing Yuno payment. How to use it
  1. Navigate to All payments → Batch refunds → Upload.
  2. Download the sample template and populate it. Required columns:
    • Payment ID
    • Transaction ID
    • Amount to refund
    • Currency
    • Merchant reference
    • Reason — one of DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER
  3. Upload the CSV. Yuno validates each row and queues the refunds.
  4. Monitor progress in All payments → Batch refunds → Overview.
Limits: up to 1,000 payments per batch. For larger volumes, split into multiple batches or contact your account manager.

​
Unreferenced refund (standalone credit, via API)

An unreferenced refund — also called a Credit or standalone refund — pushes funds back to a payment method without referencing an original Yuno payment. This is essential when the charge being reimbursed lives outside Yuno, or when the merchant needs to send a promotional / goodwill credit. The rest of this page walks through how Unreferenced Refunds work end to end.

​
Unreferenced Refunds

Yuno Unreferenced Refunds is an API solution designed to issue refunds directly to a payment method without referencing an original payment transaction. In gateway terminology, this maps to the operation_type: "Credit" operation. It enables you to send funds to a card, bank account, mandate, or wallet that was not necessarily charged through Yuno — unifying 28+ payment providers behind a single API contract.

​
How Unreferenced Refunds work

An unreferenced refund moves through a small state machine that mirrors Yuno’s standard payment lifecycle.
  1. CREATED — Yuno persists the refund after validating the request and routing to a compatible provider.
  2. PENDING — the provider has accepted the refund and is awaiting async settlement (ACH clearing, SEPA settlement, etc paid-out).
  3. Terminal states:
    • SUCCEEDED — funds confirmed on the destination payment method (either sync-settled, e.g. Stripe; or async-settled via provider webhook).
    • FAILED — provider declined the refund, returned the funds, hit OFAC/sanctions, exceeded SLA, or any other unrecoverable error. Detail lives in provider.response_code and provider.response_message.
Webhook events fire on status transitions only:
EventFires when status enters
unreferenced_refund.createdCREATED
unreferenced_refund.succeededSUCCEEDED
unreferenced_refund.failedFAILED

​
Using Yuno Unreferenced Refunds

To issue an unreferenced refund, call the POST /v1/unreferenced-refunds endpoint with:
  • account_id, merchant_order_id, description, country, amount
  • A payment_method describing the destination (vaulted token, raw card, bank transfer, or wallet)
  • A customer_payer block with the recipient’s identity (required for ACH / SEPA / PayPal — to satisfy OFAC and AML screening)
  • Optionally provider_data.id to pin to a specific gateway
Example — refund a duplicate subscription charge to a vaulted Stripe card: 
{
  "account_id": "9f6e0a4c-1d2b-4e3f-8a9b-1c2d3e4f5a6b",
  "merchant_order_id": "REFUND-2026-05-14-001",
  "description": "Subscription correction — duplicate charge",
  "country": "US",
  "amount": { "value": 25.00, "currency": "USD" },
  "provider_data": { "id": "STRIPE" },
  "payment_method": {
    "vaulted_token": "vt_01HX2Y3ZP4Q5R6S7T8U9V0W1X2"
  },
  "customer_payer": {
    "id": "cus_01HX2K9PQR3S4T5U6V7W8X9Y0Z"
  }
}
You will receive a 201 Created response with an id prefixed urf_*, and a webhook will fire when the refund reaches its terminal state.

​
Supported destinations

DestinationYuno payment_method_typeRequired fields
Raw cardCARDpayment_method.detail.card.card_data.{number, holder_name, expiration_month, expiration_year, brand}
Vaulted cardVAULTED_TOKENpayment_method.vaulted_token
SEPA / IBANBANK_TRANSFERpayment_method.detail.bank_transfer.{bank_account, account_type: "IBAN", beneficiary_name}
ACHBANK_TRANSFERpayment_method.detail.bank_transfer.{bank_account, bank_id, account_type, beneficiary_name, beneficiary_document} + customer_payer.billing_address
PayPalWALLETpayment_method.detail.wallet.payment_token + customer_payer.email
GoCardless mandateBANK_TRANSFERpayment_method.detail.bank_transfer.{provider_token, account_type: "MANDATE", beneficiary_name}

​
Choosing the right refund flow

QuestionRecommended flow
Was the original payment captured through Yuno?Referenced refund
Do you need to reverse hundreds or thousands of Yuno payments at once?Batch refund (dashboard CSV)
Was the original charge made outside Yuno, or is there no original charge at all (goodwill credit, promotional credit, subscription correction from an external billing system)?Unreferenced refund