Tokenización con compra en valor cero

Cuándo usarlaCopiar enlace

Úsala cuando el titular inscribe su tarjeta en tu plataforma, por ejemplo para garantizar una reserva o dejarla lista para cobros posteriores sin volver a pedirle los datos.

• Validación aprobada: el card_uuid queda habilitado para los cobros que acuerdes con el titular.
• Validación rechazada: la tarjeta no debe quedar registrada y debes pedir otro medio de pago.

Requisitos previosCopiar enlace

FlujoCopiar enlace

El flujo tiene un requisito y cuatro pasos en orden. Cada paso usa identificadores que devuelve uno anterior, así que no puedes ejecutarlos en paralelo ni saltarte ninguno.

Identificadores entre pasosCopiar enlace

Un mismo valor cambia de nombre según el paso: el id de la transacción es tran_id en el paso 2 e idtransaction en los pasos 3 y 4, y el terminal_id del paso 1 se envía como idterminal en el paso 3.

AutenticaciónCopiar enlace

Todas las llamadas van por HTTPS a la URL base del ambiente, desde tu servidor, con estos encabezados:

Si falta el encabezado o la apikey no existe, la API responde 403 con el mensaje El api_key enviando no existe. Revisa que uses la apikey del ambiente correcto. Los montos van en pesos colombianos y, en este flujo, siempre son 0.

Requisito: registrar al titularCopiar enlace

El titular debe existir antes del paso 1. Regístralo una sola vez con Crear persona y reutiliza su id en las transacciones siguientes. Los tipos de identificación válidos salen de Tipos de identificación.

{
  "firstname"           : "NOMBRE",
  "lastname"            : "APELLIDO",
  "ididentificationtype": "4",
  "identification"      : "<número de documento>",
  "email"               : "titular@correo.com",
  "phone"               : "<teléfono>"
}

El campo id de la respuesta es el idperson del paso 1.

Paso 1. Crear la transacciónCopiar enlace

Crea la transacción con amount en cero. Es el contenedor de todo el flujo: su id se usa en los tres pasos siguientes y en la consulta de estado.

{
  "terminal_id"   : "<terminal_id>",
  "form_id"       : "<form_id>",
  "amount"        : 0,
  "external_order": "VAL-000184",
  "ip"            : "181.50.10.20",
  "idperson"      : "43573"
}

Toma el campo id de la transacción: ese es el tran_id. La transacción nace en estado Creada (idstatus 1). Cuando la terminal tiene autenticación 3DS, el registro llega dentro de data, con type igual a Transaction.

Paso 2. Crear la ordenCopiar enlace

Crea la orden sobre la transacción del paso 1 y define el número de cuotas. La orden queda lista para ejecutarse en el paso 4.

{
  "tran_id"     : 15,
  "description" : "Validación de tarjeta para reserva",
  "installments": 1
}

La respuesta trae el identificador de la orden: guárdalo, es el order_uuid del paso 4. Si este paso falla, no sigas con la tokenización.

Paso 3. Tokenizar la tarjetaCopiar enlace

Envía los datos que el titular ingresó en tu formulario, junto con su autorización para el tratamiento de datos. Es el único paso en el que viajan el número de la tarjeta y el código de seguridad; desde aquí trabajas solo con el token.

{
  "idtransaction"    : 15,
  "idterminal"       : "<terminal_id>",
  "card_holder"      : "NOMBRE APELLIDO",
  "card_pan"         : "4111********1111",
  "card_expiry_year" : "<año>",
  "card_expiry_month": "<mes>",
  "card_cvv"         : "***",
  "autorizacionDatos": true
}

La respuesta trae el identificador de la tarjeta tokenizada: guárdalo, es el card_uuid del paso 4 y el dato con el que harás los cobros posteriores. Si incluye datos de presentación, como la marca o los últimos cuatro dígitos, puedes guardarlos para mostrarle al titular qué tarjeta registró.

Paso 4. Ejecutar en valor ceroCopiar enlace

Ejecuta la orden del paso 2 sobre la tarjeta del paso 3. Como la transacción vale cero, la red valida la tarjeta sin cobrarle al titular.

{
  "order_uuid"   : "<order_uuid del paso 2>",
  "card_uuid"    : "<card_uuid del paso 3>",
  "customer_ip"  : "181.50.10.20",
  "idtransaction": 15
}

Da por registrada la tarjeta solo cuando la transacción quede en Exitosa (idstatus 34), por la consulta de estado o por la notificación. Si queda Fallida (36) o Cancelada (38), no habilites el token y pide otra tarjeta.

Estado de la transacciónCopiar enlace

El estado está en el campo idstatus. Los estados finales son Exitosa, Fallida y Cancelada; mientras no llegue uno de ellos, trata la transacción como no resuelta.

Consulta del estadoCopiar enlace

curl --location '{{URL}}/ClientAPI/ObtenerTransaccion?id=15' \
--header 'Authorization: <APIKEY>'

El estado final puede no estar en la respuesta inmediata del paso 4, así que tu integración no debe depender solo de ella. Si el estado no es final, repite la consulta con espera creciente (a los 30 segundos, al minuto y luego cada pocos minutos) y detente cuando llegue un estado final.

Notificación por webhookCopiar enlace

Si tienes una URL de notificación registrada, PaymentsWay te envía el resultado con un POST. El formato y cómo responder están en WebHook. En este flujo:

• Busca la transacción por id o por externalorder y actualiza su estado solo si es final.
• Procesa cada notificación una sola vez; si llega repetida, ignórala.
• Ante cualquier duda, confirma con ObtenerTransaccion y quédate con lo que diga la consulta.

Manejo de erroresCopiar enlace

Los errores de validación indican el campo con problema:

{
  "status" : 400,
  "message": "Campos Incompletos",
  "item"   : null,
  "errors" : [
    {
      "item"         : "firstname",
      "previusValue" : "",
      "message"      : "El campo firstname es obligatorio y no puede estar vacío."
    }
  ]
}

Reintentos e interrupcionesCopiar enlace

1. Si el paso 1 se queda sin respuesta, no crees otra transacción a ciegas. Busca primero tu external_order y reutiliza la transacción si ya existe.

2. Si el paso 2 o el 3 fallan, no ejecutes el paso 4. Corrige la causa y reintenta; si la transacción ya quedó en un estado final, empieza de nuevo en el paso 1 con una referencia nueva.

3. Si el paso 4 se queda sin respuesta, no lo repitas de inmediato. Consulta la transacción y actúa según su estado.

4. Define tiempos de espera en tu cliente HTTP y registra en tus logs el external_order, el tran_id, el servicio y el código de respuesta. Nunca los datos de la tarjeta.

Seguridad de los datos de la tarjetaCopiar enlace

El número de la tarjeta (PAN) y el CVV solo viajan en el paso 3, por HTTPS con TLS, desde tu servidor hacia PaymentsWay.

• No guardes el PAN ni el CVV en bases de datos, archivos, colas, cachés ni copias de respaldo, ni siquiera de forma temporal o cifrada.
• No los registres en logs, trazas, herramientas de monitoreo ni mensajes de error. Para identificar la tarjeta usa el card_uuid o, como máximo, los últimos cuatro dígitos.
• Desactiva el registro de cuerpos de petición del servicio que llama a TokenizarTarjetaCliente, en tu aplicación y en balanceadores, proxies y herramientas de observabilidad.
• Guarda únicamente el card_uuid, asociado al titular.
• Mantén la apikey en un almacén de secretos, separada por ambiente, y nunca la expongas en el navegador ni en aplicaciones móviles.
• Usa TLS 1.2 o superior y valida el certificado del servidor en cada conexión.

AmbientesCopiar enlace

PaymentsWay entrega la URL base, la apikey, el terminal_id y el form_id de cada ambiente por canal seguro. No mezcles la apikey de pruebas con la URL de producción ni al revés, y parametriza estos valores fuera del código.

Lista de verificaciónCopiar enlace

Antes de pedir el paso a producción, confirma cada punto en el ambiente de pruebas: