Tokenizado

¿Para qué sirve tokenizar?

Tokenizar convierte los datos de una tarjeta en un token que puedes guardar y reutilizar. Sirve para que tu cliente no tenga que volver a escribir su tarjeta en cada compra: guardas el token una vez y en los siguientes cobros envías solo eso.

Casos típicos: un botón de «pagar con la tarjeta guardada», un carrito con compra en un clic, o cobros recurrentes que tú disparas.

Lo importante de este endpoint es lo que evita. El número de tarjeta y el CVV viajan una sola vez, en la llamada que crea el token. De ahí en adelante manejas un token, no una tarjeta, y eso reduce drásticamente el alcance PCI de tu sistema.

{danger} El token se devuelve una sola vez y no lo guardamos por ti. Guárdalo tú asociado a tu cliente. Si lo pierdes, hay que volver a pedirle la tarjeta.

{warning} El token es de tu comercio: no funciona en otro, ni en el otro ambiente (prueba / producción).

Guardar una tarjeta

POST /api/v1/tokenized

Descripción: Recibe los datos de la tarjeta y devuelve el token. Cuando la franquicia lo permite se usa un network token de la red; si no, guardamos la tarjeta cifrada de nuestro lado. En los dos casos tú manejas el mismo campo token.

Nombre del campo Descripción Reglas
holder Nombre impreso en la tarjeta. No puede ser un número de tarjeta ['required', 'string', 'max:80']
number Número de la tarjeta, sin espacios ni guiones ['required', 'numeric', 'digits_between:14,16']
datetime Vencimiento en formato YYYY-MM, con mes entre 01 y 12. No puede estar vencida ['required', 'string', 'after_or_equal:<mes actual>']
cvv Código de seguridad del reverso, de 3 o 4 dígitos ['required', 'digits_between:3,4'] 
curl -X POST \
'/api/v1/tokenized' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "holder": "Ana Gomez",
    "number": "5249314023340339",
    "datetime": "2029-05",
    "cvv": "478"
}'

{success} Respuesta satisfactoria code: 200

{
"saved": true,
"token": "eyJpdiI6IlRxV0Z...la-cadena-completa-es-larga",
"card": {
"number_card": "524931******0339",
"franchise": "Mastercard"
}
}

{info} Según el camino que se use, card trae number_card (network token) o number_label (tarjeta cifrada por nosotros). Los dos son la tarjeta enmascarada; lee el que venga.

{danger} La red rechazó la tarjeta code: 400

{
"message": "Transacción declinada. Comuníquese con su banco"
}

Consultar una tarjeta guardada

POST /api/v1/tokenized/get

Descripción: A partir del token, devuelve la tarjeta enmascarada y su franquicia. Sirve para mostrarle a tu cliente cuál tarjeta tiene guardada. Nunca devuelve el número completo ni el CVV.

Nombre del campo Descripción Reglas
token El token que te devolvió «Guardar una tarjeta» ['required', 'string']

{success} Respuesta satisfactoria code: 200

{
"number_card": "524931******0339",
"franchise": "Mastercard"
}

{danger} El token es válido pero la tarjeta ya no existe code: 404

{danger} El token no se pudo descifrar: viene alterado, o es de otro comercio o de otro ambiente code: 500

{
"message": "Invalid token"
}

Eliminar una tarjeta guardada

DELETE /api/v1/tokenized

Descripción: Borra la tarjeta asociada al token. Úsalo cuando tu cliente quite su método de pago.

Nombre del campo Descripción Reglas
token El token de la tarjeta a eliminar ['required', 'string']

{success} Respuesta satisfactoria code: 200

{
"deleted": true
}

{info} También responde deleted: true si el token era válido pero la tarjeta ya no estaba: el resultado que pediste —que no exista— se cumple igual.

Cobrar con una tarjeta guardada

En el checkout por API envía el token en payment_card.token en lugar de los datos de la tarjeta:

{
    "payment": { "id": "...", "token": "..." },
    "payment_card": {
        "token": "el-token-que-guardaste",
        "installments": 1
    }
}

{warning} payment_card.token es excluyente con number, name, expiration_date y cvv. Envía el token o los datos de la tarjeta, nunca los dos: la validación rechaza la petición.

{info} No lo confundas con payment.token, que es el token del cobro y siempre va. Son dos cosas distintas en la misma petición.

{warning} Una reserva de cupo no acepta tarjeta tokenizada: la red exige CVV y un token no lo incluye.