Tokenizado

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.

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']`

POSThttps://sag.efipay.co/api/v1/tokenized

Token de accesoCuerpo de la petición

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"
}'

200OK

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

400Bad Request

{
    "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']`

POSThttps://sag.efipay.co/api/v1/tokenized/get

Token de accesoCuerpo de la petición

200OK

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

404Not Found 500Internal Server Error

{
    "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']`

DELETEhttps://sag.efipay.co/api/v1/tokenized

Token de accesoCuerpo de la petición

200OK

{
    "deleted": true
}

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
    }
}