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

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"
cardData.cvv	string	Sí	Código de seguridad.
billingAddress.line1	string	No	Línea 1 de la dirección del usuario.
billingAddress.line2	string	No	Línea 2 de la dirección del usuario.
billingAddress.line3	string	No	Línea 3 de la dirección del usuario.
billingAddress.postCode	string	No	Código postal del usuario.
billingAddress.addrCity	string	No	Ciudad del usuario.
billingAddress.country	string	No	País del usuario.
billingAddress.state	string	No	Departamento del usuario.
billingAddress.phoneNumber	string	No	Número telefónico del usuario.
billingAddress.email	string	No	Correo electrónico del usuario.

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.

Ejemplo de Request

Ejemplo Request

{
  "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": "[e-mail]"
  }
}

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.