Create a Payment - Yuno API Documentation

Overview

The Create Payment endpoint (POST /v1/payments) processes a transaction using the payment method and amount specified. This guide covers method-specific requirements and provides ready-to-use code examples.

Endpoint

POST https://api-sandbox.y.uno/v1/payments

Card Payment

const response = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: {
      type: 'CARD',
      token: 'one-time-token-from-tokenization',
    },
    amount: { currency: 'USD', value: 50.00 },
    country: 'US',
    customer: {
      email: 'dee@hock.example',
      first_name: 'Dee',
      last_name: 'Hock',
    },
    description: 'Order #123',
  }),
});
const payment = await response.json();

Card Payment (Europe)

Card payments in Europe require a billing address for 3DS authentication. This example uses Germany (DE) with EUR currency.

const euCardPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: {
      type: 'CARD',
      token: 'one-time-token-from-tokenization',
    },
    amount: { currency: 'EUR', value: 89.99 },
    country: 'DE',
    customer: {
      email: 'hans.mueller@example.com',
      first_name: 'Hans',
      last_name: 'Mueller',
      billing_address: {
        street: 'Friedrichstrasse 43',
        city: 'Berlin',
        postal_code: '10117',
        country: 'DE',
      },
    },
    description: 'Order #789',
  }),
});
const payment = await euCardPayment.json();

3D Secure (3DS) authentication is mandatory for card payments in Europe under PSD2 (Payment Services Directive 2). Always include a complete billing_address to improve 3DS pass rates and reduce declines.

PIX Payment (Brazil)

PIX requires customer document information (CPF or CNPJ):

const pixPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: { type: 'PIX' },
    amount: { currency: 'BRL', value: 100.00 },
    country: 'BR',
    customer: {
      email: 'cliente@example.com',
      document: {
        document_type: 'CPF',
        document_number: '12345678901',
      },
    },
  }),
});

PIX payments return a payment_method.pix object containing qr_code (base64 image) and qr_code_url (copy-paste code). Display either to the customer.

SEPA Direct Debit (Europe)

SEPA Direct Debit is the standard bank transfer method across the Single Euro Payments Area. It requires the customer’s IBAN.

const sepaPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: {
      type: 'SEPA_DIRECT_DEBIT',
      iban: 'DE89370400440532013000',
    },
    amount: { currency: 'EUR', value: 150.00 },
    country: 'DE',
    customer: {
      email: 'hans.mueller@example.com',
      first_name: 'Hans',
      last_name: 'Mueller',
    },
    description: 'Subscription #200',
  }),
});
const payment = await sepaPayment.json();

SEPA Direct Debit is Europe’s primary bank-to-bank transfer method, covering 36 countries in the eurozone and beyond. Settlement typically takes 2-5 business days. SEPA is especially popular for recurring payments and subscriptions.

iDEAL (Netherlands)

iDEAL is the leading online payment method in the Netherlands. Customers select their bank and authenticate the payment via their banking app.

const idealPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: { type: 'IDEAL' },
    amount: { currency: 'EUR', value: 75.00 },
    country: 'NL',
    customer: {
      email: 'jan.devries@example.com',
      first_name: 'Jan',
      last_name: 'de Vries',
    },
    description: 'Order #350',
  }),
});
const payment = await idealPayment.json();

iDEAL accounts for approximately 60% of all Dutch e-commerce transactions. The payment flow redirects customers to their bank for authentication. The response includes a redirect_url field. Use webhooks to receive the final payment status.

Bank Transfer

const bankTransfer = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: { type: 'BANK_TRANSFER' },
    amount: { currency: 'COP', value: 50000 },
    country: 'CO',
    customer: {
      email: 'cliente@example.com',
      document: {
        document_type: 'CC',
        document_number: '1234567890',
      },
    },
  }),
});

OXXO Payment (Mexico)

OXXO is a cash voucher method in Mexico. The customer receives a reference number to pay at any OXXO store. Only customer.email is required.

const oxxoPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: { type: 'OXXO' },
    amount: { currency: 'MXN', value: 500.00 },
    country: 'MX',
    customer: {
      email: 'cliente@example.com',
    },
  }),
});

OXXO payments return a voucher reference in the response. The customer must complete payment at an OXXO store within the expiration window (typically 24-72 hours). Use webhooks to receive confirmation when the customer pays.

Card Payment (Mexico)

Card payments in Mexico use MXN currency. Document fields (CURP or RFC) are optional for cards but recommended for higher approval rates.

const mxCardPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: {
      type: 'CARD',
      token: 'one-time-token-from-tokenization',
    },
    amount: { currency: 'MXN', value: 1500.00 },
    country: 'MX',
    customer: {
      email: 'cliente@example.com',
      first_name: 'Maria',
      last_name: 'Garcia',
      document: {
        document_type: 'CURP',
        document_number: 'GARM850101MDFRRL09',
      },
    },
    description: 'Order #456',
  }),
});

PSE Payment (Colombia)

PSE (Pagos Seguros en Linea) is a bank transfer method in Colombia. It requires a Colombian identification document (CC for individuals, NIT for businesses).

const psePayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: { type: 'PSE' },
    amount: { currency: 'COP', value: 75000 },
    country: 'CO',
    customer: {
      email: 'cliente@example.com',
      document: {
        document_type: 'CC',
        document_number: '1234567890',
      },
    },
  }),
});

PSE payments redirect the customer to their bank’s website to authorize the transfer. The response includes a redirect_url field. Use webhooks to receive the final payment status after the customer completes authorization.

UPI (India)

UPI (Unified Payments Interface) is India’s dominant real-time payment system. Customers pay using their Virtual Payment Address (VPA).

const upiPayment = await fetch('https://api-sandbox.y.uno/v1/payments', {
  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({
    checkout_session: 'session-id',
    payment_method: {
      type: 'UPI',
      vpa: 'customer@upi',
    },
    amount: { currency: 'INR', value: 2500.00 },
    country: 'IN',
    customer: {
      email: 'priya.sharma@example.com',
      first_name: 'Priya',
      last_name: 'Sharma',
    },
    description: 'Order #512',
  }),
});
const payment = await upiPayment.json();

UPI payments are confirmed in real time via the customer’s banking app. The response may include a redirect_url or a collect request is sent to the customer’s VPA. Use webhooks to receive the final payment status.

Required Fields by Payment Method

Payment Method	Required Customer Fields	Country	Currency	Region
CARD	`email`	Global	Multiple	All
CARD (LATAM)	`email`, `document` (recommended)	BR, CO, MX	Local	LATAM
CARD (Europe)	`email`, `billing_address`	EU	EUR/GBP	Europe
PIX	`email`, `document` (CPF/CNPJ)	BR	BRL	LATAM
SEPA_DIRECT_DEBIT	`email`, `iban`	EU	EUR	Europe
IDEAL	`email`	NL	EUR	Europe
BANCONTACT	`email`	BE	EUR	Europe
BANK_TRANSFER	`email`, `document`	Varies	Varies	LATAM
OXXO	`email`	MX	MXN	LATAM
PSE	`email`, `document` (CC/NIT)	CO	COP	LATAM
SPEI	`email`	MX	MXN	LATAM
UPI	`email`, `vpa`	IN	INR	APAC
GRABPAY	`email`	SG, MY, PH	Local	APAC

Response Structure

{
  "id": "pay_abc123",
  "status": "SUCCEEDED",
  "amount": { "currency": "USD", "value": 50.00 },
  "payment_method": { "type": "CARD", "brand": "VISA", "last_four": "1111" },
  "provider": { "id": "provider-id", "name": "ProviderName" },
  "created_at": "2026-02-28T10:00:00Z"
}

Always verify payment status server-side. Do not rely solely on the synchronous response for fulfillment decisions. Use webhooks for definitive payment status updates.

​Overview

​Endpoint

​Card Payment

​Card Payment (Europe)

​PIX Payment (Brazil)

​SEPA Direct Debit (Europe)

​iDEAL (Netherlands)

​Bank Transfer

​OXXO Payment (Mexico)

​Card Payment (Mexico)

​PSE Payment (Colombia)

​UPI (India)

​Required Fields by Payment Method

​Response Structure

Overview

Endpoint

Card Payment

Card Payment (Europe)

PIX Payment (Brazil)

SEPA Direct Debit (Europe)

iDEAL (Netherlands)

Bank Transfer

OXXO Payment (Mexico)

Card Payment (Mexico)

PSE Payment (Colombia)

UPI (India)

Required Fields by Payment Method

Response Structure