PayBoom API Reference v1.0

API REST unificada para procesamiento de pagos en Mexico. Integra multiples procesadores de pago bajo una sola interfaz tecnica: transferencias bancarias, pagos en efectivo y ventanilla, depositos referenciados, y tarjetas de credito/debito con soporte para 3D Secure.

Django 5.1 REST API MySQL Bearer Auth

Base URL

https://api.payboom.io

Quick Start

Obtener tu API Key
Solicita tus credenciales de integracion. Recibiras un api_key con formato pb_ak_... y un MID (Merchant ID).
Elegir metodo de pago
Usa POST /directbank para transferencias y efectivo, o POST /directcard para tarjetas de credito/debito.
Redirigir al pagador
Para DirectBank, redirige al usuario a la URL recibida en bank_response.url. Para DirectCard, procesa la respuesta o redirige al challenge 3DS.
Recibir notificacion
PayBoom enviara un POST a tu notifyUrl cuando el pago cambie de estado.

Arquitectura

Tu Comercio

→

PayBoom API

→

Transferencia Bancaria

Pago en Ventanilla

Pago en Efectivo

Tarjeta de Credito/Debito

Tu comercio integra una sola API. PayBoom enruta al procesador correspondiente segun el bank_code. Consulta el directorio de bancos para obtener los codigos disponibles.

Autenticacion

Todos los endpoints requieren autenticacion via Bearer Token en el header Authorization.

HTTP Header

Authorization: Bearer pb_ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Formato del API Key Las API Keys de PayBoom siguen el formato pb_ak_ seguido de 48 caracteres alfanumericos URL-safe. El API Key debe tener estado Activo para ser valido.

Permisos por Banco

Cada API Key tiene permisos especificos por procesador de pago (bank_code). Si intentas usar un procesador sin permiso, recibiras un error 403.

JSON — 403 Forbidden

{
  "error": "Unauthorized for this bank code",
  "status": 403
}

JSON — 401 Unauthorized

{
  "error": "Invalid or missing API key"
}

Direct Bank — Transferencias y Efectivo

El endpoint /directbank permite crear pagos a traves de metodos alternativos a la tarjeta: transferencias bancarias, pagos en ventanilla, depositos referenciados y pagos en efectivo. Cada servicio se activa con un bank_code diferente.

Canales de Pago

PayBoom soporta diversos canales de pago a traves de /directbank. El canal se determina por el bank_code que envies en el request.

Canal	Descripcion	Experiencia del usuario
Transferencia bancaria	Pago via transferencia interbancaria. Disponible 24/7.	El usuario recibe una CLABE y datos bancarios para transferir desde su banca en linea o app movil.
Pago en ventanilla / efectivo	Pago en efectivo en puntos fisicos autorizados (tiendas de conveniencia, cadenas comerciales).	El usuario recibe un codigo de barras o referencia de pago que presenta en la tienda.
Deposito referenciado	Deposito bancario con referencia unica asignada.	El usuario realiza un deposito en ventanilla bancaria o transferencia con la referencia proporcionada.

Directorio de bancos Consulta el endpoint GET /banks para obtener el listado completo de bank_code disponibles para tu comercio, con sus canales y descripcion. Cada codigo activa un motor de reglas y flujo de usuario especifico.

POST /directbank Crear pago por transferencia o efectivo

Auth: Authorization: Bearer {api_key}

Request Body

Campo	Tipo	Requerido	Descripcion
bank_code	string	*	Codigo del servicio de pago. Consulta el directorio de bancos (`GET /banks`) para obtener los codigos disponibles.
amount	number	*	Monto total de la transaccion
mchOrderNo	string	*	ID unico de orden de tu comercio
currency	string	*	Moneda. Debe ser `"MXN"`
notifyUrl	string	*	URL donde PayBoom enviara la notificacion del estado del pago
shopper	object	*	Informacion del pagador (ver objeto shopper abajo)

Objeto shopper

Campo	Tipo	Descripcion
first_name	string	Nombre(s) del comprador
last_names	string	Apellidos del comprador
phone_number	string	Numero de telefono
tax_id_type	string	Tipo de identificacion fiscal (e.g. CURP, RFC)
tax_id	string	Identificacion fiscal del comprador

Campos opcionales adicionales

Algunos procesadores pueden requerir campos adicionales. Consulta el directorio de bancos para conocer los campos especificos de cada bank_code.

Campo	Tipo	Descripcion
email	string	Email del comprador
country_code	string	Codigo de pais (e.g. `"MX"`)
bank_id	string	ID del banco destino (cuando aplica)
payment_ok_url	string	URL de redireccion en caso de exito
payment_error_url	string	URL de redireccion en caso de error
expiration_time_minutes	number	Tiempo de expiracion en minutos (default: 2880)

JSON

{
  "bank_code": "1001",
  "amount": 500.00,
  "mchOrderNo": "ORD-2026-00123",
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/payboom",
  "shopper": {
    "first_name": "Juan",
    "last_names": "Perez Lopez",
    "phone_number": "5551234567",
    "tax_id_type": "CURP",
    "tax_id": "PELJ900101HDFRPN09"
  }
}

JSON — 200 OK

{
  "success": true,
  "payboom_reference": "pb_20260415120530123_93dfbb",
  "mchOrderNo": "ORD-2026-00123",
  "amount": 500.00,
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/payboom",
  "bank_response": {
    "resCode": "SUCCESS",
    "url": "https://payment.sipelatam.mx/pay/order/12345"
  }
}

cURL

curl -X POST https://api.payboom.io/directbank \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_code": "1001",
    "amount": 500.00,
    "mchOrderNo": "ORD-2026-00123",
    "currency": "MXN",
    "notifyUrl": "https://mi-sitio.com/webhook/payboom",
    "shopper": {
      "first_name": "Juan",
      "last_names": "Perez Lopez",
      "phone_number": "5551234567",
      "tax_id_type": "CURP",
      "tax_id": "PELJ900101HDFRPN09"
    }
  }'

Campo clave: bank_response.url Redirige al usuario a esta URL para que complete el pago. Segun el canal, vera datos de transferencia bancaria, un codigo de barras para pago en efectivo, o instrucciones de deposito referenciado.

Errores

Codigo	Descripcion
400	Campos requeridos faltantes, moneda invalida o banco inactivo
401	API Key invalida o ausente
403	Sin permiso para el `bank_code` solicitado
500	Error del proveedor de pago
501	Integracion del banco no implementada

Flujo de Pago

Independientemente del canal de pago, el flujo siempre sigue el mismo patron:

          1. Tu backend hace POST /directbank con el bank_code correspondiente
        
          2. PayBoom retorna bank_response.url con la pagina de pago del canal seleccionado
        
          3. Redirige al usuario a la URL → segun el canal, vera datos de transferencia, un codigo de barras, una referencia de deposito, etc.
        
          4. Cuando el pago es confirmado, PayBoom envia POST a tu notifyUrl con status APPROVED

Directorio de bancos Consulta GET /banks para obtener la lista completa de bank_code disponibles para tu comercio. El directorio incluye el canal, nombre del servicio y estado de cada procesador.

Webhooks — Notificaciones de Pago

Cuando el estado de un pago cambia, PayBoom envia un POST a la URL que especificaste en notifyUrl. Nunca asumas que un pago fue exitoso por la redireccion; espera siempre la confirmacion del webhook.

JSON — Notificacion al comercio

{
  "payboom_reference": "pb_20260415120530123_93dfbb",
  "mchOrderNo": "ORD-2026-00123",
  "status": "APPROVED",
  "amount": "500.00",
  "currency": "MXN",
  "provider_reference": "PROVIDER-TX-789456",
  "bank_code": "1001",
  "authorization": "AUTH123456"
}

Verificacion de firmas PayBoom valida la firma criptografica de cada notificacion del proveedor antes de procesarla. Tu endpoint notifyUrl debe responder con HTTP 200 para confirmar recepcion.

Direct Card — Pagos con Tarjeta

El endpoint /directcard permite procesar pagos con tarjeta de credito y debito. Existen dos flujos de pago posibles:

Flujo	Descripcion	Respuesta
Autorizacion y Captura	Pago tradicional donde la autorizacion y captura se realizan en el mismo request. Respuesta inmediata.	`APPROVED` o `DECLINED`
3D Secure (3DS)	Pago con autenticacion del banco emisor. Requiere redireccion del usuario para completar un challenge (OTP, biometria, etc.).	`PENDING` + `redirect_url`

Directorio de bancos Consulta GET /banks para obtener los bank_code disponibles para pagos con tarjeta en tu comercio. El tipo de flujo (tradicional o 3DS) depende del procesador asignado a cada bank_code.

Horario restringido Las transacciones con tarjeta se bloquean entre 1:00 AM y 5:59 AM (hora CDMX). Pagos enviados en ese horario seran rechazados automaticamente con codigo P07.

POST /directcard Crear pago con tarjeta de credito/debito

Auth: Authorization: Bearer {api_key}

Request Body

Campo	Tipo	Requerido	Descripcion
bank_code	string	*	Codigo del procesador de tarjetas. Consulta el directorio de bancos (`GET /banks`).
amount	number	*	Monto total de la transaccion
id	string	*	ID unico de orden de tu comercio (se devuelve como `mchOrderNo`)
currency	string	*	Moneda ISO 4217 (e.g. `"MXN"`). La moneda soportada depende del `bank_code`.
notifyUrl	string	*	URL para recibir la notificacion del resultado
email	string	*	Email del tarjetahabiente
card	object	*	Datos de la tarjeta (ver objeto card)
shopper	object	*	Datos del comprador (ver objeto shopper)
description	string	opcional	Descripcion de la transaccion
successUrl	string	opcional	URL de redireccion tras pago exitoso (necesaria para 3DS)
errorUrl	string	opcional	URL de redireccion tras pago fallido (necesaria para 3DS)
term_url_3ds	string	opcional	URL terminal 3DS (sobreescribe `successUrl` para redirects 3DS)

Objeto card

Campo	Tipo	Requerido	Descripcion
holderName	string	*	Nombre del tarjetahabiente tal como aparece en la tarjeta
cardNumber	string	*	Numero completo de la tarjeta (PAN)
expiryYear	string	*	Ano de expiracion (4 digitos, e.g. `"2028"`)
expiryMonth	string	*	Mes de expiracion (1-12, e.g. `"12"`)
cvv	string	*	Codigo de seguridad (CVV/CVC)

Objeto shopper

Campo	Tipo	Requerido	Descripcion
first_name	string	*	Nombre del comprador
last_name	string	*	Apellido del comprador
phone	string	*	Telefono del comprador
state	string	*	Estado/provincia
city	string	*	Ciudad
address	string	*	Direccion completa
postal_code	string	*	Codigo postal
customer_ip	string	*	Direccion IP del comprador
country	string	opcional	Codigo de pais (e.g. `"MX"`)

Moneda La moneda aceptada depende del procesador asignado al bank_code. Consulta el directorio de bancos para verificar la moneda soportada. Si envias una moneda incorrecta recibiras un error 400.

Autorizacion y Captura (Pago Tradicional)

En el flujo tradicional, la autorizacion y captura se realizan en un solo request. La respuesta es inmediata: APPROVED o DECLINED. No requiere redireccion del usuario.

          1. Tu backend hace POST /directcard con datos de tarjeta y comprador
        
          2. PayBoom valida la tarjeta, verifica permisos y ejecuta chequeos de velocidad
        
          3. Retorna respuesta inmediata con status: "APPROVED" o "DECLINED"

JSON — Autorizacion y Captura

{
  "bank_code": "{bank_code}",
  "amount": 299.99,
  "id": "ORD-CARD-001",
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/card",
  "email": "juan@email.com",
  "card": {
    "holderName": "JUAN PEREZ LOPEZ",
    "cardNumber": "4111111111111111",
    "expiryYear": "2028",
    "expiryMonth": "12",
    "cvv": "123"
  },
  "shopper": {
    "first_name": "Juan",
    "last_name": "Perez",
    "phone": "5551234567",
    "state": "CDMX",
    "city": "Ciudad de Mexico",
    "address": "Av. Reforma 222, Col. Juarez",
    "postal_code": "06600",
    "customer_ip": "189.203.45.67",
    "country": "MX"
  }
}

JSON — 200 OK (Aprobada)

{
  "success": true,
  "status": "APPROVED",
  "authorization": "AUTH789456",
  "payboom_reference": "pb_20260415130045789_a1b2c3",
  "mchOrderNo": "ORD-CARD-001",
  "provider_reference": "PROVIDER-TX-123456",
  "amount": "299.99",
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/card",
  "redirect_url": "",
  "bank_response": {
    "resp_code": "00",
    "description": "Transaccion aprobada"
  }
}

JSON — 200 (Rechazada)

{
  "success": false,
  "status": "DECLINED",
  "authorization": "",
  "payboom_reference": "pb_20260415130050123_d4e5f6",
  "mchOrderNo": "ORD-CARD-002",
  "provider_reference": "",
  "amount": "299.99",
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/card",
  "redirect_url": "",
  "bank_response": {
    "resp_code": "51",
    "description": "Fondos insuficientes"
  }
}

Pago con 3D Secure (3DS)

Algunos procesadores requieren autenticacion 3D Secure. Cuando el procesador determina que se necesita verificacion del banco emisor, la respuesta incluye un redirect_url al que debes redirigir al usuario para completar el challenge.

Campos requeridos para 3DS Cuando uses procesadores con 3DS, es importante incluir successUrl y errorUrl en el request. Estas URLs se usan para redirigir al usuario despues del challenge 3DS.

          1. Tu backend hace POST /directcard con datos de tarjeta + successUrl + errorUrl
        
          2. PayBoom retorna status: "PENDING" y un redirect_url → redirige al usuario ahi
        
          3. El usuario completa el challenge 3DS en la pagina del banco emisor (OTP, biometria, etc.)
        
          4. El banco redirige al callback de PayBoom, que verifica el resultado y actualiza la transaccion
        
          5. PayBoom redirige al usuario a tu successUrl o errorUrl y envia POST a notifyUrl

JSON — Request 3DS

{
  "bank_code": "{bank_code}",
  "amount": 1500.00,
  "id": "ORD-3DS-001",
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/card",
  "email": "cliente@email.com",
  "successUrl": "https://mi-sitio.com/pago-exitoso",
  "errorUrl": "https://mi-sitio.com/pago-error",
  "card": {
    "holderName": "CARLOS RODRIGUEZ",
    "cardNumber": "5500000000000004",
    "expiryYear": "2027",
    "expiryMonth": "06",
    "cvv": "456"
  },
  "shopper": {
    "first_name": "Carlos",
    "last_name": "Rodriguez",
    "phone": "5559876543",
    "state": "Jalisco",
    "city": "Guadalajara",
    "address": "Av. Vallarta 1234",
    "postal_code": "44100",
    "customer_ip": "201.141.78.90",
    "country": "MX"
  }
}

JSON — 200 (Redirect a 3DS)

{
  "success": true,
  "status": "PENDING",
  "authorization": "",
  "payboom_reference": "pb_20260415140012345_x1y2z3",
  "mchOrderNo": "ORD-3DS-001",
  "provider_reference": "PROVIDER-EXT-789",
  "amount": "1500.00",
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/card",
  "redirect_url": "https://procesador.com/3ds/challenge/PROVIDER-EXT-789",
  "bank_response": {
    "status": "REDIRECT",
    "external_id": "PROVIDER-EXT-789",
    "redirection_url": "https://procesador.com/3ds/challenge/PROVIDER-EXT-789"
  }
}

Accion requerida Cuando status es "PENDING" y hay un redirect_url, debes redirigir al usuario a esa URL para que complete el challenge 3DS. No consideres el pago como aprobado hasta recibir la notificacion en notifyUrl.

JSON — Webhook notifyUrl (POST)

{
  "payboom_reference": "pb_20260415140012345_x1y2z3",
  "mchOrderNo": "ORD-3DS-001",
  "status": "APPROVED",
  "amount": "1500.00",
  "currency": "MXN",
  "provider_reference": "PROVIDER-EXT-789",
  "bank_code": "{bank_code}",
  "authorization": "AUTH-3DS-456"
}

Flujo de estados — 3DS

POST /directcard

↓

PENDING + redirect_url

↓

Usuario completa challenge 3DS

↓

exito

APPROVED

→ successUrl

fallo

DECLINED

→ errorUrl

Webhooks y Callbacks (Tarjetas)

PayBoom maneja dos mecanismos de notificacion para pagos con tarjeta:

Mecanismo	Descripcion	Uso
notifyUrl (Webhook)	POST asincrono al backend del comercio con el resultado final	Actualizar el estado de la orden en tu base de datos
successUrl / errorUrl (Callback)	Redireccion del navegador del usuario tras el 3DS	Mostrar al usuario una pagina de confirmacion o error

Seguridad critica Nunca confies solo en la redireccion a successUrl para confirmar un pago. Un usuario malintencionado podria navegar manualmente a esa URL. Siempre verifica el estado real del pago usando el webhook notifyUrl.

Errores del endpoint /directcard

Codigo HTTP	Descripcion
400	Campos requeridos faltantes, tarjeta expirada, JSON invalido o moneda incorrecta para el procesador
401	API Key invalida o ausente
403	Sin permiso para el `bank_code` solicitado
429	Chequeo de velocidad fallido (demasiados intentos con la misma tarjeta)
500	Error del proveedor de pago
501	Integracion del banco no implementada

Cancelar y Reembolsar

Los endpoints de cancelacion y reembolso permiten revertir transacciones aprobadas. La disponibilidad de estas operaciones depende del procesador asignado a cada bank_code.

POST /cancel Cancelar una transaccion aprobada

Auth: Authorization: Bearer {api_key}

Request Body

Campo	Tipo	Requerido	Descripcion
payboom_reference	string	*	Referencia PayBoom de la transaccion original
amount	number	*	Monto a cancelar

JSON

{
  "payboom_reference": "pb_20260415130045789_a1b2c3",
  "amount": 299.99
}

JSON — 200 OK

{
  "success": true,
  "status": "CANCELLED",
  "payboom_reference": "pb_20260415150012345_new123",
  "original_payboom_reference": "pb_20260415130045789_a1b2c3",
  "provider_reference": "CANCEL-TX-789",
  "amount": 299.99,
  "bank_response": {}
}

Validaciones La transaccion original debe pertenecer al comercio autenticado, tener status APPROVED, SETTLED o APROBADA, y contar con una referencia del proveedor.

POST /refund Reembolsar una transaccion aprobada

Auth: Authorization: Bearer {api_key}

Mismo formato que /cancel. La diferencia principal es que algunos procesadores usan un endpoint dedicado de reembolso que puede estar disponible a partir del dia siguiente a la transaccion.

Campo	Tipo	Requerido	Descripcion
payboom_reference	string	*	Referencia PayBoom de la transaccion original
amount	number	*	Monto a reembolsar

Disponibilidad No todos los procesadores soportan cancelacion y reembolso. Algunos procesadores solo permiten cancelaciones el mismo dia y reembolsos a partir del dia siguiente. Consulta el directorio de bancos para verificar las operaciones disponibles para cada bank_code.

Endpoints de Consulta

GET /banks Listar bancos disponibles

Auth: Authorization: Bearer {api_key}

Retorna los bancos/procesadores que tu API Key tiene permiso para usar.

Query Parameters (opcionales)

Parametro	Descripcion
country	Filtrar por pais (e.g. `MX`)
channel	Filtrar por canal (e.g. `card`, `transfer`)

JSON — 200 OK

{
  "data": [
    {
      "code": "XXXX",
      "country": "MX",
      "channel": "transfer",
      "bankname": "Transferencia Bancaria",
      "providername": "Proveedor A",
      "estado": "Activo"
    },
    {
      "code": "YYYY",
      "country": "MX",
      "channel": "card",
      "bankname": "Tarjeta Credito/Debito",
      "providername": "Proveedor B",
      "estado": "Activo"
    }
  ]
}

Referencia — Estados de Transaccion

Estado	Descripcion	Procesadores
PENDING	Transaccion creada, esperando confirmacion o redireccion 3DS	Todos (formato estandar)
pendiente	Equivalente a PENDING (formato legacy de algunos procesadores)	Algunos procesadores de transferencia/efectivo
APPROVED	Pago aprobado exitosamente	Todos
DECLINED	Pago rechazado por el procesador o banco emisor	Tarjetas
3DS	En proceso de autenticacion 3D Secure	Algunos procesadores de tarjeta
SETTLED	Pago liquidado (fondos transferidos)	Algunos procesadores de tarjeta
CANCELLED	Transaccion cancelada	Tarjetas (con cancel)
REFUNDED	Transaccion reembolsada	Tarjetas (con refund)
FAILED	Error en el procesamiento	Todos

Codigos de Error HTTP

Codigo	Significado	Accion recomendada
400	Bad Request — Datos invalidos o incompletos	Verifica los campos requeridos y formatos
401	Unauthorized — API Key invalida	Verifica tu API Key y que este activa
403	Forbidden — Sin permiso para este procesador	Solicita que se active el permiso para el bank_code
429	Too Many Requests — Limite de velocidad excedido	Espera antes de reintentar. Revisa reglas de velocidad
500	Internal Server Error — Error del proveedor	Reintenta despues de unos segundos
501	Not Implemented — Procesador no disponible	Usa un bank_code soportado

Codigos de Respuesta PayBoom (P0X)

Estos codigos son generados por PayBoom cuando una transaccion es rechazada por reglas internas de velocidad, restricciones de monto u horario. Se reciben en el campo response_code de la respuesta.

Codigo	Descripcion	Accion recomendada
P00	Transaccion bloqueada por reglas de velocidad (generico)	Contacta a soporte para revisar las reglas configuradas
P01	Limite diario del comercio excedido	Espera al dia siguiente o solicita un aumento de limite diario
P02	Limite mensual del comercio excedido	Espera al siguiente mes o solicita un aumento de limite mensual
P03	Numero maximo de transacciones por tarjeta en 24 horas excedido	Espera 24 horas para reintentar con la misma tarjeta
P04	Tiempo minimo entre transacciones exitosas con la misma tarjeta no ha transcurrido	Espera el intervalo configurado antes de reintentar
P05	Tarjeta temporalmente bloqueada por multiples intentos fallidos	Espera el periodo de enfriamiento antes de reintentar
P06	Tarjeta permanentemente bloqueada	La tarjeta ha sido bloqueada. Usa una tarjeta diferente
P07	Monto de transaccion menor al minimo permitido / Transaccion fuera de horario	Verifica el monto minimo o el horario permitido (1:00 AM - 5:59 AM CDMX esta bloqueado)
P08	Monto de transaccion excede el maximo permitido por transaccion	Reduce el monto o solicita un aumento de limite
P09	Tarjetas con este BIN no estan permitidas	El BIN de la tarjeta esta bloqueado. Usa una tarjeta de otro banco/emisor

Codigos P0X y HTTP 429 Las transacciones rechazadas por reglas de velocidad (P01-P09) retornan HTTP 429 (Too Many Requests). Las transacciones fuera de horario (P07) retornan HTTP 200 con status DECLINED.

Formato de Notificacion al Comercio (Webhook)

PayBoom envia un POST a tu notifyUrl cuando el estado de la transaccion cambia. Tu endpoint debe responder con HTTP 200.

JSON — Payload del Webhook

{
  "payboom_reference": "pb_20260415120530123_93dfbb",
  "mchOrderNo": "ORD-2026-00123",
  "status": "APPROVED",
  "amount": "500.00",
  "currency": "MXN",
  "provider_reference": "PROVIDER-TX-789",
  "bank_code": "1001",
  "authorization": "AUTH123456",
  "raw": {
    // Respuesta original del proveedor (varia por procesador)
  }
}