Bienvenido a Merchant

PaymentsWay Merchant es la plataforma completa para integrar cobros en tu negocio. Desde aquí puedes configurar tus métodos de pago, conectar tu tienda online y gestionar todas tus transacciones desde un solo lugar.

¿Qué puedes hacer en Merchant?

¿Por dónde empezar?

1. Regístrate y obtén tus credenciales de acceso — ver Registro.
2. Elige tu método de integración: plugin, widget, botón HTML o API REST — ver Modos de integración.
3. Configura los métodos de pago que quieres ofrecer: tarjeta, PSE, efectivo o QR.
4. Activa tu webhook para recibir confirmaciones en tiempo real — ver WebHook.
5. Realiza una prueba de extremo a extremo con un monto mínimo antes de salir a producción.

Registro

Para usar PaymentsWay necesitas registrarte y obtener tus credenciales. El proceso toma entre 5 y 10 minutos dependiendo del tipo de cuenta.

Acceso a la consola

Una vez aprobado tu registro, accedes a la consola con las credenciales enviadas a tu correo:

Tipo de registro

Selecciona el perfil que se ajusta a tu situación:

Modos de Integración

PaymentsWay ofrece tres modalidades de integración. Elige la que mejor se adapte a tu stack tecnológico y nivel de personalización requerido.

Widget de pagos

La integración más rápida. Con pocas líneas de código embeds el checkout directamente en tu página — el cliente paga sin salir de tu sitio.

Web Checkout

Un formulario HTML estándar que redirige al cliente al checkout seguro de PaymentsWay. Ideal si no quieres gestionar el flujo de pago en tu servidor.

Plugins para CMS

Si usas WooCommerce, PrestaShop o Magento, instala el plugin y configura tus credenciales. Sin código.

Botones de pago

Los botones de pago son la unidad central de configuración en PaymentsWay. Cada botón define el tipo de cobro, los métodos habilitados y el entorno (test o producción).

Crear un botón

1. Ingresa a la consola con tu usuario y contraseña.
2. Navega al módulo Botones de pago.
3. Haz clic en Crear botón de pago y completa el formulario.

Tipos disponibles

Links de pago

Un link de pago es una URL que puedes generar desde la consola de PaymentsWay o vía API y compartir por cualquier canal digital. El cliente hace clic, ingresa sus datos de pago y listo — sin que tengas que instalar nada en tu sitio web.

¿Cómo funciona?

Links masivos

Genera links para múltiples clientes a la vez cargando una plantilla de Excel. Ideal para facturación por lotes, cobros de cuotas o pagos periódicos a muchos clientes al mismo tiempo.

Link individual

Crea un link para un cliente específico con sus datos prellenados o genérico sin datos. Sobre cada link generado tienes tres acciones disponibles:

• Ver — Abre el checkout en el navegador para previsualizar.
• Copiar — Copia el link recortado al portapapeles.
• Compartir — Envía el link por SMS directamente al número del cliente.

Link con monto dinámico

En Links de pago express activa la opción "¿Va a ser un monto fijo? → No" para que sea el cliente quien seleccione o ingrese el monto antes de pagar. Útil para donaciones, propinas o cobros variables.

Botón de Pago

El botón de pago es un formulario HTML que envías desde tu servidor hacia el checkout de PaymentsWay con los datos de la compra ya precargados. El cliente llega al checkout listo para pagar — tú controlas los datos, PaymentsWay gestiona el cobro.

¿Cómo funciona?

Código base

<form method="Post" action="https://merchant.paymentsway.co/cartaspago/redirect">
  <input name="merchant_id"      type="hidden" value="0">
  <input name="form_id"          type="hidden" value="0">
  <input name="terminal_id"      type="hidden" value="0">
  <input name="order_number"     type="hidden" value="0">
  <input name="amount"           type="hidden" value="0">
  <input name="currency"         type="hidden" value="COP">
  <input name="order_description" type="hidden" value="Test de compra">
  <input name="client_email"     type="hidden" value="user@example.com">
  <input name="client_phone"     type="hidden" value="3000000000">
  <input name="client_firstname" type="hidden" value="Juan">
  <input name="client_lastname"  type="hidden" value="Pérez">
  <input name="client_doctype"  type="hidden" value="4">
  <input name="client_numdoc"   type="hidden" value="1234567890">
  <input name="response_url"    type="hidden" value="https://tu-sitio.com/respuesta">
  <input name="Submit"          type="submit"  value="Pagar">
</form>

Parámetros

Botón de Pago Abierto

El botón de pago abierto es una variación del botón estándar donde el cliente elige cuánto pagar. Tú defines un rango de montos y él decide. Ideal para donaciones, recargas, propinas o cualquier cobro donde el precio no es fijo.

¿Cómo funciona?

Código base

<form method="post" action="https://merchant.paymentsway.co/cartaspago/redirect">
  <input name="type_method" type="hidden" value="2">
  <input name="currency"    type="hidden" value="COP">
  <input name="amount_1"    type="hidden" value="10000">
  <input name="amount_2"    type="hidden" value="20000">
  <input name="amount_3"    type="hidden" value="30000">
  <input name="amount_4"    type="hidden" value="40000">
  <input name="min_amount"  type="hidden" value="10000">
  <input name="max_amount"  type="hidden" value="40000">
  <input name="Submit"      type="submit"  value="Pagar">
</form>

Implementación del Widget

El widget de PaymentsWay es un checkout embebido que se abre directamente dentro de tu página — el cliente paga sin salir de tu sitio. A diferencia del botón de pago, no hay redirecciones: el formulario aparece sobre tu propio sitio como una capa flotante.

Widget vs Botón de Pago

1 — Hoja de estilos

<link rel="stylesheet"
      href="https://merchant.paymentsway.co/assetsWidget/css/index.css" />

2 — Script (final del body)

<script src="https://merchant.paymentsway.co/assetsWidget/js/index.js"></script>

3 — Inicializar

const checkout = new widgetCheckout({
  merchant_id      : 'tu-merchant-id',
  form_id          : 'tu-form-id',
  terminal_id      : 'tu-terminal-id',
  order_number     : generateOrderNumber(7),
  amount           : '50000',
  currency         : 'COP',
  order_description: 'Compra en mi tienda',
  apikey           : 'tu-api-key',
  ip               : '0.0.0.0',
});

// Actualizar monto dinámicamente
checkout.updateAmount(75000);

Parámetros

Modo de Uso

Esta sección describe la experiencia que vive el cliente al usar el widget — desde que hace clic en "Pagar" hasta que recibe la confirmación, sin salir de tu sitio web en ningún momento.

Flujo de pago

1. El cliente hace clic en el botón de pago generado por el widget.
2. Selecciona el método: Tarjeta, PSE o Efectivo.
3. Completa sus datos y confirma el pago.
4. Recibe confirmación en pantalla y tu servidor recibe el webhook.

Cartas de Pago

Las cartas de pago son formularios de cobro embebibles con el branding de tu marca. Se insertan en cualquier página web como un iframe — el cliente paga sin salir de tu sitio y sin ver ninguna pantalla de PaymentsWay. Ideal para páginas de donación, suscripciones o cobros recurrentes con imagen propia.

¿Cuándo usar cartas vs widget?

Crear una carta

1. Crea una terminal y ve al módulo Botones de pago.
2. Selecciona Crear Botón de pago.
3. Elige el tipo Carta de pago y completa el formulario.

Insertar la carta

Una vez creada, desde el listado haz clic en la carta para abrir el modal. Dispondrás de dos opciones:

• Copiar embebido — Código HTML listo para pegar en tu sitio.
• Copiar URL — Link directo a la carta de pago.

WooCommerce

WooCommerce es el plugin de comercio electrónico más usado del mundo, construido sobre WordPress. Con el plugin nativo de PaymentsWay puedes aceptar pagos con tarjeta y PSE en tu tienda en minutos — sin escribir una sola línea de código.

Flujo de instalación

Requisitos previos

Ten a mano las credenciales entregadas por PaymentsWay antes de empezar:

Instalación paso a paso

1. Ve a WordPress → Plugins → Añadir nuevo → Subir plugin, selecciona el archivo plugin-payments.zip y haz clic en Instalar ahora.
2. Una vez instalado haz clic en Activar plugin.
3. Ve a WooCommerce → Ajustes → Pagos y activa el interruptor de PaymentsWay.
4. Haz clic en Configurar e ingresa los datos de tu cuenta: ID MERCHANT, ID TERMINAL, ID BOTÓN DE PAGO y APIKEY.
5. En el campo URL de retorno pega la URL de la página principal de tu tienda.
6. Haz clic en Guardar cambios.

PrestaShop

PrestaShop es una plataforma de comercio electrónico de código abierto ampliamente usada en Colombia y Latinoamérica. El módulo nativo de PaymentsWay se instala directamente desde el panel de administración — sin modificar código ni plantillas.

Flujo de instalación

Requisitos previos

Credenciales necesarias, entregadas por el equipo de PaymentsWay:

Paso 1 — Instalación

1. Ve a Módulos → Administrador de Módulos → Subir un módulo.
2. Selecciona el archivo pwmerchant.zip y espera que la instalación se complete.

Paso 2 — Configuración

1. En el listado de módulos localiza PaymentsWay y haz clic en Configurar.
2. Ingresa tus credenciales: merchant_id, terminal_id, form_id, apikey.
3. Guarda los cambios.

Paso 3 — Preferencias de pago

1. Ve a Pagos → Preferencias.
2. Configura restricciones por moneda (COP, USD, EUR), grupos de clientes y países según tu operación.
3. Guarda los cambios.

Magento

Magento (Adobe Commerce) es la plataforma de comercio electrónico empresarial preferida por negocios de mediano y gran tamaño. La extensión de PaymentsWay para Magento 2 se instala vía cPanel sin necesidad de Composer ni acceso por SSH.

Flujo de instalación

Requisitos previos

Credenciales necesarias, entregadas por el equipo de PaymentsWay:

Paso 1 — Instalación vía cPanel

1. Accede a tu cPanel y abre el Administrador de archivos.
2. Navega a la carpeta raíz de tu instalación de Magento y luego abre la carpeta app/.
3. Sube el archivo plugin-magento-paymentsway.zip y descomprímelo. Se creará la carpeta code/ con la extensión.

Paso 2 — Configuración en el panel de Magento

1. Accede al panel de administración de Magento.
2. Ve a Stores → Configuration → Sales → Payments Way Configuration.
3. Ingresa tus datos: Terminal ID, Form ID, Merchant ID, API Key y Response URL.
4. Haz clic en Save Config.
5. Ve a System → Cache Management y limpia el caché completo.

VTEX

VTEX es la plataforma de comercio digital líder en Latinoamérica, utilizada por grandes marcas y retailers para gestionar sus tiendas en línea con alto volumen de transacciones. Con el conector nativo de PaymentsWay puedes activar Visa, Mastercard y PSE en tu tienda VTEX en tres pasos simples — sin desarrollo, sin código, en menos de 15 minutos.

Flujo de integración

El diagrama muestra los tres pasos de configuración (que se hacen una sola vez) y el flujo de cada pago desde el checkout de VTEX hasta la confirmación:

Requisitos previos

Antes de iniciar ten a mano los siguientes datos — los entrega el equipo de PaymentsWay:

Paso 1 — Generar App Key y App Token en VTEX

El App Key y App Token son las credenciales que permiten al conector de PaymentsWay comunicarse de forma segura con tu tienda VTEX. Se generan una sola vez.

1. Inicia sesión en el admin de tu tienda VTEX: https://{su-cuenta}.myvtex.com/admin
2. Haz clic en el avatar de usuario (esquina superior derecha) y selecciona "Account Settings".
3. Haz clic en "API Keys" y luego en "+ New API Key" (o "Generate Key").
4. Asigna el nombre "PaymentsWay-Produccion" y el rol "Owner" (o mínimo "FinancePayments").
5. Haz clic en "Generate". VTEX te mostrará el App Key y un link para obtener el App Token — copia ambos de inmediato.

Paso 2 — Crear el proveedor de pago PaymentsWay

1. En el menú lateral ve a Store Settings → Payment → Providers.
2. Haz clic en "New Provider", escribe "PaymentsWay" en el buscador y selecciónalo.
3. Completa el formulario con los valores de la siguiente tabla.
4. Haz clic en "Guardar". El proveedor aparecerá como "Production".

Paso 3 — Configurar métodos de pago

Repite este proceso una vez por cada método: Visa, Mastercard y PSE.

1. Haz clic en el botón verde "+" para agregar una nueva condición.
2. Busca y selecciona el método de pago: Visa.
3. En el campo Provider selecciona "PaymentsWay".
4. Asigna el nombre "PaymentsWay Visa".
5. Cuotas: deja "En una cuota" o configura según tu necesidad.
6. Haz clic en "Guardar". Repite para Mastercard y PSE.

Al terminar la sección Payment Conditions debe mostrar:

Datos de referencia del conector

Verificación final

Soporte

Crear link con redirección

Genera un link de pago desde tu backend. El cliente es redirigido automáticamente al checkout al acceder al link.

Parámetros

Ejemplo de petición

const response = await fetch("https://merchant.paymentsway.co/link-de-pago/create", {
  method : 'POST',
  headers: {
    "Authorization": "TU_API_KEY",
    "Content-Type" : "application/json"
  },
  body: JSON.stringify({
    "merchant_id"      : 7890,
    "form_id"          : "",
    "terminal_id"      : "",
    "order_number"     : "ORD-456789",
    "amount"           : 55000,
    "currency"         : "COP",
    "order_description": "Compra de productos",
    "client_email"     : "cliente@example.com",
    "response_url"     : "https://example.com/gracias",
  })
});

const data = await response.json();
console.log(data);

Errores

{ "error": true, "data": "" }

Crear link de pago

Genera un link de pago sin redirección automática. El cliente accede manualmente al link.

Checksum

El checksum garantiza la integridad de los datos enviados entre tu servidor y PaymentsWay. Se genera con SHA-256.

¿Cómo se genera?

Se concatenan los siguientes campos separados por ; y se aplica SHA-256:

"{idForm};{apikey};{idMerchant};{amount};{externalOrder}"

Ejemplo

import { sha256 } from 'crypto-js';

const createChecksum = (idForm, idMerchant, apikey, amount, externalOrder) =>
  sha256(`${idForm};${apikey};${idMerchant};${amount};${externalOrder}`)
    .toString();

// Uso:
const checksum = createChecksum('123', '456', 'mi-api-key', '50000', 'ORD-001');

Obtener Tipos de Identificación

Retorna el catálogo completo de tipos de documento válidos en el sistema. Usa estos IDs en todos los endpoints que requieran identification_type o client_doctype.

Headers

Envía tu Api_key en el header Authorization.

Tipos disponibles

Ejemplo de petición

const headers = new Headers();
headers.append("Authorization", "TU_API_KEY");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/ObtenerTiposIdentificacion",
  { method: 'GET', headers, redirect: 'follow' }
);
const tipos = await res.json();
console.log(tipos);

Obtener Tipos de Estados

Retorna todos los estados de transacción disponibles en el sistema con sus IDs. Usa estos valores para interpretar el campo idstatus del webhook.

const headers = new Headers();
headers.append("Authorization", "TU_API_KEY");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/GetAllTransactionStatuses",
  { method: 'GET', headers, redirect: 'follow' }
);
const estados = await res.json();
console.log(estados);

Crear Persona

Registra un cliente en el sistema de PaymentsWay. El ID retornado se usa para tokenizar tarjetas.

Parámetros

const res = await fetch("https://serviceregister.paymentsway.co/ClientAPI/CrearPersona", {
  method : 'POST',
  headers: { "x-api-key": "TU_API_KEY", "Content-Type": "application/json" },
  body   : JSON.stringify({
    firstname: "Juan", lastname: "Pérez",
    ididentificationtype: "4", identification: "10000000",
    email: "juan@email.com", phone: "3000000000"
  })
});
const { id } = await res.json(); // usa este id para tokenizar

Obtener Transacción

Consulta el estado y detalle completo de una transacción usando su referencia externa (order_number o external_order).

Headers

Envía tu Api_key en el header Authorization.

Query params

Ejemplo de petición

const externalOrder = "ORD-456789";

const headers = new Headers();
headers.append("Authorization", "TU_API_KEY");

const res = await fetch(
  `https://serviceregister.paymentsway.co/ClientAPI/ObtenerTransaccionByExternalOrder?external_order=${externalOrder}`,
  { method: 'GET', headers, redirect: 'follow' }
);
const transaccion = await res.json();
console.log(transaccion);

Obtener Persona Por Documento

Busca un cliente ya registrado en el sistema usando su número de documento. Útil para verificar si un usuario ya existe antes de crearlo.

Headers

Envía tu Api_key en el header x-api-key.

Cuerpo de la petición

{ "nroDocumento": 1012427594 }

Ejemplo de petición

const headers = new Headers();
headers.append("x-api-key", "TU_API_KEY");
headers.append("Content-Type", "application/json");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/ObtenerPersonaPorDocumento",
  {
    method: 'POST',
    headers,
    body: JSON.stringify({ "nroDocumento": 1012427594 }),
    redirect: 'follow'
  }
);
const persona = await res.json();
console.log(persona);

Crear Transacción Tarjeta de Crédito

Procesa un pago directo con tarjeta de crédito o débito. Requiere certificación PCI DSS. Usa los datos reales de la tarjeta del cliente para ejecutar el cobro.

Headers

Envía tu Api_key en el header x-api-key.

Parámetros

Cuerpo de ejemplo

{
  "amount"           : 300000,
  "firstname"        : "Pepito",
  "lastname"         : "Perez",
  "card_identification": "1012345678",
  "identification_type": 4,
  "card_holder"      : "PEPITO PEREZ PA",
  "card_pan"         : "4111111111111111",
  "card_expiry_year" : "26",
  "card_expiry_month": "06",
  "card_cvv"         : "123",
  "url_ok"           : "https://tu-sitio.com/pago-exitoso",
  "url_ko"           : "https://tu-sitio.com/pago-fallido",
  "description"      : "Compra en mi tienda",
  "installments"     : 1,
  "external_order"   : "trc231566",
  "dynamic_descriptor": "Mi Tienda Online",
  "terminal_id"      : 34,
  "form_id"          : 34,
  "ip"               : "192.168.0.1",
  "additionalData"   : { "ref": "mi-referencia" },
  "autorizacionDatos": true
}

Ejemplo de petición

const headers = new Headers();
headers.append("x-api-key", "TU_API_KEY");
headers.append("Content-Type", "application/json");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/CrearTransaccionTC",
  { method: 'POST', headers, body: JSON.stringify(body), redirect: 'follow' }
);
const resultado = await res.json();

// Si hay url_3ds, redirige para autenticación 3D Secure
if (resultado.url_3ds) {
  window.location.href = resultado.url_3ds;
}

Reversar Transacción

Anula una transacción aprobada y devuelve el cobro al cliente. El idTransaction es el identificador interno de PaymentsWay, retornado en la respuesta de Crear Transacción Tarjeta de Crédito.

Headers

Envía tu Api_key en el header Authorization.

Cuerpo de la petición

{ "idTransaction": 1360 }

Ejemplo de petición

const headers = new Headers();
headers.append("Authorization", "TU_API_KEY");
headers.append("Content-Type", "application/json");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/ReversarTransaccion",
  {
    method: 'POST',
    headers,
    body: JSON.stringify({ "idTransaction": 1360 }),
    redirect: 'follow'
  }
);
const resultado = await res.json();
console.log(resultado);

Tokenizar Tarjetas

Permite tokenizar una tarjeta de crédito para cobros recurrentes sin que el cliente tenga que ingresarla nuevamente.

Flujo

1. Crea una persona — obtienes un idperson.
2. Llama a TokenizarDatosPersona con el idperson y datos de la tarjeta.
3. Recibes un token. Muestra el embed en tu página para que el cliente complete el proceso.

{
  "documento"          : "10000000",
  "identification_type": 4,
  "idperson"           : 8,
  "url"                : "https://tu-sitio.com",
  "form_id"            : 368,
  "amount"             : "100",
  "external_order"     : "Test_02",
  "ip"                 : "127.0.0.1",
  "currencycode"       : "COP",
  "description"        : "Descripción",
  "installments"       : 1
}

Embed de tokenización

<embed id="embed" width="500px" height="320px"></embed>
<script defer>
  const token = 'token-recibido';
  document.getElementById('embed').src =
    `https://merchant.paymentsway.co/tokenizacion/?p=${token}`;
</script>

Estados de transacción aprobada

Códigos de respuesta cuando una transacción es autorizada exitosamente.

Estados de transacción rechazada

Códigos de respuesta cuando una transacción es negada por el sistema o el banco emisor.

Obtener Listado de Bancos

Retorna el catálogo de bancos habilitados para transacciones PSE. Los campos CodigoBanco y NombreBanco retornados aquí se usan directamente en el endpoint Crear Transacción PSE.

Headers

Envía tu Api_key en el header Authorization.

Ejemplo de petición

const headers = new Headers();
headers.append("Authorization", "TU_API_KEY");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/ObtenerListadoBancos",
  { method: 'GET', headers, redirect: 'follow' }
);
const bancos = await res.json();
console.log(bancos);

Ejemplo de respuesta

[
  { "CodigoBanco": "10512", "NombreBanco": "BANCO DAVIVIENDA" },
  { "CodigoBanco": "10007", "NombreBanco": "BANCOLOMBIA" },
  { "CodigoBanco": "10001", "NombreBanco": "BANCO DE BOGOTA" }
]

Crear Transacción PSE

Inicia una transacción de débito bancario a través de PSE (Pagos Seguros en Línea). El cliente es redirigido al portal de su banco para autorizar el pago.

Headers

Envía tu Api_key en el header x-api-key.

Parámetros

Cuerpo de ejemplo

{
  "amount"             : 30000,
  "PersonType"         : "0",
  "identification_type": 4,
  "Documento"          : "1012345678",
  "Correo"             : "cliente@email.com",
  "Nombres"            : "Ana",
  "Apellidos"          : "Perez",
  "Celular"            : "3167225855",
  "Direccion"          : "Calle 32 # 74-31",
  "external_order"     : "ORD-PSE-001",
  "CodigoBanco"        : "10512",
  "NombreBanco"        : "BANCO DAVIVIENDA",
  "entityurl"          : "https://tu-sitio.com/pago-exitoso",
  "terminal_id"        : 34,
  "form_id"            : 34,
  "ip"                 : "192.168.0.1",
  "additionalData"     : { "referencia": "mi-referencia" }
}

Ejemplo de petición

const headers = new Headers();
headers.append("x-api-key", "TU_API_KEY");
headers.append("Content-Type", "application/json");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/CrearTransaccionPSE",
  { method: 'POST', headers, body: JSON.stringify(body), redirect: 'follow' }
);
const resultado = await res.json();

// Redirige al cliente al portal PSE
if (resultado.urlBanco) {
  window.location.href = resultado.urlBanco;
}

Obtener Medios De Pago en Efectivo

Retorna el listado de métodos de pago en efectivo habilitados (Efecty, Baloto, etc.). El campo method retornado aquí se envía directamente en Crear Transacción Cash.

Headers

Envía tu Api_key en el header Authorization.

Ejemplo de petición

const headers = new Headers();
headers.append("Authorization", "TU_API_KEY");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/ObtenerMediosDePago",
  { method: 'GET', headers, redirect: 'follow' }
);
const medios = await res.json();
console.log(medios);

Crear Transacción Cash

Genera un recibo de pago en efectivo para que el cliente cancele en un punto físico (Efecty, Baloto, Su Red, etc.). El cliente recibe un voucher con el código de pago.

Headers

Envía tu Api_key en el header x-api-key.

Parámetros

Cuerpo de ejemplo

{
  "amount"              : 30000,
  "external_order"      : "ORD-CASH-001",
  "description"         : "Pago membresía mensual",
  "method"              : "efecty",
  "iva"                 : 0,
  "user_identification" : "1012345678",
  "identification_type" : "CC",
  "user_name"           : "Andres",
  "user_last_name"      : "Camil",
  "user_email"          : "andres@example.com",
  "user_phone"          : "3227358312",
  "user_address"        : "Cra 8b 17 15",
  "terminal_id"         : 34,
  "form_id"             : 34,
  "ip"                  : "192.168.0.1",
  "additionalData"      : { "ref": "valor" }
}

Ejemplo de petición

const headers = new Headers();
headers.append("x-api-key", "TU_API_KEY");
headers.append("Content-Type", "application/json");

const res = await fetch(
  "https://serviceregister.paymentsway.co/ClientAPI/CrearTransaccionCash",
  { method: 'POST', headers, body: JSON.stringify(body), redirect: 'follow' }
);
const resultado = await res.json();

// resultado.urlVoucher contiene el link al voucher de pago
console.log(resultado);

WebHook

Recibe notificaciones en tiempo real sobre el resultado de cada transacción. PaymentsWay hace un HTTP POST a tu endpoint cuando una transacción cambia de estado.

Estados y cómo responder

Responde con 200 únicamente cuando el estado es Exitosa (id 34). Para todos los demás estados responde 201.

Campos del payload

Ejemplo de payload — Transacción exitosa

{
  "id"            : "822",
  "ammount"       : 4000,
  "externalorder" : "12001",
  "ip"            : "172.0.0.1",
  "fullname"      : "",
  "additionaldata": null,
  "idstatus"      : { "id": 34, "nombre": "Exitosa" },
  "idperson"      : {
    "id"            : "60",
    "firstname"     : "Ejemplo nombre",
    "lastname"      : "Ejemplo apellido",
    "identification": "1200345601",
    "email"         : "",
    "phone"         : ""
  },
  "paymentmethod": { "id": 2, "nombre": "PSE" },
  "idmerchant"   : "1"
}

Ejemplo de payload — PSE rechazado (con innerexception)

{
  "id"            : "id",
  "amount"        : 100,
  "externalorder": "external",
  "ip"            : "127.0.0.1",
  "fullname"      : "",
  "additionaldata": {},
  "innerexception": { "codigo": "00001", "causal": "CUENTA NO EXISTE" },
  "idstatus"      : { "id": 36, "nombre": "Fallida" },
  "idperson"      : {
    "id": "", "firstname": "", "lastname": "",
    "identification": "", "email": "", "phone": ""
  },
  "paymentmethod": { "id": 2, "nombre": "PSE" },
  "idmerchant"   : ""
}

Ejemplo de handler en Node.js

app.post('/webhook/paymentsway', async (req, res) => {
  const { id, externalorder, idstatus, idperson, amount } = req.body;

  if (idstatus?.id === 34) {
    // Transacción exitosa — actualiza tu base de datos
    await db.updateOrder(externalorder, { status: 'paid', amount });
    return res.status(200).send('OK');
  }

  // Cualquier otro estado
  return res.status(201).send('RECEIVED');
});

BReB — QR

BReB (Botón de Recaudo Bancario) es el estándar colombiano de pagos inmediatos QR impulsado por Banco de la República de Colombia. PaymentsWay lo implementa sobre la infraestructura de VePay / qrvbreb.vepay.com.co, cumpliendo el estándar QR. Permite recibir pagos desde cualquier app bancaria del ecosistema ACH.

Flujo completo QR

El siguiente diagrama muestra los 5 pasos del ciclo de vida de un QR BReB, desde el login hasta la confirmación del pago:

URL Base y autenticación

https://qrvbreb.vepay.com.co

Todos los endpoints (excepto Login) requieren el header Authorization: Bearer {token} con el JWT obtenido en el paso 1.

Tipos de QR

Ecosistema compatible

01 — Login

Autentícate con las credenciales entregadas por PaymentsWay para obtener el JWT Bearer token que necesitas en todas las demás llamadas. El token expira en 1 hora.

Headers

Cuerpo de la petición

{
  // Username y Password que comparte Payments Way
  "username": "",
  "password": ""
}

Ejemplo de petición

const res = await fetch('https://qrvbreb.vepay.com.co/api/auth/login', {
  method : 'POST',
  headers: { 'Content-Type': 'application/json' },
  body   : JSON.stringify({
    username: 'TU_USUARIO',
    password: 'TU_PASSWORD'
  })
});
const { token } = await res.json();
// Guarda el token para usarlo en las demás llamadas
localStorage.setItem('breb_token', token);

cURL

curl --location 'https://qrvbreb.vepay.com.co/api/auth/login' \\
--header 'Content-Type: application/json' \\
--data '{
  "username": "",
  "password": ""
}'

02 — Generar QR

Genera un código QR siguiendo el estándar QR. Puedes crear QRs estáticos (11) para puntos de venta físicos o dinámicos (12) para cobros específicos con monto fijo.

Headers

Parámetros del body

Cuerpo de ejemplo

{
  // Siempre debe ser "01"
  "payloadFormatIndicator": "01",
  // 11 = estático, 12 = dinámico
  "pointOfInitiationMethod": "12",
  "merchantAccountInformation": {
    // Tipo de llave: PHONE, NRIC, EMAIL, ALPHANUM, MERCHANTCODE
    "keytype"       : "PHONE",
    // Número de celular registrado del comercio (10 dígitos)
    "key"           : "3001234567",
    "merchantName"  : "Mi Tienda Online",
    "merchantCity"  : "Bogota",
    "postalCode"    : "110111",
    // Código MCC — 0000 para genérico
    "merchantCategoryCode": "0000"
  },
  "transaction": {
    // Monto con 2 decimales. QR dinámico: "0"
    "value"   : "5000.00",
    // Para COP usar "CO" (ISO 4217: 170)
    "currency": "CO"
  }
}

cURL

curl --location 'https://qrvbreb.vepay.com.co/api/qr/generate' \\
--header 'Authorization: Bearer TU_JWT_TOKEN' \\
--header 'Content-Type: application/json' \\
--data '{
  "payloadFormatIndicator": "01",
  "pointOfInitiationMethod": "12",
  "merchantAccountInformation": {
    "keytype": "PHONE",
    "key": "3001234567",
    "merchantName": "Mi Tienda Online",
    "merchantCity": "Bogota",
    "postalCode": "110111",
    "merchantCategoryCode": "0000"
  },
  "transaction": {
    "value": "5000.00",
    "currency": "CO"
  }
}'

Ejemplo JavaScript

const token = localStorage.getItem('breb_token'); // obtenido en Login

const res = await fetch('https://qrvbreb.vepay.com.co/api/qr/generate', {
  method : 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type' : 'application/json'
  },
  body: JSON.stringify({
    payloadFormatIndicator : "01",
    pointOfInitiationMethod: "12",
    merchantAccountInformation: {
      keytype             : "PHONE",
      key                 : "3001234567",
      merchantName        : "Mi Tienda Online",
      merchantCity        : "Bogota",
      postalCode          : "110111",
      merchantCategoryCode: "0000"
    },
    transaction: { value: "5000.00", currency: "CO" }
  })
});
const qrData = await res.json();
// qrData contiene el QR string (EMV) y/o imagen para mostrar al cliente
console.log(qrData);

03 — Verificar Token

Verifica que un JWT token (generado en el paso Generar QR) sea válido y no haya expirado. Úsalo para validar el QR antes de mostrarlo al cliente o para confirmar que la sesión sigue activa.

Headers

Cuerpo

{
  // Token generado en 02 - Generar QR
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

cURL

curl --location 'https://qrvbreb.vepay.com.co/api/auth/verify' \\
--header 'Content-Type: application/json' \\
--data '{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Ejemplo JavaScript

const res = await fetch('https://qrvbreb.vepay.com.co/api/auth/verify', {
  method : 'POST',
  headers: { 'Content-Type': 'application/json' },
  body   : JSON.stringify({ token: qrData.token })
});
const verification = await res.json();
console.log(verification); // { valid: true, ... }

Consulta

Consulta el estado y los detalles de un QR generado usando su id. Usa este endpoint para hacer polling y detectar cuándo el cliente ha completado el pago.

Headers

Path Parameter

cURL

curl --location 'https://qrvbreb.vepay.com.co/api/qr/QR_ID_AQUI' \\
--header 'Authorization: Bearer TU_JWT_TOKEN'

Ejemplo JavaScript — Polling

// Polling cada 3 segundos hasta confirmar el pago
const pollQRStatus = (qrId, token) => {
  const interval = setInterval(async () => {
    const res = await fetch(
      `https://qrvbreb.vepay.com.co/api/qr/${qrId}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    const qr = await res.json();

    if (qr.status === 'PAID' || qr.status === 'COMPLETED') {
      clearInterval(interval);
      console.log('✓ Pago confirmado', qr);
      // Actualiza tu UI y base de datos
    }

    if (qr.status === 'EXPIRED') {
      clearInterval(interval);
      console.log('QR expirado');
    }
  }, 3000);
};

pollQRStatus('QR_ID_AQUI', token);

Status — Actualizar Estado

Actualiza el estado de un QR existente. Se usa para marcar un QR como pagado después de recibirla confirmación del banco, o para invalidarlo manualmente.

Headers

Estados disponibles

Cuerpo de ejemplo

{
  "status": "PAID"
}

cURL

curl --location --request PATCH \\
  'https://qrvbreb.vepay.com.co/api/qr/QR_ID_AQUI/status' \\
  --header 'Authorization: Bearer TU_JWT_TOKEN' \\
  --header 'Content-Type: application/json' \\
  --data '{ "status": "PAID" }'

Ejemplo JavaScript

const res = await fetch(
  `https://qrvbreb.vepay.com.co/api/qr/${qrId}/status`,
  {
    method : 'PATCH',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type' : 'application/json'
    },
    body: JSON.stringify({ status: 'PAID' })
  }
);
const result = await res.json();
console.log(result);

Integración BReB — Transferencias BReB

Esta API permite hacer transferencias de dinero entre cuentas bancarias usando el sistema BReB de Integración BReB. Piénsala como el "mesero" entre tu app y los bancos: tú le dices a quién le mandas la plata y cuánto, y él se encarga de hacer todo el proceso por detrás para que el dinero llegue.

¿Qué puedes hacer con este sistema?

Flujo completo de una transferencia

El siguiente diagrama muestra el orden en que se usan los endpoints para completar una transferencia desde cero:

URL Base

{BASE_URL}/visionamos

Consultar llave de cliente

Busca la llave (correo, celular o cédula) con la que un cliente está registrado en el sistema. Es como buscar un contacto en el celular — si existe, te muestra toda su información; si no existe, te avisa que no lo encontró.

Parámetros

Ejemplo de petición

{
  "channel"          : "REDESALIADAS",
  "sourceService"    : "PEX",
  "user"             : "jcano",
  "identification"   : "1144134800",
  "typeIdentification": "CC",
  "ip"               : "192.168.0.1",
  "purpose"          : "Source",
  "uuid"             : "a1b2c3d4e5f67890",
  "mac"              : "08:BD:01:00:00:00",
  "platform"         : "iOS",
  "trademark"        : "Apple",
  "model"            : "iPhone 15",
  "geoLocation"      : "4.710989,-74.072092",
  "versionPlatform"  : "13"
}

Respuestas

Registrar llave de cliente

Crea una nueva llave para un cliente — puede ser su correo, celular o cédula — y la vincula a su cuenta bancaria. Es como inscribirse a Nequi por primera vez: das tu número de celular y lo atan a tu cuenta.

Parámetros

Ejemplo de petición

{
  "channel"                      : "MOVIL",
  "sourceService"                : "MEX",
  "identification"               : "80009330",
  "typeIdentification"           : "CC",
  "numberAccount"                : "862000034",
  "processKeyCustomer"           : "NEWR",
  "typeKeyCustomer"              : "E",
  "valueKeyCustomer"             : "rolozadag@gmail.com",
  "typeAccount"                  : "AH",
  "subTypeAccount"               : "DE",
  "receptorNode"                 : "VIS",
  "sourceTypeAccountDescription": "Ahorros a la Vista",
  "businessName"                 : "Cliente Test Nuevo",
  "firstName"                    : "RENE",
  "surName"                      : "LOZADA",
  "secondSurName"                : "null",
  "user"                         : "rene"
}

Respuestas

Actualizar llave de cliente

Modifica los datos de una llave que ya existe. Por ejemplo, si el cliente cambió de correo o quiere actualizar el nombre. Es como editar un contacto guardado en el celular.

Parámetros clave

Ejemplo de petición

{
  "channel"                      : "MOVIL",
  "processKeyCustomer"           : "AMND",
  "typeKeyCustomer"              : "E",
  "valueKeyCustomer"             : "rolozadag@gmail.com",
  "idKeyCustomer"                : "416da151-51e9-4bd6-8c13-4f244f3648d9",
  "receptorNode"                 : "VIS",
  "sourceTypeAccountDescription": "Ahorros a la Vista",
  "businessName"                 : "Integración BReB",
  "firstName"                    : "RENEE",
  "surName"                      : "LOZADA",
  "sourceService"                : "MEX",
  "identification"               : "80009330",
  "typeIdentification"           : "CC",
  "numberAccount"                : "862000034",
  "typeAccount"                  : "AH",
  "subTypeAccount"               : "DE",
  "user"                         : "jcano"
}

Respuestas

Eliminar llave de cliente

Desvincula y elimina la llave de un cliente. Después de esto, esa llave ya no se puede usar para recibir transferencias. Es como borrar un número de cuenta de tus favoritos en la app del banco.

Parámetros

Ejemplo de petición

{
  "channel"           : "MOVIL",
  "processKeyCustomer": "DEAC",
  "typeKeyCustomer"   : "E",
  "valueKeyCustomer"  : "rolozadag@gmail.com",
  "idKeyCustomer"     : "1f66a569-5f23-4ba2-8f7a-53d4c77d2400",
  "receptorNode"      : "VIS",
  "sourceTypeAccountDescription": "Ahorros a la Vista",
  "businessName"      : "Integración BReB",
  "firstName"         : "Brayan",
  "surName"           : "Marin",
  "sourceService"     : "MEX",
  "identification"    : "80009330",
  "typeIdentification": "CC",
  "numberAccount"     : "862000034",
  "typeAccount"       : "AH",
  "subTypeAccount"    : "DE",
  "ip"                : "192.168.0.1",
  "user"              : "jcano"
}

Respuestas

Consultar destinatario (GetTarget)

Busca a quién le vas a enviar la plata usando su llave (correo, celular o cédula). Cuando envías la información del monto y cuenta origen, el sistema prepara la transacción y te devuelve un transactionId — guárdalo porque lo necesitas en el siguiente paso.

Parámetros

* Si envías uno de los tres (amount, sourceIdentification, sourceAccount), debes enviar los tres juntos.

Ejemplo de petición

{
  "channel"           : "WEB",
  "sourceService"     : "PEX",
  "entity"            : "EB000001",
  "user"              : "jcano",
  "typeKeyCustomer"   : "E",
  "valueKeyCustomer"  : "deison_ac@hotmail.com",
  "ip"                : "192.168.0.1",
  "amount"            : "1.02",
  "sourceIdentification": "1051287968",
  "sourceAccount"     : "852000002",
  "geoLocation"       : "4.710989,-74.072092"
}

Respuestas

Realizar Transferencia

Ejecuta la transferencia de dinero entre dos cuentas. Es el paso final donde el dinero realmente se mueve. Necesitas tener listo el targetResolutionId que obtuviste en Consultar destinatario.

Parámetros — Origen (quien envía)

Parámetros — Destino (quien recibe)

Ejemplo de petición

{
  "channel"              : "MOVIL",
  "sourceService"        : "MEX",
  "user"                 : "jcano",
  "ip"                   : "192.168.0.1",
  "reference"            : "Pago de referencia",
  "amount"               : "1000000",
  "sourceIdentification" : "11281434",
  "sourceTypeIdentification": "CC",
  "sourceFirstName"      : "DEISON ANDREI",
  "sourceSurName"        : "BUITRAGO",
  "sourceEntity"         : "EB000001",
  "sourceNumberAccount"  : "862000159",
  "sourceTypeAccount"    : "AH",
  "sourceSubTypeAccount" : "DE",
  "targetResolutionId"   : "373988e9-490c-48d6-aa12-a06b92e184af",
  "targetValueKeyCustomer": "80009330",
  "targetTypeKeyCustomer": "NRIC",
  "targetEntity"         : "00000022",
  "targetNumberAccount"  : "862000034",
  "targetTypeAccount"    : "AH",
  "targetSubTypeAccount" : "DE",
  "targetNode"           : "NODE001",
  "targetIdentification" : "80009330",
  "targetTypeIdentification": "CC",
  "targetFirstName"      : "RENE",
  "targetSurName"        : "LOZADA"
}

Respuestas

Consultar pago específico

Verifica el estado de una transferencia que ya realizaste usando su paymentId. Es como rastrear un paquete de Rappi: le das el número de pedido y te dice en qué estado va.

Parámetros

{
  "paymentId"  : "6bd54b39-c876-4295-9b58-c2735147ece8",
  "initialDate": "20250804",
  "finalDate"  : "20250804",
  "initialHour": "081700",
  "finalHour"  : "235900"
}

Respuestas

Historial de pagos de un cliente

Consulta todos los pagos que ha realizado un cliente en un rango de fechas y horas. Es como pedir el extracto bancario de los últimos días, pero filtrado por el sistema BReB.

Parámetros

{
  "identification"    : "1193127269",
  "typeIdentification": "CC",
  "initialDate"       : "20250804",
  "finalDate"         : "20250804",
  "initialHour"       : "000000",
  "finalHour"         : "235959"
}

Respuestas