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

# Credenciales almacenadas

> Almacena y reutiliza los datos de la tarjeta en transacciones iniciadas por el cliente o por el comercio, cumpliendo las reglas de las marcas

Según cómo y cuándo se procese un pago, este puede originarse en transacciones iniciadas por el cliente (CIT) o en transacciones iniciadas por el comercio (MIT).

Para garantizar el almacenamiento y el uso responsables de la información del titular de la tarjeta, Visa y Mastercard han establecido pautas y normas para las credenciales almacenadas.

Yuno ha simplificado el proceso para que cumplas con estas reglas de las marcas, y te permite almacenar de forma segura los datos de la tarjeta en Yuno para usarlos más adelante sin perder el cumplimiento.

> [!NOTE]
>
> **Importante: esto no es lo mismo que las suscripciones**
>
> Piensa en quién controla la recurrencia:
>
> * **Credenciales almacenadas**: tú controlas la recurrencia y eres responsable de enviar cada transacción según tu propio calendario y tu propia lógica de recurrencia.
> * **API de suscripciones**: Yuno la controla. Tú das las instrucciones una sola vez y Yuno envía las transacciones automáticamente en tu nombre. Consulta [Suscripciones](https://docs.y.uno/docs/payment-features/subscriptions.md).

* Categorización
* Consideraciones generales
* Crear un pago
* ID del acuerdo de suscripción
* ID de transacción de red
* Tokens originados en billeteras (Apple Pay y Google Pay)

## Categorización

| Categoría | Transacciones iniciadas por el cliente (CIT) | Transacciones iniciadas por el comercio (MIT) |
| :- | :- | :- |
| **Definición** | Transacciones iniciadas por el cliente, como compras en línea y en tienda, o retiros en cajeros automáticos. | Transacciones iniciadas por el comercio o el proveedor de servicios sin la participación activa del cliente. |
| **Ejemplos** | Incluye compras en línea, compras en tienda y retiros en cajeros automáticos. | Incluye pagos recurrentes, renovaciones automáticas de suscripciones y facturación recurrente. |
| **Autenticación** | Normalmente requiere autenticación del titular de la tarjeta para garantizar la seguridad. | Requiere autenticación inicial del cliente para configurarse, con una posible autenticación adicional en las transacciones posteriores, según las normas de seguridad y las políticas del emisor de la tarjeta. |

Determinar si una transacción la inicia el comercio o el cliente tiene implicaciones importantes para la seguridad, la experiencia del usuario, la prevención del fraude y el cumplimiento normativo.

## Consideraciones generales

* **Responsabilidad**: en el contexto de la autenticación reforzada del cliente (SCA) bajo la regulación PSD2 de la Unión Europea, las CIT generalmente requieren una autenticación más estricta que las MIT.
* **Frecuencia**: las transacciones MIT suelen ser recurrentes y periódicas, mientras que las CIT son eventos más ocasionales que dependen de las acciones del cliente.

## Crear un pago con tipo de procesamiento

Para especificar un [pago](https://docs.y.uno/es/reference/payments/create-payment.md) con un tipo de procesamiento, usa la estructura `stored_credentials` dentro de `payment_method.detail.card` al crear un pago.

| Parámetro | Tipo | Descripción |
| - | - | - |
| `reason` | enum | Indica el motivo del almacenamiento de las credenciales para la transacción.  `CARD_ON_FILE`  `SUBSCRIPTION`  `UNSCHEDULED_CARD_ON_FILE` |
| `usage` | enum | Una tarjeta de crédito puede almacenarse con o sin un pago inicial. Este campo indica si es la primera vez que se usa o se reutiliza el vaulted\_token/network\_token.  `FIRST`  `USED` |
| `subscription_agreement_id` | string | El ID del acuerdo con el cliente, obligatorio en ciertos mercados (por ejemplo, MX). |
| `network_transaction_id` | string | El ID proporcionado por Visa/Mastercard en la respuesta del pago inicial, muy recomendado para su uso futuro en transacciones iniciadas por el comercio (MIT). |
| `transaction_link_id` | string | El ID de vínculo de transacción de Mastercard (TLID) devuelto en la respuesta del pago inicial. Mastercard lo exige en las transacciones iniciadas por el comercio (MIT), además del `network_transaction_id`. |

> [!CAUTION]
>
> **Crítico: completa todos los campos obligatorios**
>
> * Al trabajar con transacciones CIT y MIT, es fundamental completar correctamente los campos `usage`, `reason` y `network_transaction_id`. No completarlos adecuadamente puede provocar una **disminución de las tasas de aprobación** y la **pérdida de disputas por contracargo**.
> * Algunos proveedores (por ejemplo, Adyen) exigen que el campo `reason` se mantenga coherente durante todo el ciclo de vida de la transacción. Si tu primera transacción (`usage=FIRST`) usa `reason=SUBSCRIPTION`, todas las transacciones posteriores (`usage=USED`) también deben usar `reason=SUBSCRIPTION`.

Motivos de las credenciales almacenadas

| Motivo | Descripción |
| :- | :- |
| `CARD_ON_FILE` | Un pago iniciado por el cliente con una tarjeta de crédito inscrita previamente, en el que el titular de la tarjeta está presente. Permite a los clientes pagar con un solo clic para una experiencia de pago sin fricción. |
| `SUBSCRIPTION` | Se usa en pagos iniciados por el comercio como parte de una suscripción. Esto no crea una nueva suscripción: usa la [API de suscripciones](https://docs.y.uno/docs/payment-features/subscriptions.md) para la facturación recurrente automatizada. |
| `UNSCHEDULED_CARD_ON_FILE` | Un pago iniciado por el comercio con los datos almacenados de una tarjeta de crédito, que no está relacionado con el calendario ni con el monto de una suscripción. El pago puede ocurrir en cualquier momento. |

### Ejemplo de solicitud

```sh Request (cURL) 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": "DE",
    "merchant_reference" : "reference-{{$randomUUID}}",
    "amount": {
        "currency": "EUR",
        "value": 5000
    },
    "customer_payer": {
        "id":"967ecd18-d898-4b88-9400-dd5b01b18edc"
    },
    "workflow": "DIRECT",
    "payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }
}
'
```

## Tokens originados en billeteras (Apple Pay y Google Pay)

Una CIT de billetera con `vault_on_success: true` también genera un `vaulted_token`: Apple Pay y Google Pay se descifran a un token de red de la tarjeta, por lo que el instrumento almacenado es un registro `CARD` con `parent_payment_method_type` establecido en el tipo de billetera.

> [!WARNING]
>
> **Guarda el token de la respuesta del pago**
>
> El `vaulted_token` se devuelve únicamente en la respuesta del pago CIT. Los instrumentos de billetera guardados en el vault intencionalmente no se incluyen en [Consultar métodos de pago inscritos](https://docs.y.uno/reference/payment-methods-direct-workflow/retrieve-enrolled-payment-methods-api.md): es normal que la lista `payment_methods` de un cliente que solo tiene billeteras esté vacía, aunque el token sea válido y se pueda cobrar. Conserva el `vaulted_token` (junto con los metadatos de visualización que necesites, como la marca y los últimos cuatro dígitos) de tu lado cuando la CIT sea exitosa. Un token almacenado todavía se puede consultar de forma individual con [Consultar método de pago inscrito por ID](https://docs.y.uno/reference/payment-methods-direct-workflow/retrieve-enrolled-payment-method-by-id-api.md).

El lugar donde va `stored_credentials` depende del paso. En el primer cobro, el método de pago sigue siendo la billetera, por lo que el objeto va en `detail.wallet`. Una vez que el instrumento se guarda en el vault, es un registro `CARD`, y los cobros posteriores con el `vaulted_token` usan `detail.card`, exactamente igual que con las tarjetas (PayPal es la excepción, consulta la nota más abajo):

| Paso | `payment_method.type` | Campo del token | Nodo `stored_credentials` | `reason` | `usage` |
| :- | :- | :- | :- | :- | :- |
| Primer cobro (se muestra la hoja de la billetera, el instrumento se guarda en el vault) | `APPLE_PAY` o `GOOGLE_PAY` | `token` (SDK) o `detail.wallet.payment_token` (directo) | `detail.wallet.stored_credentials` | `SUBSCRIPTION` | `FIRST` |
| Cobros posteriores de la misma serie recurrente (MIT) | `CARD` (el tipo de billetera también se acepta con un `vaulted_token`) | `vaulted_token` | `detail.card.stored_credentials` | `SUBSCRIPTION` | `USED` |
| Compra con un clic con el cliente presente sobre el token almacenado | `CARD` (el tipo de billetera también se acepta con un `vaulted_token`) | `vaulted_token` | `detail.card.stored_credentials` | `CARD_ON_FILE` | `USED` |

> [!WARNING]
>
> **No coloques `stored_credentials` en `detail.card` en una CIT de billetera**
>
> `detail.wallet` es el único nodo que Yuno garantiza leer en un pago con billetera. Un objeto colocado en `detail.card` en un primer pago con Apple Pay o Google Pay no se valida: puede llegar al proveedor, pero el flujo de SDK de dos pasos no lo transfiere al método de pago guardado, lo que deja el registro sin los indicadores de credenciales almacenadas y sin un `network_transaction_id`. Los cobros posteriores sobre ese registro se ejecutan entonces como compras simples en lugar de como una serie recurrente.

> [!NOTE]
>
> **PayPal es la excepción**
>
> Un instrumento guardado en el vault mediante `PAYPAL_ENROLLMENT` sigue siendo un registro de billetera, por lo que `stored_credentials` (incluido `subscription_agreement_id`) va en `detail.wallet` también en los cobros posteriores, no en `detail.card`.

Yuno adjunta automáticamente el `network_transaction_id` del pago con `usage: FIRST`, exactamente igual que con las tarjetas. Mantén `reason` coherente dentro de una serie. Consulta la nota "Crítico: completa todos los campos obligatorios" en [Crear un pago con tipo de procesamiento](#create-a-payment-with-processing-type). Encontrarás ejemplos completos de solicitud en las páginas de [Apple Pay SDK](https://docs.y.uno/docs/wallets/apple-pay/sdk-integration/recurring-payments.md#customer-initiated-transaction-cit), [Apple Pay directo](https://docs.y.uno/docs/wallets/apple-pay/apple-pay-direct-integration.md#recurring-payments-with-direct-api), [Google Pay SDK](https://docs.y.uno/docs/wallets/google-pay/sdk-integration/recurring-payments.md) y [Google Pay directo](https://docs.y.uno/docs/wallets/google-pay/google-pay-direct-integration.md#recurring-payments-cit-and-mit).

## Acuerdo de suscripción

En ciertos mercados (MX, por ejemplo) y con ciertos procesadores de pago, cuando se realiza un pago relacionado con una suscripción, es necesario especificar en la solicitud de pago el ID del acuerdo con el cliente para garantizar un procesamiento correcto. Para facilitarlo, Yuno habilitó el campo `subscription_agreement_id` dentro de la estructura `stored_credentials`, que te permite compartir el acuerdo establecido con el cliente.

> [!NOTE]
>
> **Nota**
>
> El `subscription_agreement_id` y el `network_transaction_id` son campos independientes. Incluir un `subscription_agreement_id` no sustituye la necesidad de un `network_transaction_id`. Ambos deben proporcionarse cuando corresponda para lograr tasas de aprobación óptimas y protección contra contracargos.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "subscription_agreement_id":"AA0001",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }
```

## ID de transacción de red

Un ID de transacción de red es un identificador único que la red de tarjetas asigna a una transacción. Se usa para rastrear y consultar transacciones específicas, en particular en escenarios de pagos recurrentes, y garantiza coherencia y trazabilidad a lo largo del ciclo de vida del pago.

Si la transacción es iniciada por el cliente (CIT), la referencia de transacción de red estará disponible en el campo `card.stored_credentials.network_transaction_id`. Este campo representa el ID de transacción en Visa y el trace ID en Mastercard, que se recomiendan para los pagos de suscripción futuros.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
"payment_method": {
        "type":"CARD",
        "vaulted_token": "eb8caa17-6407-457b-960e-125d8d7a90c1",
        "detail": {
           "card": {
               "stored_credentials":{
                  "reason":"CARD_ON_FILE",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189"
              }
           }
        }
    }
```

### Uso

Yuno asocia el `network_transaction_id` con el `vaulted_token` para transacciones futuras, de modo que no tengas que gestionar la lógica de cada caso. Yuno realiza la asociación cuando se crea un pago con:

* *Método de pago*:
  * Un `vaulted_token` de tarjeta, o
  * Datos de tarjeta con `vault_on_success` establecido en `true`
* *Credenciales almacenadas*:
  * `usage` establecido en `FIRST`

> [!WARNING]
>
> Al usar `vault_on_success = true` en una integración directa, debes crear primero el cliente y pasar su `customer_payer.id` en la solicitud de pago. Enviar los datos del cliente en línea no crea el cliente del lado de Yuno, por lo que la tarjeta no se puede almacenar y no se devolverá ningún `vaulted_token`.

Si ya tienes el `network_transaction_id` de la tarjeta, puedes incluirlo en el pago en el campo correspondiente. Si no, en los pagos MIT (con `stored_credentials.usage=USED`), Yuno envía al proveedor el `network_transaction_id` asociado con el `vaulted_token`.

> [!CAUTION]
>
> Recuerda especificar el `usage` en la sección `stored_credentials`, ya que Yuno activa la lógica del `network_transaction_id` según esos campos. Un objeto `stored_credentials` que incluye `reason` pero no `usage` se acepta, pero no se registra ningún `network_transaction_id` para ese pago.

## Pagos recurrentes entre proveedores

El `network_transaction_id` pertenece a la red de tarjetas, no al proveedor que procesó el primer pago. Yuno lo almacena en el `vaulted_token` y lo envía en cada pago iniciado por el comercio, sea cual sea el proveedor que seleccione tu enrutamiento. Esto es lo que hace que una tarjeta almacenada sea portable: una suscripción que comenzó con un proveedor puede cobrarse con otro sin pedirle al cliente que se autentique de nuevo.

Siempre envías los mismos campos (`usage`, `reason` y, opcionalmente, `network_transaction_id`); Yuno los traduce al formato de credenciales almacenadas y a los campos de referencia propios de cada proveedor. Por esto, puedes:

* Enrutar renovaciones, reintentos y alternativas de respaldo al proveedor con la mejor tasa de aprobación o el mejor costo. La [condición de enrutamiento](https://docs.y.uno/reference/organizations/routing/routing-conditions.md) `TRANSACTION_TYPE` distingue los pagos `CIT`, `MIT` y `RECURRING`, de modo que una ruta puede tratar de forma distinta los primeros cobros y los posteriores.
* Recuperar renovaciones fallidas con [Smart Retries](https://docs.y.uno/es/docs/payment-features/subscriptions/retries.md) cuando Yuno gestiona la suscripción, o con el endpoint [Reintentar suscripción](https://docs.y.uno/reference/subscriptions/retry-subscription.md). Si gestionas la facturación por tu cuenta, reintenta la MIT sobre el token del vault exactamente como lo cobrarías la primera vez.
* Mover una serie iniciada por el comercio entre proveedores durante una migración, porque la referencia de red viaja con el token y no con la conexión.

## ID de vínculo de transacción de Mastercard

En Mastercard, el ID de vínculo de transacción (TLID) es independiente del `network_transaction_id`, que lleva el trace ID de Mastercard. Mastercard exige el TLID en las transacciones iniciadas por el comercio, además del trace ID. La respuesta de pago de un pago iniciado por el cliente lo devuelve en `card.stored_credentials.transaction_link_id`.

Cómo lo reutilizas depende de dónde esté almacenada la tarjeta:

* **Tarjeta guardada en el vault de Yuno.** Yuno almacena el TLID devuelto en un pago exitoso enviado con `usage: FIRST` y lo reutiliza en los cobros `USED` posteriores sobre el mismo `vaulted_token`. Otro pago `FIRST` exitoso puede reemplazar el valor almacenado por el TLID que devuelva ese pago. Sigue enviando `usage` y `reason` como de costumbre; no necesitas enviar el TLID tú mismo.
* **Tarjeta almacenada en tu propio vault.** Conserva el `transaction_link_id` del primer pago junto con el `network_transaction_id`, y envía ambos en `stored_credentials` en cada pago con `usage: USED`. Si envías un `transaction_link_id` en un pago con un `vaulted_token`, el valor de la solicitud tiene prioridad sobre el almacenado.

```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
"payment_method": {
        "type":"CARD",
        "detail": {
           "card": {
               "card_data": { ... },
               "stored_credentials":{
                  "reason":"SUBSCRIPTION",
                  "usage": "USED",
                  "network_transaction_id":"583103536844189",
                  "transaction_link_id":"MCC1234567890123456789"
              }
           }
        }
    }
```

El reenvío del TLID depende de que el proveedor receptor lo admita. Contacta a tu TAM para confirmar que está habilitado en tu conexión.

> [!NOTE]
>
> La [regla de coherencia de `reason`](#create-a-payment-with-processing-type) sigue aplicándose cuando una serie pasa a otro proveedor: mantén el mismo `reason` que usaste en el primer pago, sea cual sea el proveedor que procese los posteriores.


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