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

Genera links de pago desde la consola o vía API y compártelos por cualquier canal: email, WhatsApp, SMS o redes sociales.

Links masivos

Genera links para múltiples clientes a la vez cargando una plantilla de Excel. Ideal para facturación por lotes o cobros periódicos.

Link individual

Crea un link para un cliente específico con sus datos prellenados o genérico sin datos. Dispones de tres acciones sobre el link generado:

• Ver — Abre el checkout en el navegador.
• Copiar — Copia el link recortado al portapapeles.
• Compartir — Envía por SMS 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 el cliente seleccione el monto antes de pagar.

Botón de Pago

Un formulario HTML que redirige al cliente al checkout de PaymentsWay con los datos de la compra precargados.

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

Permite que el cliente seleccione o ingrese el monto que desea pagar, dentro de un rango mínimo/máximo que defines tú.

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 permite aceptar pagos directamente en tu sitio sin redirecciones. Solo necesitas incluir 3 bloques de código.

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

Experiencia del cliente al interactuar con el widget de pagos.

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 embebibles con branding personalizado que puedes insertar en cualquier página web autorizada.

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

Integra PaymentsWay en tu tienda WooCommerce en menos de 10 minutos sin tocar código.

Instalación

1. Ve a WordPress → Plugins → Añadir nuevo → Subir plugin, selecciona el .zip e instala.
2. Activa el plugin y ve a WooCommerce → Ajustes → Pagos.
3. Activa PaymentsWay y haz clic en Configurar.
4. Completa: ID MERCHANT, ID TERMINAL, ID BOTÓN DE PAGO, APIKEY.
5. Copia la URL de tu página de tienda y pégala en el campo URL de retorno.
6. Guarda los cambios.

PrestaShop

Módulo nativo de PaymentsWay para PrestaShop con configuración visual sin código.

Paso 1 — Instalación

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

Paso 2 — Configuración

1. Localiza PaymentsWay en el listado y haz clic en Configurar.
2. Ingresa tus credenciales (merchant_id, terminal_id, form_id, apikey).
3. Guarda los cambios.

Paso 3 — Preferencias

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

Magento

Extensión de PaymentsWay para Magento 2 instalable vía cPanel o Composer.

Instalación

1. Accede a cPanel y abre el Administrador de archivos.
2. Navega a la carpeta raíz de Magento y luego a app/.
3. Sube el .zip y descomprímelo. Se creará la carpeta code/.

Configuración

1. Accede al panel de administración de Magento.
2. Ve a Stores → Configuration → Sales → Payments Way Configuration.
3. Agrega tus datos: terminal, formulario, merchant, apikey y response URL.
4. Guarda y limpia el caché.

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.

Estados del sistema

Ejemplo de petición

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');
});

PayOuts

Servicio de dispersión de fondos. Permite enviar dinero a múltiples cuentas bancarias desde tu saldo en PaymentsWay.

Documentación

BReB — QR

BReB (Botón de Recaudo Bancario) es el estándar de pagos inmediatos mediante código QR, iniciativa del Banco de la República de Colombia. PaymentsWay lo implementa a través de la infraestructura de VePay. Permite recibir pagos desde cualquier app bancaria habilitada.

Flujo completo de pago con 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

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 dinámico o estático. 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 string del QR 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

Esta API permite hacer transferencias de dinero entre cuentas bancarias a través del sistema 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}/breb

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"                 : "PaymentsWay",
  "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"      : "PaymentsWay",
  "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

Reportes

El módulo de reportes permite generar, programar y enviar automáticamente informes de transacciones BReB. Ideal para conciliación contable, auditoría y control de movimientos.

Endpoints disponibles

Flujo típico de reportes

1. Crea los destinatarios que recibirán los reportes (POST /reports/recipients).
2. Crea un programa de reporte con la frecuencia y configuración deseada (POST /reports/schedules).
3. Vincula los destinatarios al programa generado.
4. Genera el reporte manualmente cuando necesites (GET /reports/generate-and-send) o espera la ejecución automática según el programa.