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

# Solución de problemas

> La respuesta, su causa y la solución para los errores comunes de una integración con Yuno: claves, workflow, rutas, tarjetas de prueba, webhooks, reintentos y montos.

Primeros pasos

Referencia

Busca en la primera columna la respuesta que recibiste y aplica la solución. Antes de volver a enviar una solicitud de pago, averigua si la primera solicitud creó un pago.

## Encuentra tu respuesta

| Respuesta | Causa | Solución |
| - | - | - |
| `401` `INVALID_CREDENTIALS` | Falta el encabezado `public-api-key` o `private-secret-key`, o es incorrecto. Sandbox y producción usan claves distintas. | Envía las claves del entorno al que llamas. En sandbox, cópialas desde el dashboard en Test Mode. Consulta [Autenticación](https://docs.y.uno/reference/getting-started/authentication.md) y [Credenciales de Developers](https://docs.y.uno/docs/using-yuno/settings/developers-credentials.md). |
| La transacción termina en `INTERNAL_ERROR` | El `workflow` no coincide con tu integración. | Usa `DIRECT` cuando tu servidor envía la tarjeta. Usa `SDK_SEAMLESS` en la sesión de checkout cuando el Web SDK crea el pago. |
| No hay proveedor en la respuesta | Card no tiene una ruta publicada. | Abre [Routing](https://docs.y.uno/docs/using-yuno/dashboard-overview/routing.md) y verifica que la ruta de Card esté en la pestaña **Published**. Verifica que Card esté activado en el Checkout builder. |
| La tarjeta es rechazada | Las tarjetas de prueba son específicas de cada proveedor. Las tarjetas del Quickstart solo funcionan cuando tu sandbox enruta Card al Yuno Test Payment Gateway. | Enruta Card al gateway, o usa las tarjetas de prueba del proveedor al que enrutas. Consulta [Yuno Test Payment Gateway](https://docs.y.uno/docs/direct-integration-use-cases/yuno-testing-gateway.md). |
| No hay métodos de pago en el checkout | El Checkout builder solo muestra los métodos de pago que tienen una ruta publicada y están activados. Una condición de visualización (país, monto, moneda o metadata) también puede ocultar un método. | Publica la ruta, activa el método y haz clic en **Publish settings** en el Checkout builder. Luego revisa las condiciones de visualización del método. |
| `400` `INVALID_CUSTOMER_FOR_TOKEN` | El token del pago está asociado a otro objeto de cliente. | Envía el cliente al que pertenece el token. Si creaste la sesión de checkout con un `customer_id`, envía el mismo cliente en `customer_payer.id`. Consulta [Flujo de pago](https://docs.y.uno/es/docs/how-yuno-works/how-yuno-payment-flow-works.md). |
| `checkout.sdk_action_required` es `true` y el checkout no termina | El pago necesita otra acción del cliente, como 3DS o una redirección, y el SDK no la ejecutó. | Llama al método `continuePayment` del SDK después de crear el pago. |
| El pago queda en `PENDING` después de la redirección | El método de pago es asíncrono, así que el pago pasa por `PENDING` antes de llegar a un estado final. | Confirma el estado final en tu servidor con un [webhook](https://docs.y.uno/docs/webhooks/index.md) o con [Retrieve payment](https://docs.y.uno/reference/payments/retrieve-payment-by-id-v2.md) antes de entregar el pedido. |
| Una condición de enrutamiento `METADATA` nunca coincide | La clave no está en `payment.metadata`. Una clave ausente nunca coincide, sea cual sea el operador, incluidos `NOT_EQUAL` y `NOT_ONE_OF`. | Envía la clave en el `metadata` del pago. Para dividir el tráfico según si una clave está presente, consulta [Condiciones de enrutamiento](https://docs.y.uno/reference/organizations/routing/routing-conditions.md). |
| El `x-hmac-signature` no coincide | Tu código parseó o volvió a serializar el cuerpo antes de calcular la firma, o usa otro secreto. | Calcula el HMAC sobre el cuerpo sin procesar de la solicitud con el secreto configurado para ese webhook. Consulta [Verificar firmas de webhook](https://docs.y.uno/docs/webhooks/verify-webhook-signatures-hmac.md). |
| Tu endpoint procesa un webhook dos veces | Yuno reintenta una entrega que no recibe HTTP 200, así que el mismo evento puede llegar más de una vez. | Registra cada evento procesado con su `account_id`, su `type_event` y su clave de idempotencia juntos, y omite un evento que ya esté registrado. Usar solo la clave descarta eventos reales, porque los eventos de reembolso y de contracargo llevan el mismo `data.payment.idempotency_key` que su pago. Consulta [Deduplicación](https://docs.y.uno/docs/webhooks/index.md#de-duplication). |
| El monto es 100 veces el total del pedido | El monto se envió en unidades menores (centavos). `amount.value` está en unidades mayores. | Envía `25` para USD 25.00. Valida el monto contra el pedido que guardaste. |
| `400` `INVALID_PARAMETERS` con `The field 'amount.value' has an invalid amount.` | La moneda no tiene unidades menores (por ejemplo `KRW`, `JPY` o `CLP`) y `value` tiene parte decimal. Yuno no redondea el valor. La misma validación se aplica a los reembolsos, a `cardholder_amount` y a los montos divididos. | Envía un número entero. Redondea una sola vez al armar el pedido y usa el mismo valor en la sesión, en el pago y en cada reembolso. Consulta [Montos y monedas](https://docs.y.uno/docs/basic-concepts/amounts-and-currencies.md). |

## Maneja una solicitud con resultado incierto

Si una solicitud supera el tiempo de espera, pierde la conexión, devuelve un `500` o devuelve una respuesta que no puedes interpretar, reinténtala con el mismo `X-Idempotency-Key`. Un reintento con una clave nueva crea una operación duplicada si la primera solicitud fue exitosa.

El reintento devuelve uno de estos resultados:

* **El pago original.** La primera solicitud creó un pago, así que maneja el estado actual de ese pago. Yuno ignora el cuerpo del reintento.
* **`400 REQUEST_IN_PROCESS`.** La primera solicitud todavía se está procesando. Reintenta con la misma clave después de unos segundos.
* **`400 IDEMPOTENCY_DUPLICATED`.** La primera solicitud falló antes de crear un pago. No existe ningún pago para esta clave y no puedes reutilizarla. Corrige la solicitud y envíala con una clave nueva.
* **Procesamiento normal.** La primera solicitud fue rechazada antes de empezar a procesarse, así que la clave no se usó y el reintento se ejecuta como una solicitud nueva.

Las reglas completas están en [Idempotencia](https://docs.y.uno/reference/getting-started/authentication.md#idempotency). Para cada estado HTTP y código de error, consulta [Códigos de respuesta](https://docs.y.uno/reference/getting-started/response-codes.md).

## Verifica el entorno correcto

Sandbox y producción tienen claves distintas. Antes de comparar registros, verifica tres valores:

* **Host de la API.** Sandbox y producción usan URLs base distintas. Consulta [Developers](https://docs.y.uno/docs/developers.md).
* **Modo del dashboard.** El indicador de contexto en la barra superior muestra **Test** o **Live**.
* **Claves.** Cada cuenta tiene un conjunto de claves distinto para cada modo.

Consulta [Entornos](https://docs.y.uno/docs/using-yuno/environments.md) y [Credenciales de Developers](https://docs.y.uno/docs/using-yuno/settings/developers-credentials.md).

## Pide ayuda con información útil

Escribe a [support@y.uno](mailto:support@y.uno) e incluye:

* El entorno, y la hora de la solicitud con su zona horaria.
* El endpoint, el método HTTP, el estado HTTP y el `code` del error.
* El ID del pago o de la sesión de checkout, y tu referencia del pedido.
* La plataforma y la versión del SDK, lo que esperabas y lo que pasó.
* Los pasos para reproducirlo, con los campos de la solicitud y de la respuesta que importan.

Quita las claves privadas, las credenciales, los números de tarjeta sin procesar y los datos personales que no necesitas enviar. Consulta el [estado del servicio](https://status.y.uno) para ver incidentes en curso, y [Developers](https://docs.y.uno/docs/developers.md) para las versiones y los changelogs de los SDKs.

## Siguientes pasos

<ol>
  <li>[Salir a producción](https://docs.y.uno/es/docs/go-live.md)Guía Claves de producción, una ruta publicada, webhooks verificados y un primer pago real.</li>
  <li>[Códigos de respuesta](https://docs.y.uno/reference/getting-started/response-codes.md)Referencia Los estados HTTP y los códigos de error que devuelve la API de Yuno.</li>
  <li>[Webhooks](https://docs.y.uno/docs/webhooks/index.md)Guía Entrega, reintentos, deduplicación y verificación de firmas.</li>
  <li>[Quickstart](https://docs.y.uno/es/docs/quickstart.md)Tutorial Conecta el gateway de pruebas y envía un pago en sandbox.</li>
</ol>


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