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 estructurastored_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,reasonynetwork_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
reasonse mantenga coherente durante todo el ciclo de vida de la transacción. Si tu primera transacción (usage=FIRST) usareason=SUBSCRIPTION, todas las transacciones posteriores (usage=USED) también deben usarreason=SUBSCRIPTION.
Ejemplo de solicitud
Request (cURL)
Tokens originados en billeteras (Apple Pay y Google Pay)
Una CIT de billetera convault_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.
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):
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.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 camposubscription_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 campocard.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 elnetwork_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_tokende tarjeta, o - Datos de tarjeta con
vault_on_successestablecido entrue
- Un
- Credenciales almacenadas:
usageestablecido enFIRST
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
Elnetwork_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_TYPEdistingue los pagosCIT,MITyRECURRING, 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.
ID de vínculo de transacción de Mastercard
En Mastercard, el ID de vínculo de transacción (TLID) es independiente delnetwork_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: FIRSTy lo reutiliza en los cobrosUSEDposteriores sobre el mismovaulted_token. Otro pagoFIRSTexitoso puede reemplazar el valor almacenado por el TLID que devuelva ese pago. Sigue enviandousageyreasoncomo de costumbre; no necesitas enviar el TLID tú mismo. - Tarjeta almacenada en tu propio vault. Conserva el
transaction_link_iddel primer pago junto con elnetwork_transaction_id, y envía ambos enstored_credentialsen cada pago conusage: USED. Si envías untransaction_link_iden un pago con unvaulted_token, el valor de la solicitud tiene prioridad sobre el almacenado.
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.