Tokenización de tarjeta: guarda tarjetas para pagos futuros

La tokenización reemplaza un número de tarjeta sin cifrar por una referencia reutilizable — un token con el prefijo vt_ — que Therius almacena de forma segura en su bóveda. Una vez que una tarjeta está tokenizada, nunca necesitas volver a recopilar los datos de la tarjeta. Los tokens están limitados a tu cuenta de comercio, llevan metadatos de BIN (marca, tipo y emisor de la tarjeta) y funcionan en cualquier llamada futura de purchase o authorization exactamente igual que los datos de la tarjeta original.

Dos formas de tokenizar

1. Durante un pago

Agrega "tokenize": true dentro de card.cardData (o card.nonceData si usas el flujo de nonce del SDK de JS), e incluye un shopper.id para asociar el token con un cliente específico. El pago se procesa normalmente y la respuesta incluye el nuevo token.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": { "currency": "USD", "value": 2999, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "card": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "cardholderName": "Ada Lovelace",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "cvv": "123",
      "tokenize": true
    }
  }
}

La respuesta incluye un campo token junto a los campos normales del pago:

{
  "status": "captured",
  "paymentCode": "PAY-abc123",
  "token": {
    "id": "vt_4xK9mNpQ2rLsT7uV",
    "expirationDate": "2030-12-31",
    "tokenCreationReference": "PAY-abc123"
  }
}

Guarda token.id asociado al cliente en tu base de datos. Es lo único que necesitas para volver a cobrarle.

Tarjetas en pagos asíncronos

Una tarjeta se guarda solo cuando el pago se aprueba. Cuando el proveedor responde un pago con tarjeta con pending (4ON, por ejemplo), la respuesta aún no trae token: Therius conserva la tarjeta cifrada hasta que el pago se resuelve, y entonces la guarda, o la borra si el pago falla. Cuando la tarjeta se guarda recibes:

El webhook payment.captured (o payment.authorized), con data.token en la misma forma de arriba, cuando la tarjeta se guardó antes de enviarlo.
Un webhook token.created con data.token, data.payment_id y data.payment_code. Es el confiable: guarda el token desde ahí, porque el webhook del pago puede enviarse antes de que se guarde la tarjeta.

Consulta Eventos de tarjetas guardadas.

2. Creación de token independiente

Llama a POST /token para almacenar una o varias tarjetas como tokens sin realizar un pago. Es útil durante los flujos de configuración de cuenta donde quieres guardar una tarjeta en archivo antes de la primera compra.

{
  "merchantCode": "MERCHANT_001",
  "shopper": { "id": "shopper-42" },
  "card": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "cardholderName": "Ada Lovelace",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "cvv": "123"
    }
  }
}

La respuesta devuelve el mismo valor token (vt_...) sin procesar un cobro.

Usar un token en solicitudes futuras

Pasa card.tokenData.token en lugar de card.cardData en cualquier compra o autorización posterior. La estructura de la solicitud y la de la respuesta son idénticas a las de un pago normal.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-002",
  "amount": { "currency": "USD", "value": 2999, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "card": {
    "tokenData": {
      "token": "vt_4xK9mNpQ2rLsT7uV"
    }
  }
}

CVV en tarjetas tokenizadas

Opcionalmente puedes incluir card.tokenData.cvv al cobrar un token. Algunos adquirentes requieren el CVV para las transacciones iniciadas por el titular (CIT) pero no para las transacciones iniciadas por el comercio (MIT) ni para los cobros recurrentes.

{
  "card": {
    "tokenData": {
      "token": "vt_4xK9mNpQ2rLsT7uV",
      "cvv": "123"
    }
  }
}

Si estás ejecutando una suscripción o un reintento automatizado, omite el CVV — el cliente no está presente para proporcionarlo.

Tokenización de billetera

Los métodos de pago de Apple Pay y Google Pay también pueden guardarse para uso recurrente. Agrega "tokenize": true y un shopper.id dentro del objeto walletData.

{
  "shopper": { "id": "shopper-42" },
  "card": {
    "walletData": {
      "type": "apple_pay",
      "token": "<wallet payment token from device>",
      "tokenize": true
    }
  }
}

El token vt_... resultante se comporta de forma idéntica a un token de tarjeta en solicitudes futuras.

Tokenización de ACH

Los datos de cuenta bancaria enviados por ACH pueden tokenizarse de la misma forma. Agrega "tokenize": true dentro del objeto apm.

{
  "shopper": { "id": "shopper-42" },
  "apm": {
    "type": "ach",
    "accountNumber": "123456789",
    "routingNumber": "021000021",
    "tokenize": true
  }
}

La respuesta devuelve un token vt_... que puedes usar en cobros de ACH futuros sin volver a pedirle al cliente los datos de su cuenta bancaria.

Ciclo de vida del token

Un token puede estar active, deleted, erased o expired. Consúltalo en cualquier momento con GET /token/{token}.

Estado	Qué significa	¿Se puede cobrar?
`active`	La tarjeta está guardada y en uso.	Sí.
`deleted`	El cliente eliminó la tarjeta, un agente de soporte la eliminó, un guardado más reciente de la misma tarjeta la reemplazó, o Therius la retiró (ver abajo).	Sí, hasta que se borren los datos de la tarjeta. La respuesta incluye el encabezado `X-Therius-Token-Status: deleted`.
`erased`	Los datos de la tarjeta se borraron de forma permanente según la política de retención.	No.
`expired`	Venció la fecha de expiración del propio token.	No.

Cuándo se borran los datos de la tarjeta

Therius no conserva los datos de tarjeta para siempre. Los plazos de abajo son los valores predeterminados de la plataforma; erasesAt en el endpoint de estado siempre muestra la fecha que corresponde a un token.

Una tarjeta eliminada se borra 2 años después de la más reciente entre su eliminación, su último pago y el fin de la última suscripción que la usó. Si el token se vuelve a usar, esa fecha se mueve.
Una tarjeta que nadie eliminó se retira cuando venció hace más de 30 días, o cuando no se hizo ningún pago con ella durante 18 meses. Una tarjeta retirada pasa a deleted con deletedReason expired o unused, recibes token.deleted y sus datos se borran 30 días después.
Una tarjeta que una suscripción activa o un beneficiario de pagos todavía usa nunca se retira ni se borra.

Al borrar se eliminan el número de tarjeta cifrado, el token de red y los datos de cuenta bancaria, y se elimina la tarjeta en el proveedor de bóveda de tarjetas de Therius. La bandera, los últimos cuatro dígitos y el vencimiento se conservan, por lo que los pagos anteriores siguen mostrando “Visa ••••4242”. El token también se conserva, así que tus referencias a él nunca quedan colgando.

Cómo saber cuándo un token deja de funcionar

Webhooks: token.deleted cuando una tarjeta se elimina o se retira, token.erased cuando se borran sus datos, y subscription.payment_method_removed cuando un cliente elimina la tarjeta en la que se renueva una suscripción. Ver Eventos de webhook.
Errores: cobrar un token que ya no se puede cobrar devuelve 400 con un code sobre el que puedes ramificar tu lógica.

`code`	Significado	Qué hacer
`token_erased`	Se borraron los datos de la tarjeta.	Pide al cliente una tarjeta nueva.
`token_expired`	Venció la fecha de expiración del token.	Pide al cliente una tarjeta nueva.
`token_not_found`	No existe ese token en tu cuenta de comercio.	Revisa el valor que guardaste.

Una suscripción sigue cobrando su tarjeta después de que el cliente la elimina de sus tarjetas guardadas, hasta que reemplaces el método de pago con Actualizar método de pago. Usa subscription.payment_method_removed para pedirle una tarjeta nueva al cliente a tiempo.

Seguridad

Los tokens de Therius son seguros para PCI. Un token vt_... solo es utilizable dentro de la bóveda de Therius y solo por tu cuenta de comercio. No puede usarse para recuperar el número de tarjeta sin cifrar, y ningún sistema de pago externo lo acepta. Almacenar tokens en lugar de datos de tarjeta significa que tu base de datos queda fuera del alcance de los requisitos de PCI DSS relacionados con los PAN.

Primeros pasos

Conceptos básicos

Guías

Webhooks

Asistente de IA

Plugins de e-commerce

Tokenización de tarjeta: guarda tarjetas para pagos futuros

Dos formas de tokenizar

1. Durante un pago

Tarjetas en pagos asíncronos

2. Creación de token independiente

Usar un token en solicitudes futuras

CVV en tarjetas tokenizadas

Tokenización de billetera

Tokenización de ACH

Ciclo de vida del token

Cuándo se borran los datos de la tarjeta

Cómo saber cuándo un token deja de funcionar

Seguridad

​Dos formas de tokenizar

​1. Durante un pago

​Tarjetas en pagos asíncronos

​2. Creación de token independiente

​Usar un token en solicitudes futuras

​CVV en tarjetas tokenizadas

​Tokenización de billetera

​Tokenización de ACH

​Ciclo de vida del token

​Cuándo se borran los datos de la tarjeta

​Cómo saber cuándo un token deja de funcionar

​Seguridad

Dos formas de tokenizar

1. Durante un pago

Tarjetas en pagos asíncronos

2. Creación de token independiente

Usar un token en solicitudes futuras

CVV en tarjetas tokenizadas

Tokenización de billetera

Tokenización de ACH

Ciclo de vida del token

Cuándo se borran los datos de la tarjeta

Cómo saber cuándo un token deja de funcionar

Seguridad