> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Programmatically configure your Yuno checkout — payment methods, conditions, required fields, and styling — via Yuno's public B2B API.

<Warning>
  **BETA.** Endpoints are stable in shape but subject to additive changes during the BETA window.
</Warning>

The Checkout Builder Management API lets you read and update a merchant's checkout configuration:

* **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` |

All examples in this reference use the production base URL. The sandbox host accepts the same endpoints and payload shapes.

## 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`                                                                                        |

<Note>
  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.
</Note>

## 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

<Note>
  **`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`.
</Note>

* **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.