Saltar al contenido principal
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.
Importante: esto no es lo mismo que las suscripcionesPiensa 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.
  • 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

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 con un tipo de procesamiento, usa la estructura stored_credentials dentro de payment_method.detail.card al crear un pago.
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

Ejemplo de solicitud

Request (cURL)

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.
Guarda el token de la respuesta del pagoEl 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: 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.
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):
No coloques stored_credentials en detail.card en una CIT de billeteradetail.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.
PayPal es la excepciónUn 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. Encontrarás ejemplos completos de solicitud en las páginas de Apple Pay SDK, Apple Pay directo, Google Pay SDK y Google Pay directo.

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

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.

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
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.
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 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 cuando Yuno gestiona la suscripción, o con el endpoint Reintentar suscripción. 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.
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.
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.
La regla de coherencia de reason 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.