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

# Montos y monedas

> Cómo enviar amount.value: unidades mayores, códigos de moneda ISO 4217 y la regla de números enteros para monedas sin decimales como KRW, JPY y CLP.

Cada monto que envías a la API de Yuno es un objeto con un `currency` y un `value`. `currency` es un código ISO 4217 alfabético de tres letras. `value` es el monto en unidades mayores de esa moneda: envía `25` para USD 25.00, no `2500`.

Dieciséis monedas no tienen unidades menores. Para estas monedas, `value` debe ser un número entero. Yuno no redondea ni trunca el valor por ti: una solicitud con un `value` fraccionario devuelve `400 INVALID_PARAMETERS` antes de que Yuno cree algo.

```json Request theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
"amount": {
  "currency": "KRW",
  "value": 11833
}
```

## Monedas sin decimales

| Código | Moneda |
| :- | :- |
| `BIF` | Franco burundés |
| `CLP` | Peso chileno |
| `DJF` | Franco yibutiano |
| `GNF` | Franco guineano |
| `ISK` | Corona islandesa |
| `JPY` | Yen japonés |
| `KMF` | Franco comorense |
| `KRW` | Won surcoreano |
| `PYG` | Guaraní paraguayo |
| `RWF` | Franco ruandés |
| `UGX` | Chelín ugandés |
| `VND` | Dong vietnamita |
| `VUV` | Vatu de Vanuatu |
| `XAF` | Franco CFA de África Central |
| `XOF` | Franco CFA de África Occidental |
| `XPF` | Franco CFP |

Cualquier otra moneda acepta un `value` decimal. `COP` no está en la lista, porque ISO 4217 asigna dos dígitos decimales al peso colombiano, por lo que `COP 11833.2` se acepta, mientras que `KRW 11833.2` no. Los dígitos decimales de la moneda de cada país aparecen en la [referencia de países](https://docs.y.uno/reference/country-reference.md).

Los ceros finales no hacen fallar la validación: `11833.00` se acepta para `KRW`, `11833.2` se rechaza.

## Dónde se aplica la regla

Yuno valida cada campo que lleva un `value` junto a un código de moneda, tanto en la solicitud que crea la operación como en la que la actualiza:

* `amount` en [sesiones de checkout](https://docs.y.uno/es/reference/checkout-sessions/create-checkout-session.md), en [pagos](https://docs.y.uno/es/reference/payments/create-payment.md) y en [enlaces de pago](https://docs.y.uno/reference/payment-links/create-payment-link.md).
* `amount` en reembolsos: [Reembolsar un pago](https://docs.y.uno/reference/payments/refund-payment.md), [Cancelar o reembolsar un pago](https://docs.y.uno/reference/payments/cancel-or-refund-a-payment.md) y [Cancelar o reembolsar un pago con transacción](https://docs.y.uno/reference/payments/cancel-or-refund-payment-with-transaction.md). La validación se ejecuta antes de que Yuno busque el pago, por lo que un reembolso parcial fraccionario de un pago en `KRW` falla con el mismo error.
* `currency_conversion.cardholder_amount` frente a `cardholder_currency`, y `merchant_amount` frente a `merchant_currency`.
* Los montos de pagos divididos y el `fixed_amount` de la configuración de división de un destinatario.
* Los montos de suscripciones, planes, medidores, métodos de envío y payout.

## El error

```json Response theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "code": "INVALID_PARAMETERS",
  "messages": [
    "The field 'amount.value' has an invalid amount."
  ]
}
```

El mensaje indica el campo que falló. Un `cardholder_amount` fraccionario devuelve `The field 'currency_conversion.cardholder_amount' has an invalid amount.`

## Redondea una sola vez, al construir el pedido

Si tu catálogo fija los precios de los artículos con dos decimales, redondea cada línea a una unidad entera al construir el pedido, con la regla de redondeo que exija tu política de precios, y guarda los valores redondeados. Envía esos mismos números enteros en la sesión de checkout, en el pago y en cada reembolso.

No redondees en cada llamada a la API a partir de los valores con dos decimales. Un total redondeado una vez y un conjunto de líneas redondeadas una por una pueden diferir en una unidad, lo que hace que un reembolso parcial falle o que la suma de los reembolsos supere el monto cobrado.

Para un reembolso parcial, calcula el `value` del reembolso a partir de los montos de línea guardados en unidades enteras y comprueba que la suma de todos los reembolsos del pago no supere su `amount.value` cobrado.

## Ejemplo

La primera solicitud se rechaza porque `value` tiene una parte fraccionaria. La segunda solicitud es el mismo pedido con el valor redondeado al won.

```bash Rejected theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/checkout/sessions \
     --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 '
{
  "account_id": "{{account-code}}",
  "customer_id": "{{customer-id}}",
  "merchant_order_id": "order-kr-0001",
  "payment_description": "Tickets",
  "country": "KR",
  "amount": {
    "currency": "KRW",
    "value": 11833.2
  }
}
'
```

```json Response theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "code": "INVALID_PARAMETERS",
  "messages": [
    "The field 'amount.value' has an invalid amount."
  ]
}
```

```bash Accepted theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/checkout/sessions \
     --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 '
{
  "account_id": "{{account-code}}",
  "customer_id": "{{customer-id}}",
  "merchant_order_id": "order-kr-0001",
  "payment_description": "Tickets",
  "country": "KR",
  "amount": {
    "currency": "KRW",
    "value": 11833
  }
}
'
```

Un reembolso parcial del mismo pago sigue la misma regla:

```bash Partial refund theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
     --url https://api-sandbox.y.uno/v1/payments/{{payment-id}}/cancel-or-refund \
     --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": "One ticket refunded",
  "reason": "REQUESTED_BY_CUSTOMER",
  "merchant_reference": "order-kr-0001-refund-1",
  "amount": {
    "currency": "KRW",
    "value": 1183
  }
}
'
```

## Relacionado

* **Referencia:** [Solución de problemas](https://docs.y.uno/es/docs/troubleshooting.md) enumera este error junto con las demás respuestas comunes.
* **Referencia:** la [referencia de países](https://docs.y.uno/reference/country-reference.md) indica la moneda y sus dígitos decimales para cada país.
* **Guía:** [Reembolsar pagos](https://docs.y.uno/docs/direct-integration-use-cases/refund-payments.md) cubre los reembolsos completos y parciales.
* **Referencia:** [Detalles del pago](https://docs.y.uno/docs/payment-features/payment-amount-details.md) desglosa un total en comisiones, envío, propinas, impuestos y descuentos.


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