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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Uso de sellers en pagos

> Guía para referenciar un seller registrado en las solicitudes de pago mediante additional_data.seller_details.

Una vez que se registra un mapeo de seller, puedes referenciarlo en las solicitudes de pago mediante `additional_data.seller_details`. El sistema resuelve automáticamente el `merchant_id` correcto al momento del pago, según el proveedor que procesa el pago.

## Referenciar un seller

Puedes referenciar un seller con cualquiera de los dos identificadores (son **mutuamente excluyentes**: envía uno u otro):

| Campo | Descripción |
| :- | :- |
| `merchant_seller_id` | El identificador propio del comercio (por ejemplo, `"FRANCHISE_STORE_001"`). |
| `seller_id` | El UUID generado por Yuno (por ejemplo, `"f7a1b2c3-d4e5-6789-abcd-ef0123456789"`). |

### Ejemplo: pago con `merchant_seller_id`

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "amount": { "currency": "BRL", "value": 10000 },
  "country": "BR",
  "payment_method": {
    "type": "CARD",
    "token": "pm_tok_abc123"
  },
  "additional_data": {
    "seller_details": {
      "merchant_seller_id": "FRANCHISE_STORE_001"
    }
  }
}
```

### Ejemplo: pago con campos sobrescritos

Cuando envías campos adicionales del seller junto con la referencia al seller, esos campos **sobrescriben** los valores almacenados del seller solo para ese pago. No se guardan de nuevo en el mapeo del seller.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "amount": { "currency": "BRL", "value": 10000 },
  "country": "BR",
  "payment_method": {
    "type": "CARD",
    "token": "pm_tok_abc123"
  },
  "additional_data": {
    "seller_details": {
      "merchant_seller_id": "FRANCHISE_STORE_001",
      "name": "Store 001 - Campinas",
      "document": {
        "type": "CNPJ",
        "number": "98765432000111"
      }
    }
  }
}
```

## Cómo funciona la resolución

1. El comercio envía una solicitud de pago con `merchant_seller_id` o `seller_id` dentro de `additional_data.seller_details`.
2. El pago fluye por el pipeline estándar. El enrutamiento selecciona un proveedor (por ejemplo, Cielo).
3. Después del enrutamiento, el sistema busca el mapeo de franquicia por `(organization, seller_identifier, provider, payment_method_type)`.
4. **Si lo encuentra:** el `merchant_id` de la conexión se sobrescribe con el `merchant_id` resuelto. Cualquier campo del seller enviado en la solicitud sobrescribe los valores almacenados para este pago.
5. **Si no lo encuentra o el servicio no está disponible:** el pago continúa con el `merchant_id` predeterminado de la conexión (fallback controlado).

### Retrocompatibilidad

Cuando no hay ni `seller_id` ni `merchant_seller_id`, se omite por completo la función de franquicias: sin impacto en los flujos existentes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.