# Tokenizado

<!-- Fuente: https://docs.efipay.co/tokenized -->

---

- [Tokenizado](#tokenizado)
  - [¿Para qué sirve tokenizar?](#overview)
  - [Guardar una tarjeta](#create)
  - [Consultar una tarjeta guardada](#get)
  - [Eliminar una tarjeta guardada](#delete)
  - [Cobrar con una tarjeta guardada](#cobrar)

## ¿Para qué sirve tokenizar? [#overview]

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

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

## Guardar una tarjeta [#create]

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

`POST /api/v1/tokenized`

Cuerpo de ejemplo:

```json
{
    "holder": "Ana Gomez",
    "number": "5249314023340339",
    "datetime": "2029-05",
    "cvv": "478"
  }
```

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

:::tip
Respuesta satisfactoria
:::

Código de respuesta: 200

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

:::note
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
:::

Código de respuesta: 400

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

## Consultar una tarjeta guardada [#get]

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

`POST /api/v1/tokenized/get`

Cuerpo de ejemplo:

```json
{
    "token": "el-token-que-guardaste"
  }
```

:::tip
Respuesta satisfactoria
:::

Código de respuesta: 200

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

:::danger
El token es válido pero la tarjeta ya no existe
:::

Código de respuesta: 404

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

Código de respuesta: 500

```json
{
    "message": "Invalid token"
}
```

## Eliminar una tarjeta guardada [#delete]

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

`DELETE /api/v1/tokenized`

Cuerpo de ejemplo:

```json
{
    "token": "el-token-que-guardaste"
  }
```

:::tip
Respuesta satisfactoria
:::

Código de respuesta: 200

```json
{
    "deleted": true
}
```

:::note
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 [#cobrar]

En el [checkout por API](/checkout-transaction) envía el token en
`payment_card.token` en lugar de los datos de la tarjeta:

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

:::caution
`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.
:::

:::note
No lo confundas con `payment.token`, que es el token del **cobro** y siempre va.
Son dos cosas distintas en la misma petición.
:::

:::caution
Una [reserva de cupo](/mit-pre-authorization) **no**
acepta tarjeta tokenizada: la red exige CVV y un token no lo incluye.
:::