PayBoom API Reference v1.0

Unified REST API for payment processing in Mexico. Integrates multiple payment processors under a single technical interface: bank transfers, cash and in-store payments, referenced deposits, and credit/debit cards with 3D Secure support.

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.

Base URL

Quick Start

1. Get your API Key
   Request your integration credentials. You will receive an api_key with format pb_ak_... and a MID (Merchant ID).
   Obtener tu API Key
   Solicita tus credenciales de integracion. Recibiras un api_key con formato pb_ak_... y un MID (Merchant ID).
2. Choose a payment method
   Use POST /directbank for transfers and cash, or POST /directcard for credit/debit cards.
   Elegir metodo de pago
   Usa POST /directbank para transferencias y efectivo, o POST /directcard para tarjetas de credito/debito.
3. Redirect the payer
   For DirectBank, redirect the user to the URL received in bank_response.url. For DirectCard, process the response or redirect to the 3DS challenge.
   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.
4. Receive notification
   PayBoom will send a POST to your notifyUrl when the payment changes state.
   Recibir notificacion
   PayBoom enviara un POST a tu notifyUrl cuando el pago cambie de estado.

Architecture

Arquitectura

Your merchant integrates a single API. PayBoom routes to the corresponding processor based on the bank_code. Check the bank directory for available codes.

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.

Authentication

Autenticacion

All endpoints require authentication via a Bearer Token in the Authorization header.

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

Authorization: Bearer pb_ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Permissions per Bank

Permisos por Banco

Each API Key has specific permissions per payment processor (bank_code). If you try to use a processor without permission, you will receive a 403 error.

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

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

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

Direct Bank — Transfers & Cash

Direct Bank — Transferencias y Efectivo

The /directbank endpoint allows creating payments through methods other than card: bank transfers, in-store payments, referenced deposits, and cash payments. Each service is activated with a different bank_code.

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.

Payment Channels

Canales de Pago

PayBoom supports several payment channels through /directbank. The channel is determined by the bank_code you send in the request.

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

{
  "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"
  }
}

{
  "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 -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"
    }
  }'

Payment Flow

Flujo de Pago

Regardless of the payment channel, the flow always follows the same pattern:

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

Webhooks — Payment Notifications

Webhooks — Notificaciones de Pago

When a payment's status changes, PayBoom sends a POST to the URL you specified in notifyUrl. Never assume a payment was successful based on the redirect; always wait for the webhook confirmation.

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.

{
  "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"
}

Direct Card — Card Payments

Direct Card — Pagos con Tarjeta

The /directcard endpoint allows processing credit and debit card payments. There are two possible payment flows:

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

Authorization & Capture (Traditional Payment)

Autorizacion y Captura (Pago Tradicional)

In the traditional flow, authorization and capture are done in a single request. The response is immediate: APPROVED or DECLINED. No user redirect required.

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.

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
  }
}

3D Secure (3DS) Payment

Pago con 3D Secure (3DS)

Some processors require 3D Secure authentication. When the processor determines issuer-bank verification is needed, the response includes a redirect_url where you must redirect the user to complete the challenge.

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.

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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"
}

State Flow — 3DS

Flujo de estados — 3DS

Webhooks & Callbacks (Cards)

Webhooks y Callbacks (Tarjetas)

PayBoom handles two notification mechanisms for card payments:

PayBoom maneja dos mecanismos de notificacion para pagos con tarjeta:

/directcard endpoint errors

Errores del endpoint /directcard

Cancel & RefundCancelar y Reembolsar

The cancel and refund endpoints allow reversing approved transactions. Availability of these operations depends on the processor assigned to each bank_code.

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

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

{
  "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": {}
}

Query Endpoints

Endpoints de Consulta

{
  "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"
    }
  ]
}

Reference — Transaction StatusesReferencia — Estados de Transaccion

HTTP Error CodesCodigos de Error HTTP

PayBoom Response Codes (P0X)Codigos de Respuesta PayBoom (P0X)

These codes are generated by PayBoom when a transaction is rejected by internal velocity, amount, or schedule rules. They are received in the response_code field of the response.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.

Merchant Notification Format (Webhook)Formato de Notificacion al Comercio (Webhook)

PayBoom sends a POST to your notifyUrl when the transaction status changes. Your endpoint must respond with HTTP 200.PayBoom envia un POST a tu notifyUrl cuando el estado de la transaccion cambia. Tu endpoint debe responder con HTTP 200.

{
  "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)
  }
}