The Customer Object

Represents a customer in Yuno’s system, used across checkout sessions, payments, enrollments, and subscriptions.

The Customer object stores buyer information used across checkout sessions, payments, enrollments, and subscriptions. Customers can be created explicitly via the Create Customer endpoint or implicitly during payment creation.

Customer records are shared across all payment methods and providers. Creating a customer once allows you to reference them in every subsequent transaction using their id or merchant_customer_id.

Object fields

id · string

Yuno’s unique customer identifier (UUID v4). Server-generated.

Example: c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f

merchant_customer_id · string · required

Your own internal customer identifier. Non-blank string, unique per Yuno account. Used for reconciliation and to retrieve a customer with Retrieve Customer by External ID.

Example: cust-internal-001

merchant_customer_created_at · string | null

The customer’s original registration date on your platform. Use ISO 8601 with microseconds and Z suffix. For example, 2024-01-15T12:34:56.123456Z.

first_name · string | null

Customer’s first name (legal first name as shown on the identification document).

Example: Maria

last_name · string | null

Customer’s last name (legal surname as shown on the identification document).

Example: Silva

email · string | null

Customer’s email address. Strongly recommended. Required by most APMs (PIX, Boleto, OXXO, PSE) and by 3DS challenge flows.

Example: [e-mail]

gender · string | null

Customer’s gender.

Values: M (male), F (female), NB (non-binary).

date_of_birth · string | null

Date of birth in YYYY-MM-DD format (calendar date only. No time component).

Example: 1990-02-28

country · string | null

Customer’s country of residence. ISO 3166-1 alpha-2 code.

Example: BR

nationality · string | null

Customer’s nationality. ISO 3166-1 alpha-2 code.

Example: BR

document · object | null

Customer’s identification document. Required by most Latin American APMs at payment time.

Show document

document_type · string · required

Type of identification document. Common values per country: Brazil. CPF, CNPJ; Colombia. CC, CE, NIT, PP, TI; Mexico. CURP, RFC; Argentina. DNI, CUIT, CUIL; Chile. RUT, RUN; Peru. DNI, RUC; Uruguay. CI, RUT; United States. SSN; international. PASSPORT.

document_number · string · required

Document number, digits only (no separators or formatting). Examples: 12345678901 (CPF. 11 digits), 12345678000190 (CNPJ. 14 digits).

phone · object | null

Customer’s phone number. Both nested fields are required when phone is present.

Show phone

country_code · string · required

Country calling code (E.164 country code) without the leading +. Up to 3 characters.

Example: 55

number · string · required

Subscriber number without the country code. Digits only. No spaces, dashes, or parentheses.

Example: 11999990000

billing_address · object | null

Customer’s billing address. All nested fields are optional, but completeness improves authorization rates and 3DS frictionless eligibility.

Show billing_address

address_line_1 · string

Primary street address.

Example: Av. Paulista, 1000

address_line_2 · string

Additional address detail (apartment, suite, floor, unit).

building_number_1 · string

Primary building number (used in markets where street name and building number are stored separately, e.g., Brazil).

building_number_2 · string

Secondary building number (complement, block, or tower reference).

city · string

City name.

state · string

State, province, or department.

zip_code · string

Postal / ZIP code.

neighborhood · string

Neighborhood, district, or borough.

country · string

ISO 3166-1 alpha-2 country code.

shipping_address · object | null

Customer’s shipping address. Same structure as billing_address.

metadata · array | null

Custom key/value entries you attached to the customer. Array of { key, value } objects.

Show metadata[]

key · string · required

Metadata entry key.

value · string · required

Metadata entry value.

created_at · string

Server-generated ISO 8601 timestamp of when the customer record was created.

Example: 2026-03-01T10:00:00.000000Z

updated_at · string

Server-generated ISO 8601 timestamp of the last update to the customer record.

Example: 2026-03-01T10:00:00.000000Z

Example

{
  "id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
  "merchant_customer_id": "cust-internal-001",
  "merchant_customer_created_at": "2024-01-15T12:34:56.123456Z",
  "first_name": "Maria",
  "last_name": "Silva",
  "email": "[e-mail]",
  "gender": "F",
  "date_of_birth": "1990-02-28",
  "country": "BR",
  "nationality": "BR",
  "document": {
    "document_type": "CPF",
    "document_number": "12345678901"
  },
  "phone": {
    "country_code": "55",
    "number": "11999990000"
  },
  "billing_address": {
    "address_line_1": "Av. Paulista, 1000",
    "address_line_2": "Apto 502",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "zip_code": "01310100",
    "neighborhood": "Bela Vista"
  },
  "shipping_address": {
    "address_line_1": "Av. Paulista, 1000",
    "address_line_2": "Apto 502",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "zip_code": "01310100",
    "neighborhood": "Bela Vista"
  },
  "metadata": [
    { "key": "loyalty_tier", "value": "gold" },
    { "key": "signup_source", "value": "web" }
  ],
  "created_at": "2026-03-01T10:00:00.000000Z",
  "updated_at": "2026-03-01T10:00:00.000000Z"
}

Document requirements by country

The document object is optional at the schema level, but most Latin American APMs reject the eventual payment if it is missing or has the wrong type for the country.

Country	Common payment methods	Document type	Format
Brazil	PIX, Boleto, Card	CPF (individuals), CNPJ (businesses)	11 digits / 14 digits
Colombia	PSE, Nequi, Card	CC, CE, NIT, PP, TI	Varies
Mexico	OXXO, SPEI, Card	CURP, RFC	18 chars / 12-13 chars
Argentina	Card, Pago Fácil, Rapipago	DNI, CUIT, CUIL	7-8 / 11 digits
Chile	Webpay, Bank Transfer, Card	RUT, RUN	8-9 digits + check digit
Peru	PagoEfectivo, Card	DNI, RUC	8 digits / 11 digits
Uruguay	Card, Redpagos	CI, RUT	Varies

Related endpoints

• Create Customer. POST /v1/customers
• Get Customer. GET /v1/customers/{customer_id}
• Retrieve Customer by External ID. GET /v1/customers/merchant-customer-id/{merchant_customer_id}
• List Customers. GET /v1/customers
• Update Customer. PATCH /v1/customers/{customer_id}
• Delete Customer. DELETE /v1/customers/{customer_id}

Related concepts

• Customers. How customers work in Yuno
• Tokens. How customer tokens and vaulting work
• Country Reference. Document types and address requirements per country