Create Unreferenced Refund - Yuno API Documentation

{
  "account_id": "9f6e0a4c-1d2b-4e3f-8a9b-1c2d3e4f5a6b",
  "merchant_order_id": "REFUND-2026-05-14-001",
  "merchant_reference": "credit-note-7891",
  "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",
    "merchant_customer_id": "cust_4521",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "metadata": [
    { "key": "billing_cycle_id", "value": "bc_2026_05" },
    { "key": "support_ticket", "value": "ZD-99214" }
  ],
  "callback_url": "https://merchant.example.com/yuno/webhooks/refunds"
}

{
  "id": "urf_01HX31R6QK7E2F4G5H6J7K8M9N",
  "account_id": "9f6e0a4c-1d2b-4e3f-8a9b-1c2d3e4f5a6b",
  "merchant_order_id": "REFUND-2026-05-14-001",
  "merchant_reference": "credit-note-7891",
  "country": "US",
  "description": "Subscription correction — duplicate charge",
  "amount": {
    "value": 25.00,
    "currency": "USD"
  },
  "status": "CREATED",
  "sub_status": "CREATED",
  "payment_method": {
    "vaulted_token": "vt_01HX2Y3ZP4Q5R6S7T8U9V0W1X2",
    "detail": {
      "card": {
        "card_data": {
          "brand": "VISA",
          "last_four": "1111",
          "type": "CREDIT"
        }
      }
    }
  },
  "customer_payer": {
    "id": "cus_01HX2K9PQR3S4T5U6V7W8X9Y0Z",
    "merchant_customer_id": "cust_4521",
    "first_name": "John",
    "last_name": "Doe"
  },
  "provider": {
    "name": "STRIPE",
    "type": "PSP",
    "connection_id": "conn_01HX0J8FZQK7M3N4P5R6S7T8U9",
    "reference": "re_3OqQz92eZvKYlo2C0g6XK1Yj",
    "category": "APPROVED",
    "raw_response_code": "succeeded"
  },
  "metadata": [
    { "key": "billing_cycle_id", "value": "bc_2026_05" }
  ],
  "created_at": "2026-05-14T11:47:13.482Z",
  "updated_at": "2026-05-14T11:47:13.482Z"
}

POST

unreferenced-refunds

{
  "account_id": "9f6e0a4c-1d2b-4e3f-8a9b-1c2d3e4f5a6b",
  "merchant_order_id": "REFUND-2026-05-14-001",
  "merchant_reference": "credit-note-7891",
  "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",
    "merchant_customer_id": "cust_4521",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "metadata": [
    { "key": "billing_cycle_id", "value": "bc_2026_05" },
    { "key": "support_ticket", "value": "ZD-99214" }
  ],
  "callback_url": "https://merchant.example.com/yuno/webhooks/refunds"
}

{
  "id": "urf_01HX31R6QK7E2F4G5H6J7K8M9N",
  "account_id": "9f6e0a4c-1d2b-4e3f-8a9b-1c2d3e4f5a6b",
  "merchant_order_id": "REFUND-2026-05-14-001",
  "merchant_reference": "credit-note-7891",
  "country": "US",
  "description": "Subscription correction — duplicate charge",
  "amount": {
    "value": 25.00,
    "currency": "USD"
  },
  "status": "CREATED",
  "sub_status": "CREATED",
  "payment_method": {
    "vaulted_token": "vt_01HX2Y3ZP4Q5R6S7T8U9V0W1X2",
    "detail": {
      "card": {
        "card_data": {
          "brand": "VISA",
          "last_four": "1111",
          "type": "CREDIT"
        }
      }
    }
  },
  "customer_payer": {
    "id": "cus_01HX2K9PQR3S4T5U6V7W8X9Y0Z",
    "merchant_customer_id": "cust_4521",
    "first_name": "John",
    "last_name": "Doe"
  },
  "provider": {
    "name": "STRIPE",
    "type": "PSP",
    "connection_id": "conn_01HX0J8FZQK7M3N4P5R6S7T8U9",
    "reference": "re_3OqQz92eZvKYlo2C0g6XK1Yj",
    "category": "APPROVED",
    "raw_response_code": "succeeded"
  },
  "metadata": [
    { "key": "billing_cycle_id", "value": "bc_2026_05" }
  ],
  "created_at": "2026-05-14T11:47:13.482Z",
  "updated_at": "2026-05-14T11:47:13.482Z"
}

This request allows you to create an unreferenced refund — a credit pushed directly to a payment method without referencing an original payment transaction.

When to use Unreferenced RefundsUse this endpoint when the original charge was processed outside Yuno (legacy billing system, external subscription engine) or when you need to send a goodwill / promotional credit. For reversing a Yuno-captured payment, use Refund Payment endpoint with transaction instead.

public-api-key

string

required

The unique public API key for your account. You find this on the Yuno dashboard.

private-secret-key

string

required

The unique private secret key for your account. You find this on the Yuno dashboard.

X-Idempotency-Key

string

required

Unique UUID v4 identifier used to safely retry the request. Retries with the same key return the originally created refund.

account_id

string

required

The unique identifier of the account. You find this information on the Yuno dashboard (UUID, 36 chars).

merchant_order_id

string

required

The unique identifier of your internal credit/refund (MAX 255; MIN 3).

merchant_reference

string

Optional correlation ID. Defaults to merchant_order_id (MAX 255; MIN 3).

description

string

required

The description of the refund. Appears on dashboards and statements (MAX 255; MIN 3).

country

string

required

Country where the refund must be processed (MAX 2; MIN 2; ISO 3166-1). Drives provider routing.

amount

object

required

Specifies the refund amount object, with the value and currency.

Show properties

value

number

required

The refund amount (multiple of 0.0001). Must be greater than 0.

currency

string

required

The currency used for the refund (MAX 3; MIN 3; ISO 4217).

provider_data

object

Pins the refund to a specific gateway, bypassing routing rules. Useful when the destination provider is dictated by where the original payment was processed.

Show properties

string

required

Provider identifier. Allowed values: ADYEN, STRIPE, NUVEI, BRAINTREE, GOCARDLESS, ORBITAL, WORLDPAY, VANTIV, CARDCONNECT, FISERV_COMMERCEHUB, MONERIS, NMI, FIRSTDATA, WINDCAVE, SAFERPAY, JPM, PAYPAL_EXPRESS_CHECKOUT, MASTERCARD, CITI, WELLSFARGO, SAGEPAY, FATZEBRA, HELIX, 24HF, MERCHANTE_SOLUTIONS, ANB, AUTHORIZE_NET, SPECTRUM.

payment_method

object

required

Specifies the destination of the refund — vaulted token, raw card, bank transfer, or wallet. Exactly one of vaulted_token or detail.<card|wallet|bank_transfer> must be set.

Show properties

vaulted_token

string

Yuno-side vault reference for a previously stored payment method. Preferred path — keeps PCI scope minimal.

detail

object

Inline payment-method details. Use when you do not have a vaulted token. Exactly one sub-object must be populated: card, wallet, or bank_transfer.

Show properties

card

object

Use when you need to push the refund to a raw card (Yuno will encrypt the PAN at the edge).

Show properties

card_data

object

required

Show properties

number

string

required

The card number (PAN). Encrypted at the edge.

holder_name

string

required

Name as it appears on the card.

expiration_month

integer

required

Card expiration month (1–12).

expiration_year

integer

required

Card expiration year.

security_code

string

CVV / CVC. Most acquirers do not require it for credits.

brand

string

required

One of: VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, UATP, ELO, HIPERCARD, MAESTRO.

type

string

Card type: CREDIT, DEBIT, PREPAID.

soft_descriptor

string

The text shown on the cardholder’s statement (MAX 255).

stored_credentials

object

Stored-credential metadata for recurring-credit flows. Reuses the same shape as /v1/payments.

network_token

object

Network-token metadata (Visa Token Service / Mastercard MDES) when refunding to a tokenized network credential.

bank_transfer

object

Use for SEPA / IBAN, ACH, and GoCardless mandate refunds.

Show properties

provider_token

string

Provider-side reference to a pre-existing bank object. Required for GoCardless — carries the mandate_id (e.g. MD000ABCDEF123). When supplied, bank_account and bank_id are optional.

bank_account

string

IBAN (SEPA) or account number (ACH / local). Required when no provider_token is supplied.

bank_id

string

BIC / SWIFT (non-SEPA EU corridors) or ABA-9 routing number (ACH). Required for ACH.

account_type

string

required

One of: IBAN, CHECKING, SAVINGS, CLABE, CCI, LOCAL, MANDATE (new — used for GoCardless).

beneficiary_name

string

required

Recipient name on the account.

beneficiary_type

string

INDIVIDUAL or ENTITY.

beneficiary_document

object

Recipient’s tax / national ID. Required for ACH (SSN / EIN) and for LATAM SEPA-equivalent corridors.

Show properties

document_type

string

e.g., SSN, EIN

document_number

string

e.g., 123-45-6789

wallet

object

Use for PayPal Express Checkout refunds.

Show properties

payment_token

string

required

PayPal payerID of the recipient.

customer_payer

object

Specifies the recipient of the refund. Required for ACH, SEPA, and PayPal destinations to satisfy OFAC and AML screening.

Show properties

string

Existing Yuno customer UUID. Alternative to inlining the customer PII.

merchant_customer_id

string

Your external customer identifier.

first_name

string

Recipient’s first name.

last_name

string

Recipient’s last name.

string

Recipient’s email address.

phone

object

{ country_code, number, extension }.

document

object

National identification document. { document_type, document_number }.

date_of_birth

string

YYYY-MM-DD.

nationality

string

ISO 3166-1 alpha-2 country code.

ip_address

string

Recipient’s IP address (when known).

billing_address

object

Postal address.

shipping_address

object

Same shape as billing_address.

type

string

INDIVIDUAL or ENTITY.

business_name

string

Required when type = ENTITY.

metadata

array of objects

Optional list of key/value pairs for your own reference. Echoed back in the response and webhook payload.

Show properties

key

string

Free-form label.

value

string

Free-form value. Max 512 characters.

callback_url

string

HTTPS URL where Yuno will deliver webhook events for this refund. Falls back to your account-level webhook if omitted.

fraud_screening

object

When stand_alone: true, Yuno runs an ML fraud check before submitting to the provider. Recommended for raw-card refunds.

Show properties

stand_alone

boolean

When true, performs a fraud check before provider submission.

{
  "account_id": "9f6e0a4c-1d2b-4e3f-8a9b-1c2d3e4f5a6b",
  "merchant_order_id": "REFUND-2026-05-14-001",
  "merchant_reference": "credit-note-7891",
  "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",
    "merchant_customer_id": "cust_4521",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "metadata": [
    { "key": "billing_cycle_id", "value": "bc_2026_05" },
    { "key": "support_ticket", "value": "ZD-99214" }
  ],
  "callback_url": "https://merchant.example.com/yuno/webhooks/refunds"
}

{
  "id": "urf_01HX31R6QK7E2F4G5H6J7K8M9N",
  "account_id": "9f6e0a4c-1d2b-4e3f-8a9b-1c2d3e4f5a6b",
  "merchant_order_id": "REFUND-2026-05-14-001",
  "merchant_reference": "credit-note-7891",
  "country": "US",
  "description": "Subscription correction — duplicate charge",
  "amount": {
    "value": 25.00,
    "currency": "USD"
  },
  "status": "CREATED",
  "sub_status": "CREATED",
  "payment_method": {
    "vaulted_token": "vt_01HX2Y3ZP4Q5R6S7T8U9V0W1X2",
    "detail": {
      "card": {
        "card_data": {
          "brand": "VISA",
          "last_four": "1111",
          "type": "CREDIT"
        }
      }
    }
  },
  "customer_payer": {
    "id": "cus_01HX2K9PQR3S4T5U6V7W8X9Y0Z",
    "merchant_customer_id": "cust_4521",
    "first_name": "John",
    "last_name": "Doe"
  },
  "provider": {
    "name": "STRIPE",
    "type": "PSP",
    "connection_id": "conn_01HX0J8FZQK7M3N4P5R6S7T8U9",
    "reference": "re_3OqQz92eZvKYlo2C0g6XK1Yj",
    "category": "APPROVED",
    "raw_response_code": "succeeded"
  },
  "metadata": [
    { "key": "billing_cycle_id", "value": "bc_2026_05" }
  ],
  "created_at": "2026-05-14T11:47:13.482Z",
  "updated_at": "2026-05-14T11:47:13.482Z"
}

Unreferenced Refund Status Retrieve Unreferenced Refund by ID