Customers

The buyer record in Yuno. What the customer object is, when you need one, and how it ties to vaulting, checkout, subscriptions, and every payment.

A customer is Yuno’s permanent record of one of your buyers. It holds their identity, documents, addresses, and metadata, and every vaulted payment method, subscription, and enrollment session attaches to it. Create one when you have the buyer’s profile, keep the customer_id Yuno returns, and reuse it across checkout sessions, payments, tokens, and subscriptions.

When you need a customer

Flow	Customer required?
POST /v1/checkout/sessions	Yes. A session cannot open without a customer_id.
POST /v1/subscriptions	Yes. A subscription is permanently tied to one customer.
Vaulting a payment method (one-click, recurring)	Yes. Every vaulted token is owned by exactly one customer.
POST /v1/payments with inline customer fields only	No. Guest payments work without a Yuno customer record, but you lose vaulting and reuse.

Create a customer

1. Send the create request

   Replace the header values and body fields with your own test data.

   cURL

   curl -sS -X POST "https://api-sandbox.y.uno/v1/customers" \
     -H "public-api-key: YOUR_PUBLIC_API_KEY" \
     -H "private-secret-key: YOUR_PRIVATE_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "merchant_customer_id": "your-internal-user-123",
       "first_name": "Dee",
       "last_name": "Hock",
       "email": "[e-mail]",
       "country": "US"
     }'
   
2. Read the response

   On success you receive HTTP 200 with a Yuno-generated customer_id. Store it next to your own user key.

   {
     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
     "merchant_customer_id": "your-internal-user-123",
     "first_name": "Dee",
     "last_name": "Hock",
     "email": "[e-mail]",
     "country": "US",
     "created_at": "2026-04-14T12:00:00.000Z"
   }
   

   Field names in live responses follow the Customer object reference (this sample is illustrative).

Customer identifiers

Identifier	Source	What you use it for
customer_id	Returned by Yuno	Primary key in Customers API paths and in payment payloads
merchant_customer_id	You set it on create	Stable link to your internal user; you can look up by external id

Persist customer_id in your datastore. You need it for enrolled payment methods, one-click flows, and profile updates.

Document types

Most Latin American payment methods require identification on the customer (CPF and CNPJ in Brazil, CC / CE / NIT in Colombia, CURP and RFC in Mexico, and so on). Send document numbers digits only. No dots, dashes, or spaces. Example: CPF 123.456.789-01 → 12345678901.

For the full per-country table of supported document types and formats, see payment methods and the country reference.

Vaulted payment methods

Every vaulted token belongs to exactly one customer. A single customer can hold many methods of different types: cards, digital wallets (Apple Pay, Google Pay, Click to Pay), bank transfer enrollments, BNPL accounts, and payment links. All of them are retrieved from the same endpoint:

GET /v1/customers/{customer_id}/payment-methods

Each entry in the response includes a vaultedToken you can pass as payment_method.token on a future payment, plus masked details safe to render to the buyer (last 4 digits for cards, masked keys for PIX, and so on). Unenrolled methods are excluded.

Typical uses:

• One-click checkout. Surface saved methods at the top of your checkout UI so repeat buyers skip re-entering data.
• Subscriptions and recurring charges. Reference a vaulted token when creating a subscription or a merchant-initiated transaction (MIT).
• Method management. Let customers review and remove their stored methods from an account page.

See tokens for the request example and List payment methods for the full response schema.

Customer in payment requests

When you call Create payment, attach a customer either by reference (customer_id pointing to an existing record), by sending the fields inline, or both. Many methods need specific fields. PIX and Boleto in Brazil need customer.document with a valid CPF or CNPJ; UPI in India needs a VPA; SEPA needs an IBAN. See payment methods for the per-method contract.

{
  "customer": {
    "customer_id": "yuno-customer-id",
    "email": "[e-mail]",
    "document": { "document_type": "CPF", "document_number": "12345678901" }
  }
}

Precedence when both are sent

If you pass customer_id and inline fields, the inline values win for that payment. The provider sees exactly what you sent on the request, not what’s stored on the customer record. This lets you correct or enrich profile data per transaction without touching the stored customer.

After the payment is processed, Yuno backfills empty fields on the stored customer from your inline values. Populated fields are never overwritten by a payment.

Field	Provider sees	Backfilled to the stored customer
email, first_name, last_name, gender, date_of_birth, nationality, document, phone	Inline if present, otherwise the stored value.	Only if the stored field is empty.
billing_address, shipping_address	Inline if present, otherwise the stored value.	Never. Addresses are request-scoped only.
merchant_customer_id, country	The stored customer’s value. Not overridable per payment.	Never.

A payment with customer_id plus inline values may silently update the stored customer the first time a field is filled in. If you need to keep the stored record frozen, use Update customer explicitly rather than passing the fields on a payment. To intentionally edit the stored record, always prefer the Update endpoint. It’s request-scoped vs. backfill-scoped and the intent is explicit.

What next

Customer object

Every field the Customer object supports.

Checkout sessions

Create a session and attach the customer to it.

Payment methods

Country and method requirements per region.

Tokens

How vaulted methods attach to this customer.