BETA. Endpoints are stable in shape but subject to additive changes during the BETA window.
- Payment methods — which methods are shown and in what display order
- Conditions — per-method rules (currency, country, amount, metadata) that gate when a method appears
- Required fields — per-method form field configuration (CVV, installments, billing address, etc.) for both the enrolled (saved-card) and non-enrolled (first-time) flows
- General settings — accepted document types per country
- Styling & SDK settings — colors, fonts, button shapes, dark mode, render mode, payment-method list layout, and Payment Link branding
Base URL
| Environment | Base URL |
|---|
| Production | https://api.y.uno |
| Sandbox | https://api-sandbox.y.uno |
Authentication
Every request must include:
| Header | Required | Description |
|---|
PUBLIC-API-KEY | Yes | Merchant public API key. Found in your Yuno dashboard under Settings → API Keys. |
PRIVATE-SECRET-KEY | Yes | Merchant private secret key, paired with the public key. Never embed in client-side code. |
X-Account-Code | Yes | UUID of the merchant account scope for the request. |
X-Idempotency-Key | Recommended (PATCH) | Client-generated UUID. Re-sending the same request with the same key is safe and will not double-publish. |
Content-Type | Yes (PATCH) | application/json |
Accept | Recommended | application/json |
Credentials must have the v1/checkouts product permission enabled — READ for GET endpoints, WRITE for PATCH endpoints. Permissions are granted per-credential in the dashboard’s API Keys page.
Endpoints
| Method | Path | Purpose |
|---|
GET | /v1/checkouts/{checkout_code} | Fetch the full checkout configuration. |
PATCH | /v1/checkouts/{checkout_code}/publish | Publish a new configuration (payment methods, conditions, required fields, general settings). |
GET | /v1/checkouts/payment-methods/{payment_method_type}/required-fields | List configurable required fields for a payment method. |
GET | /v1/checkouts/country-data | Fetch supported countries and their document-type options. |
GET | /v1/checkouts/builder/settings | Fetch styling & SDK settings. |
PATCH | /v1/checkouts/builder/settings | Update styling & SDK settings. |
Key behaviors
PATCH /v1/checkouts/{checkout_code}/publish is a sparse upsert, not a full replace. Payment methods omitted from the payment_methods array retain their previous state — they are not removed or disabled. To disable a method, include it with is_active: false.
- Order is driven by
order_to_show, not by array position. Change the integer values to re-order; lower values are shown first.
- Including
conditions_to_override replaces that method’s condition sets in full. Omitting it leaves existing conditions intact. The same rule applies to required_fields_to_override and general_settings.
- Changes take effect immediately. Validate payloads against the sandbox base URL before applying to production.
- New payment-method rows cannot be created via the publish endpoint. Methods must already exist on the checkout. Contact your Yuno TAM to add additional methods.
- Enrolled and non-enrolled flows are independent. When configuring required fields for CARD, send both
fields (non-enrolled) and enrollment_fields (enrolled). To leave one flow untouched, pass an empty array for that side.
active_enrollment_type only applies to type: "PAYMENT_METHOD" entries that support enrollment (e.g. CARD). For type: "ENROLLMENT" entries (e.g. PAYPAL_ENROLLMENT, NU_PAY_ENROLLMENT), omit active_enrollment_type and toggle is_active instead.- Required-field conditions: only the first set is persisted. Within
required_fields_to_override.fields[].conditions_to_override (and the enrolled equivalent), only the first element of the array is stored. Send a single condition set per field — additional sets are silently dropped.
conditions_to_override at the required-field level uses condition_value (not values) on each condition object. Same concept as payment-method conditions — different field name preserved for backward compatibility. Don’t mix them up.
