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"
}

{
  "type": "https://docs.y.uno/errors/VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "title": "Request validation failed",
  "status": 400,
  "detail": "One or more fields did not pass validation",
  "trace_id": "01HX31R6QK7E2F4G5H6J7K8M9N",
  "errors": [
    {
      "field": "payment_method",
      "code": "INVALID_PAYMENT_METHOD_SOURCE",
      "message": "Exactly one of 'vaulted_token' or 'detail.<card|wallet|bank_transfer>' must be set."
    },
    {
      "field": "amount.value",
      "code": "OUT_OF_RANGE",
      "message": "Value must be greater than 0."
    }
  ]
}

{
  "type": "https://docs.y.uno/errors/UNREFERENCED_REFUND_NOT_SUPPORTED",
  "code": "UNREFERENCED_REFUND_NOT_SUPPORTED",
  "title": "No provider supports this payment-method for non-referenced refunds",
  "status": 422,
  "detail": "Provider 'CHECKOUTCOM' does not define operation_type=Credit for CARD payment-methods in country US.",
  "trace_id": "01HX31R6QK7E2F4G5H6J7K8M9N"
}

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"
}

{
  "type": "https://docs.y.uno/errors/VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "title": "Request validation failed",
  "status": 400,
  "detail": "One or more fields did not pass validation",
  "trace_id": "01HX31R6QK7E2F4G5H6J7K8M9N",
  "errors": [
    {
      "field": "payment_method",
      "code": "INVALID_PAYMENT_METHOD_SOURCE",
      "message": "Exactly one of 'vaulted_token' or 'detail.<card|wallet|bank_transfer>' must be set."
    },
    {
      "field": "amount.value",
      "code": "OUT_OF_RANGE",
      "message": "Value must be greater than 0."
    }
  ]
}

{
  "type": "https://docs.y.uno/errors/UNREFERENCED_REFUND_NOT_SUPPORTED",
  "code": "UNREFERENCED_REFUND_NOT_SUPPORTED",
  "title": "No provider supports this payment-method for non-referenced refunds",
  "status": 422,
  "detail": "Provider 'CHECKOUTCOM' does not define operation_type=Credit for CARD payment-methods in country US.",
  "trace_id": "01HX31R6QK7E2F4G5H6J7K8M9N"
}

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.

string

required

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

string

required

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

string

required

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

string

required

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

string

required

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

string

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

string

required

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

string

required

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

object

required

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

Show properties

number

required

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

string

required

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

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.

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

string

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

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

object

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

Show properties

object

required

Show properties

string

required

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

string

required

Name as it appears on the card.

integer

required

Card expiration month (1–12).

integer

required

Card expiration year.

string

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

string

required

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

string

Card type: CREDIT, DEBIT, PREPAID.

string

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

object

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

object

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

object

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

Show properties

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.

string

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

string

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

string

required

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

string

required

Recipient name on the account.

string

INDIVIDUAL or ENTITY.

object

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

Show properties

string

e.g., SSN, EIN

string

e.g., 123-45-6789

object

Use for PayPal Express Checkout refunds.

Show properties

string

required

PayPal payerID of the recipient.

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.

string

Your external customer identifier.

string

Recipient’s first name.

string

Recipient’s last name.

string

Recipient’s email address.

object

{ country_code, number, extension }.

object

National identification document. { document_type, document_number }.

string

YYYY-MM-DD.

string

ISO 3166-1 alpha-2 country code.

string

Recipient’s IP address (when known).

object

Postal address.

object

Same shape as billing_address.

string

INDIVIDUAL or ENTITY.

string

Required when type = ENTITY.

array of objects

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

Show properties

string

Free-form label.

string

Free-form value. Max 512 characters.

string

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

object

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

Show properties

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"
}

{
  "type": "https://docs.y.uno/errors/VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "title": "Request validation failed",
  "status": 400,
  "detail": "One or more fields did not pass validation",
  "trace_id": "01HX31R6QK7E2F4G5H6J7K8M9N",
  "errors": [
    {
      "field": "payment_method",
      "code": "INVALID_PAYMENT_METHOD_SOURCE",
      "message": "Exactly one of 'vaulted_token' or 'detail.<card|wallet|bank_transfer>' must be set."
    },
    {
      "field": "amount.value",
      "code": "OUT_OF_RANGE",
      "message": "Value must be greater than 0."
    }
  ]
}

{
  "type": "https://docs.y.uno/errors/UNREFERENCED_REFUND_NOT_SUPPORTED",
  "code": "UNREFERENCED_REFUND_NOT_SUPPORTED",
  "title": "No provider supports this payment-method for non-referenced refunds",
  "status": 422,
  "detail": "Provider 'CHECKOUTCOM' does not define operation_type=Credit for CARD payment-methods in country US.",
  "trace_id": "01HX31R6QK7E2F4G5H6J7K8M9N"
}

Unreferenced Refund Status Retrieve Unreferenced Refund by ID

⌘I