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

# Detalles del pago

> Desglosa el total de un pago en sus componentes de comisión, envío, propinas, impuestos y descuento para dar transparencia

La API te permite desglosar el total de un pago en componentes individuales, como cargos base, impuestos, comisiones, propinas y descuentos.

* [Comisión](#fee-amount)
* [Envío](#shipping-amount)
* [Propinas](#tips)
* [Impuestos](#taxes)
* [Descuentos](#discounts)
* [Validaciones del cliente](#customer-validations)

Estos campos son informativos: cada componente ya está incluido en el `amount.value` total del pago y no se suma encima de él. La única excepción es un descuento `YUNO_PROMOTION`: envías el `amount` original y Yuno cobra `amount.value` menos ese descuento (consulta [Descuentos](#discounts)).

## Monto de la comisión

Un campo dedicado (`additional_data.order.fee_amount`) te permite especificar el monto de la comisión por tus servicios que está incluido en la transacción.

En el siguiente ejemplo puedes ver una solicitud que aclara que una comisión de 180 JPY forma parte de una transacción final de 5000 JPY. Este campo es solo informativo: el `fee_amount` ya está incluido en el monto final de la transacción y no se suma por separado.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "JP",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "JPY",
        "value": 5000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "fee_amount": 180.00
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'
```

## Monto de envío

Un campo dedicado (`additional_data.order.shipping_amount`) te permite especificar el monto de envío que está incluido en la transacción.

En el siguiente ejemplo puedes ver una solicitud que aclara que un monto de envío de 270 JPY forma parte de una transacción final de 5000 JPY. Este campo es solo informativo: el `shipping_amount` ya está incluido en el monto final de la transacción y no se suma por separado.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "JP",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "JPY",
        "value": 5000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "shipping_amount": 270.00
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'
```

## Propinas

Un campo dedicado (`additional_data.order.tip_amount`) te permite especificar el monto de las propinas que está incluido en la transacción.

En el siguiente ejemplo puedes ver una solicitud que aclara que una propina de 50 JPY forma parte de una transacción final de 5000 JPY. Este campo es solo informativo: el `tip_amount` ya está incluido en el monto final de la transacción y no se suma por separado.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "JP",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "JPY",
        "value": 5000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "tip_amount": 50.00
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'
```

## Impuestos

Un arreglo dedicado de objetos (`additional_data.order.taxes`) te permite especificar los montos de impuestos por tus servicios que están incluidos en la transacción.

| Campo | Tipo | Descripción | Ejemplo |
| :- | :- | :- | :- |
| type\* | enum | Tipo de impuesto. | VAT |
| tax\_base | float | Monto base gravado del pago. | 10000.00 |
| value\* | float | Valor del monto del impuesto del pago. | 2100.00 |
| percentage | float | Tasa del impuesto | 21.00 |

| Tipo de impuesto | Disponibilidad | Descripción |
| :- | :- | :- |
| VAT | COL, ECU | Impuesto al valor agregado. También conocido como IVA. |
| CONSUMPTION\_TAX | COL | También conocido como "Impuesto al consumo". En Colombia, el impuesto nacional al consumo es un impuesto indirecto que se aplica a la venta de bienes y servicios específicos, como bebidas alcohólicas, cigarrillos y servicios de telefonía móvil, entre otros. La tasa varía según el bien o servicio. |
| AIRPORT\_TAX | COL, BRL | Este impuesto es una tarifa que se cobra a los pasajeros por el uso de las instalaciones del aeropuerto. Varía según el aeropuerto y puede incluir tasas nacionales e internacionales. |
| VAT\_LAW\_17934 | UYU | En Uruguay, la Ley N.º 17.934 se refiere a las regulaciones que establecen modificaciones y disposiciones específicas relacionadas con el impuesto al valor agregado (VAT). Esta ley puede incluir regulaciones sobre exenciones, tasas especiales y procedimientos administrativos. |
| VAT\_LAW\_19210 | UYU | En Uruguay, la Ley N.º 19.210 establece regulaciones adicionales o modificaciones a las reglas del VAT. Esta ley puede centrarse en aspectos como la digitalización de los procesos tributarios, nuevas tasas de impuestos o ajustes en las exenciones y los tratamientos fiscales de ciertos bienes y servicios. |
| VAT\_EXEMPTION | COL, ECU | Exención del impuesto al valor agregado |
| ISV | DOM | Impuesto sobre las ventas. También conocido como "Impuesto Sobre las Ventas". En la República Dominicana, el ISV, comúnmente conocido como ITBIS (Impuesto a la Transferencia de Bienes Industrializados y Servicios), es un impuesto al valor agregado que se aplica a la transferencia de bienes y servicios. El ITBIS es similar al VAT de otros países, donde el impuesto se aplica en cada etapa del proceso de producción y distribución. |

En el siguiente ejemplo puedes ver una solicitud que aclara qué impuestos forman parte de una transacción final de 1000.00 USD. Este campo es solo informativo; la estructura `taxes` ya está incluida en el monto final de la transacción y no se ha sumado por separado.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "US",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "USD",
        "value": 1000.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "taxes": [
                {
                  "type": "AIRPORT_TAX",
                  "tax_base":400000.00
                },
                {
                  "type": "VAT",
                  "value": 320000.00,
                  "tax_base":2000000.00
                }
              ]
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'
```

## Descuentos

Un arreglo dedicado de objetos (`additional_data.order.discounts`) te permite especificar los descuentos que están incluidos en la transacción.

Cada línea tiene un `type`. `MERCHANT` (el valor predeterminado) es un descuento que calculaste tú: `id`, `name` y `unit_amount` son obligatorios, y `id` y `name` tienen de 3 a 255 caracteres. `YUNO_PROMOTION` es una [cotización de promoción](https://docs.y.uno/docs/payment-features/promotions) calculada por Yuno, solo con `quote_id`; rechaza `id`, `name` y `unit_amount`, una línea `MERCHANT` rechaza `quote_id`, y cualquier combinación devuelve `400 INVALID_PARAMETERS`. Una línea con `quote_id` y sin `type` se interpreta como `YUNO_PROMOTION`. Escribe el `type` exactamente como se muestra, en mayúsculas: cualquier otra grafía devuelve `400`. Una cotización por pago y, en total, como máximo 10 líneas de descuento. La línea `YUNO_PROMOTION` se acepta solo en Create Payment: los pagos con varios métodos, los enlaces de pago, las sesiones de checkout y la captura la rechazan con `400`, y un pago que incluye un `subscription` o un `external_subscription` la rechaza con `422 PROMOTION_SUBSCRIPTION_UNSUPPORTED`.

En la respuesta y en cada webhook `payment.*`, Yuno completa la línea `YUNO_PROMOTION` (`quote_id`, `id` = el id de la promoción, `unit_amount` en la moneda del pago y, cuando Yuno lo tiene, `name`) y agrega un `discount_amount`, la suma de esas líneas. Tus líneas `MERCHANT` conservan su `id`, `name` y `unit_amount`; cuando el pago incluye una promoción de Yuno, la respuesta de Create Payment, Retrieve Payment y los webhooks listan primero la línea de Yuno y marcan la tuya con `type: MERCHANT`. El `amount` nunca se reescribe; el monto neto cobrado está en la transacción (`transactions.amount`).

En el siguiente ejemplo puedes ver una solicitud que aclara que un descuento de 5 USD forma parte de una transacción final de 50 USD. Los descuentos calculados por el comercio son informativos: el monto ya está incluido en `amount` y no se suma de nuevo.

```json Example theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments \
     --header 'X-Idempotency-Key: <Your idempotency-key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'private-secret-key: <Your private-secret-key>' \
     --header 'public-api-key: <Your public-api-key>' \
     --data '
{
    "description": "Test",
    "account_id": "{{account-code}}",
    "merchant_order_id": "0000023",
    "country": "US",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "USD",
        "value": 50.00
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "additional_data": {
          "order": {
              "discounts": [
                {
                  "id": "10OFF",
                  "name":"Offer",
                  "unit_amount":5.00
                }
              ]
          }
      },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED"
              }
           }
        }
    }
}
'
```

## Validaciones del cliente

Un objeto dedicado (`customer_payer.merchant_customer_validations`) te permite especificar ciertas reglas de validación del cliente para las consultas de prevención de fraude.

| Campo | Tipo | Descripción |
| :- | :- | :- |
| account\_is\_verified | bool | Si la cuenta del cliente se ha validado antes por parte del comercio. True de forma predeterminada |
| email\_is\_verified | bool | Si el email del cliente se ha validado antes por parte del comercio. True de forma predeterminada |
| phone\_is\_verified | bool | Si el teléfono del cliente se ha validado antes por parte del comercio. True de forma predeterminada |

En el siguiente ejemplo puedes ver una solicitud que aclara que el cliente fue verificado previamente fuera de Yuno.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
[...]
  "description": "Test PIX",
    "account_id":"{{account-code}}",
    "merchant_order_id": "0000022",
    "country": "BR",
    "amount": {
        "currency": "BRL",
        "value": 50
    },
   "customer_payer": {
        "merchant_customer_id": "AA001",
        "first_name": "VALERIO",
        "last_name": "DE AGUIAR ZORZATO",
        "email": "test_user_1431202421@testuser.com",
        "phone": {
                "number": "11992149494",
                "country_code": "55"
        },
        "document": {
                "document_type": "CPF",
                "document_number": "96050176876"
        },
        "merchant_customer_validations":{
          "phone_is_verified":true,
          "account_is_verified":true,
          "email_is_verified":true
        }
    },
[...]
```


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