Tokenización

Servicio para tokenizar tarjetas y generar un token que puede ser utilizado para transacciones futuras sin necesidad de almacenar los datos sensibles de la tarjeta.

Endpoint principal

Sandbox: POST https://api-test.payvalida.com/cards/tokens

Producción: POST https://api.payvalida.com/cards/tokens

Request

Request JSON

{
  "merchant": {
    "merchantId": "string",      // ID único del comercio
    "checksum": "string"         // Checksum de seguridad provisto por Payvalida (sha512 merchantid + fixed hash)
  },
  "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
  }
}

Especificación de los datos de entrada

Campo	Tipo	Requerido	Descripción
merchant.merchantId	string	Sí	ID único del comercio asignado por Payvalida
merchant.checksum	string	Sí	Checksum formado de la siguiente manera: SHA512(merchantid + fixed hash)
cardData.cardNumber	string	Sí	Número de la tarjeta de crédito (solo dígitos, sin espacios)
cardData.expirationMonth	string	Sí	Mes de expiración de la tarjeta (formato MM, por ejemplo "12")
cardData.expirationYear	string	Sí	Año de expiración de la tarjeta (formato YY, por ejemplo "25")
cardData.holderName	string	Sí	Nombre completo del titular de la tarjeta
cardData.franchise	string	Sí	Franquicia de la tarjeta: "visa", "mastercard" o "amex"

Ejemplo de Request

Ejemplo Request

{
  "merchant": {
    "merchantId": "merchantone",
    "checksum": "e54ee7e285fbb0275279143abc4c554e5314e7b417ecac83a5984a964facbaad68866a2841c3e83ddf125a2985566261c4014f9f960ec60253aebcda9513a9b4"
  },
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": "12",
    "expirationYear": "30",
    "holderName": "John Doe",
    "franchise": "visa"
  }
}

Response

Ejemplo de Response exitoso

Response 200

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

Ejemplo de Response de error

Response error

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

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

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.