Skip to main content
Cash voucher payments generate a printable or digital reference that the customer takes to a physical payment network (convenience store, bank branch, or lottery outlet) to pay in cash. They are common in markets with large unbanked or underbanked populations. Key characteristics:
  • Payment is confirmed hours or days after order creation.
  • The final status arrives via webhook — never synchronously.
  • Vouchers have an expiry date. Unpaid vouchers transition to EXPIRED.
  • No card data or bank credentials are required from the customer.

​
OXXO — Mexico

OXXO is Mexico’s largest convenience store chain with over 20,000 locations nationwide. Customers show or enter the voucher reference at the cashier and pay in cash.

​
Required fields

  • payment_method.type: OXXO
  • customer_payer.email: required to email the voucher to the customer
  • country: MX, currency: MXN

​
Create an OXXO payment

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: YOUR_SECRET_KEY' \
  --header 'account-code: YOUR_ACCOUNT_CODE' \
  --data '{
    "merchant_order_id": "order-mx-002",
    "checkout_session": "SESSION_ID",
    "country": "MX",
    "amount": { "value": 45000, "currency": "MXN" },
    "payment_method": { "type": "OXXO" },
    "customer_payer": {
      "first_name": "Carlos",
      "last_name": "Mendez",
      "email": "carlos.mendez@example.com"
    }
  }'
The response contains the voucher in payment_method.detail: 
{
  "status": "PENDING",
  "payment_method": {
    "detail": {
      "voucher_url": "https://vouchers.example.com/oxxo/ref-abc123.pdf",
      "barcode": "1234567890123456789012345",
      "reference": "ORD-MX-002",
      "expires_at": "2026-04-04T23:59:59Z"
    }
  }
}
Redirect the customer to voucher_url to view and download the PDF, or render the barcode directly in your confirmation screen.

​
Boleto — Brazil

Boleto Bancário is Brazil’s traditional bank-issued payment slip. Customers pay at bank branches, ATMs, lottery outlets (Casas Lotéricas), or via online banking. Boleto is widely accepted even by customers without a bank account.

​
Required fields

  • payment_method.type: BOLETO
  • customer_payer.document: CPF or CNPJ (Brazilian tax ID)
  • country: BR, currency: BRL

​
Create a Boleto payment

curl --request POST \
  --url https://api-sandbox.y.uno/v1/payments \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: YOUR_SECRET_KEY' \
  --header 'account-code: YOUR_ACCOUNT_CODE' \
  --data '{
    "merchant_order_id": "order-br-002",
    "checkout_session": "SESSION_ID",
    "country": "BR",
    "amount": { "value": 8900, "currency": "BRL" },
    "payment_method": { "type": "BOLETO" },
    "customer_payer": {
      "first_name": "Marcos",
      "last_name": "Oliveira",
      "email": "marcos@example.com",
      "document": {
        "document_type": "CPF",
        "document_number": "98765432100"
      }
    }
  }'
The response contains: 
{
  "status": "PENDING",
  "payment_method": {
    "detail": {
      "boleto_url": "https://boleto.example.com/br/ref-xyz789.pdf",
      "barcode": "03399.62990 62010.530003 00063.201016 8 93260000008900",
      "expires_at": "2026-04-04T23:59:59Z"
    }
  }
}
  • boleto_url: Direct link to the PDF — redirect customers here or open in a new tab.
  • barcode: The numeric line for copy-paste payment in internet banking.

​
PagoEfectivo

PagoEfectivo covers Peru and other parts of Latin America, allowing cash payments at partner agents and bank branches. The integration pattern is the same: create a payment with payment_method.type: "PAGOEFECTIVO" and display the returned voucher_url or reference code to the customer. Check Dashboard > Connections to confirm PagoEfectivo is configured for your account.

​
Displaying vouchers

The simplest option: after payment creation, redirect the customer directly to voucher_url. The hosted page is ready to print.
window.location.href = paymentResponse.payment_method.detail.voucher_url;

​
Confirming payment via webhook

When a customer pays at the store, the payment network notifies Yuno, which fires a PAYMENT_STATE_CHANGED event. This can happen minutes to days after the voucher is issued. 
{
  "type": "PAYMENT_STATE_CHANGED",
  "data": {
    "payment_id": "pay_abc123",
    "status": "SUCCEEDED",
    "payment_method_type": "OXXO"
  }
}
Configure your webhook endpoint in Dashboard > Developers > Webhooks and only fulfill orders after receiving status: "SUCCEEDED".
Set voucher expiry to match your order hold window. For example, if you hold inventory for 3 days, set expiry to 72 hours. After expiry, release the inventory and mark the order as cancelled. The default Boleto expiry is 3 calendar days; OXXO defaults vary by provider configuration.
Do not fulfill orders based on the initial PENDING status. Always wait for the SUCCEEDED webhook. Cash voucher payments are final — they cannot be refunded at the network level after cash is accepted.