# Tokenización

## Endpoint principal

{% hint style="success" %}
**Sandbox**: POST `https://api-test.payvalida.com/cards/tokens`
{% endhint %}

{% hint style="success" %}
**Producción**: POST `https://api.payvalida.com/cards/tokens`
{% endhint %}

## Request

<pre class="language-json" data-title="Request JSON"><code class="lang-json"><strong>{
</strong>  "merchant": {
    "merchantId": "string",      // ID único del comercio
    "checksum": "string"         // Checksum de seguridad provisto por Payvalida SHA512(merchantid + fixed hash + Unix timestamp)
  },
  "cardData": {
    "cardNumber": "string",      // Número de la tarjeta (solo dígitos)
    "expirationMonth": "string", // Mes de expiración (MM)
    "expirationYear": "string",  // Año de expiración (YY)
    "holderName": "string",      // Nombre completo del titular
    "franchise": "string",        // Franquicia: visa, mastercard, amex
    "cvv": "string"               // Código de seguridad.
  },
    "billingAddress": {
    "line1": "string",               // Línea 1 de la dirección del usuario.
    "line2": "string",              // Línea 2 de la dirección del usuario.
    "line3": "string",              // Línea 3 de la dirección del usuario.
    "addrCity": "string",          // Ciudad del usuario.
    "country": "string",          // País del usuario.
    "state": "string",            // Departamento del usuario.
    "postCode": "string",          // Código postal del usuario.
    "phoneNumber": "string",        // Número telefónico del usuario
    "email": "string",              // Correo electrónico del usuario.
  }
}
</code></pre>

## Especificación de los datos de entrada

<table data-full-width="true"><thead><tr><th width="243.1171875">Campo</th><th width="105.4453125">Tipo</th><th width="120.9140625">Requerido</th><th>Descripción</th></tr></thead><tbody><tr><td>merchant.merchantId</td><td>string</td><td>Sí</td><td>ID único del comercio asignado por Payvalida</td></tr><tr><td>merchant.checksum</td><td>string</td><td>Sí</td><td>Checksum formado de la siguiente manera: SHA512(merchantid + fixed hash)</td></tr><tr><td>cardData.cardNumber</td><td>string</td><td>Sí</td><td>Número de la tarjeta de crédito (solo dígitos, sin espacios)</td></tr><tr><td>cardData.expirationMonth</td><td>string</td><td>Sí</td><td>Mes de expiración de la tarjeta (formato MM, por ejemplo "12")</td></tr><tr><td>cardData.expirationYear</td><td>string</td><td>Sí</td><td>Año de expiración de la tarjeta (formato YY, por ejemplo "25")</td></tr><tr><td>cardData.holderName</td><td>string</td><td>Sí</td><td>Nombre completo del titular de la tarjeta</td></tr><tr><td>cardData.franchise</td><td>string</td><td>Sí</td><td>Franquicia de la tarjeta: "visa", "mastercard" o "amex"</td></tr><tr><td>cardData.cvv</td><td>string</td><td>Sí</td><td>Código de seguridad.</td></tr><tr><td>billingAddress.line1</td><td>string</td><td>No</td><td>Línea 1 de la dirección del usuario.</td></tr><tr><td>billingAddress.line2</td><td>string</td><td>No</td><td>Línea 2 de la dirección del usuario.</td></tr><tr><td>billingAddress.line3</td><td>string</td><td>No</td><td>Línea 3 de la dirección del usuario.</td></tr><tr><td>billingAddress.postCode</td><td>string</td><td>No</td><td>Código postal del usuario.</td></tr><tr><td>billingAddress.addrCity</td><td>string</td><td>No</td><td>Ciudad del usuario.</td></tr><tr><td>billingAddress.country</td><td>string</td><td>No</td><td>País del usuario.</td></tr><tr><td>billingAddress.state</td><td>string</td><td>No</td><td>Departamento del usuario.</td></tr><tr><td>billingAddress.phoneNumber</td><td>string</td><td>No</td><td>Número telefónico del usuario.</td></tr><tr><td>billingAddress.email</td><td>string</td><td>No</td><td>Correo electrónico del usuario.</td></tr></tbody></table>

{% hint style="warning" %}
Los campos de la estructura **billingAddress** no son obligatorios; sin embargo, se recomienda incluirlos, ya que su ausencia puede generar inconvenientes con el banco emisor durante el proceso de validación de la tarjeta. En caso de no proporcionarse, la solicitud será enviada utilizando datos simulados.
{% endhint %}

### Ejemplo de Request

{% code title="Ejemplo Request" %}

```json
{
  "merchant": {
    "merchantId": "merchantone",
    "checksum": "e54ee7e285fbb0275279143abc4c554e5314e7b417ecac83a5984a964facbaad68866a2841c3e83ddf125a2985566261c4014f9f960ec60253aebcda9513a9b4"
  },
  "cardData": {
    "cardNumber": "5303710409428783",
    "expirationMonth": "03",
    "expirationYear": "30",
    "holderName": "John Doe",
    "franchise": "mastercard",
    "cvv": "123"
  },
    "billingAddress": {
    "line1": "Cra 10 # 20-30",
    "line2": "Apto 107",
    "line3": "Plazoleta",
    "addrCity": "Bogotá",
    "country": "Colombia",
    "state": "Cundinamarca",
    "postCode": "110111",
    "phoneNumber": "3001234567",
    "email": "juan.perez@example.com"
  }
}
```

{% endcode %}

## Response

### Ejemplo de Response exitoso

{% code title="Response 200" %}

```json
{
  "code": "0000",
  "message": "Tokenización exitosa",
  "data": {
    "cardToken": "tok_abcdef123456" // token para futuras transacciones
  }
}
```

{% endcode %}

### Ejemplo de Response de error

{% code title="Response error" %}

```json
{
  "CODE": "0012",
  "DESC": "error authenticating merchant"
}
```

{% endcode %}

## Códigos de respuesta

* `0000`: OK
* `0010`: invalid request // formato de request inválido
* `0011`: invalid request // parámetros no cumplen con las validaciones
* `0012`: error authenticating merchant // error al autenticar el comercio
* `0013`: error tokenizing card // error al tokenizar la tarjeta

{% hint style="warning" %}
Notas de seguridad:

* Los datos sensibles deben ser enviados siempre sobre HTTPS.
* El token retornado puede ser almacenado y utilizado para operaciones futuras, evitando el almacenamiento de datos sensibles de la tarjeta.
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payvalida.com/api-tarjeta/master/crear-token/tokenizacion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.