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

{
  "success": true,
  "payboom_reference": "pb_20260827120530123_93dfbb",
  "mchOrderNo": "ORD-2026-00456",
  "amount": 500.00,
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/payboom",
  "bank_response": {
    "clabe": "703010520043000151",
    "bank_name": "TESORED",
    "beneficiary": "PAYBOOM",
    "expires_at": "2026-08-29T05:57:52Z",
    "provider_reference": "mm_gOSG3A5yEPKuP1",
    "raw": { "...": "..." }
  }
}

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.

{
  "api_key_id": 2007,
  "payboom_reference": "pb_20260415120530123_93dfbb",
  "provider_reference": "PROVIDER-TX-789456",
  "reference": "ORD-2026-00123",
  "bank_code": "1001",
  "amount": 500.00,
  "currency": "MXN",
  "status": "deposit"
}

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

Recurring Card Plans (UNLIMIT)

Planes de Tarjeta Recurrente (UNLIMIT)

The /recurrenceplan endpoint creates a recurring billing plan and subscribes a card to it via UNLIMIT. The first charge happens immediately as part of this call; UNLIMIT executes every following charge on its own schedule and notifies each result via notifyUrl, the same way Direct Card webhooks work.

El endpoint /recurrenceplan crea un plan de cobro recurrente y suscribe una tarjeta via UNLIMIT. El primer cobro ocurre de inmediato como parte de este mismo llamado; UNLIMIT ejecuta cada cobro siguiente segun su propio calendario y notifica cada resultado via notifyUrl, igual que los webhooks de Direct Card.

{
  "bank_code": "1021",
  "amount": 199.00,
  "id": "SUB-2026-00042",
  "currency": "MXN",
  "recurrence": "monthly",
  "plan_name": "Plan Premium Mensual",
  "notifyUrl": "https://mi-sitio.com/webhook/payboom",
  "successUrl": "https://mi-sitio.com/suscripcion/exito",
  "errorUrl": "https://mi-sitio.com/suscripcion/error",
  "email": "cliente@example.com",
  "shopper": {
    "first_name": "Juan",
    "last_name": "Perez",
    "phone": "5551234567",
    "state": "CDMX",
    "city": "CDMX",
    "address": "Av. Reforma 1",
    "postal_code": "06000",
    "customer_ip": "201.100.10.5"
  },
  "card": {
    "holderName": "JUAN PEREZ",
    "cardNumber": "4111111111111111",
    "expiryYear": "2028",
    "expiryMonth": "12",
    "cvv": "123"
  }
}

{
  "success": true,
  "status": "APPROVED",
  "authorization": "",
  "payboom_reference": "pb_20260827120530123_93dfbb",
  "mchOrderNo": "SUB-2026-00042",
  "provider_reference": "REC-9001",
  "plan_id": "PLAN-4521",
  "subscription_id": "SUB-3312",
  "recurrence": "monthly",
  "amount": "199.00",
  "currency": "MXN",
  "notifyUrl": "https://mi-sitio.com/webhook/payboom",
  "redirect_url": "",
  "bank_response": { "...": "..." }
}

curl -X POST https://api.payboom.io/recurrenceplan \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_code": "1021",
    "amount": 199.00,
    "id": "SUB-2026-00042",
    "currency": "MXN",
    "recurrence": "monthly",
    "plan_name": "Plan Premium Mensual",
    "notifyUrl": "https://mi-sitio.com/webhook/payboom",
    "email": "cliente@example.com",
    "shopper": { "...": "..." },
    "card": { "...": "..." }
  }'

Direct Link — Colombia Payins (Cobre)

Direct Link — Payins Colombia (Cobre)

The /directlink endpoint creates payins in Colombia through Cobre Direct Link. Unlike /directbank, the merchant sends a payment type (slug) instead of a bank_code.

El endpoint /directlink crea payins en Colombia a traves de Cobre Direct Link. A diferencia de /directbank, el comercio envia un type (slug) de metodo de pago en lugar de un bank_code.

{
  "type": "pse",
  "amount": 50000,
  "currency": "COP",
  "mchOrderNo": "ORD-1",
  "notifyUrl": "https://tu-sitio/webhook",
  "email": "pagador@x.com",
  "financial_institution_code": "1070",
  "redirect_url": "https://tu-sitio/ok"
}

{
  "success": true,
  "payboom_reference": "pb_20260720120000000_ab12cd",
  "provider_reference": "mm_bNCf3W9mdA062D",
  "type": "pse",
  "status": "PENDING",
  "instruction": {
    "type": "payment_link",
    "url": "https://registro.pse.com.co/PSENF/index.html?enc=_XXXX",
    "qr_value": null,
    "key_value": null,
    "expires_at": "2026-07-20T12:10:00Z"
  }
}

curl -X POST https://api.payboom.io/directlink \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pse",
    "amount": 50000,
    "currency": "COP",
    "email": "pagador@x.com",
    "financial_institution_code": "1070",
    "redirect_url": "https://tu-sitio/ok",
    "mchOrderNo": "ORD-1",
    "notifyUrl": "https://tu-sitio/webhook"
  }'

{
  "banks": [
    { "financial_institution_code": "1070", "name": "Lulo Bank" },
    { "financial_institution_code": "1007", "name": "Bancolombia" }
  ]
}

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

Withdrawals

Retiros

Six endpoints to check your balance, request a withdrawal to your registered CLABE, list and track withdrawals, manage the destination account, and receive the execution webhook. All require Authorization: Bearer {api_key} and permission on the requested bank_code, same as the rest of this API.

Seis endpoints para consultar tu saldo, solicitar un retiro a tu CLABE registrada, listar y rastrear retiros, administrar la cuenta destino, y recibir el webhook de ejecucion. Todos requieren Authorization: Bearer {api_key} y permiso sobre el bank_code solicitado, igual que el resto de esta API.

curl "https://api.payboom.io/balance?bank_code=1025" \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "bank_code": "1025",
  "bankname": "SPEI MXN",
  "currency": "MXN",
  "available_cents": 500000,
  "withdrawable_cents": 496500
}

{
  "amount": 4965.00,
  "bank_code": "1025",
  "notify_url": "https://mi-sitio.com/webhook/retiros",
  "reference": "order-8842"
}

{
  "id": 4821,
  "amount_cents": 496500,
  "status": "executed",
  "currency": "MXN",
  "commission_cents": 500,
  "iva_cents": 80,
  "total_debited_cents": 497080,
  "method": "spei",
  "provider_reference": "SP-99213",
  "error_message": null,
  "executed_at": "2026-08-31T10:22:04.881000+00:00",
  "bank_code": "1025",
  "clabe": "012180001234567895",
  "notify_url": "https://mi-sitio.com/webhook/retiros",
  "reference": "order-8842"
}

curl -X POST https://api.payboom.io/withdrawals \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4965.00,
    "bank_code": "1025",
    "notify_url": "https://mi-sitio.com/webhook/retiros",
    "reference": "order-8842"
  }'

{
  "error": "insufficient_balance",
  "required_cents": 100530,
  "available_cents": 100000
}

curl "https://api.payboom.io/withdrawals?status=executed&from=2026-08-01&page=1" \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "page": 1,
  "per_page": 50,
  "total": 1,
  "total_pages": 1,
  "items": [
    {
      "id": 4821,
      "status": "executed",
      "method": "spei",
      "bank_code": "1025",
      "currency": "MXN",
      "amount_cents": 496500,
      "commission_cents": 500,
      "iva_cents": 80,
      "net_cents": 496500,
      "total_debited_cents": 497080,
      "reference": "order-8842",
      "clabe": "012180001234567895",
      "bank_name": "STP",
      "provider_reference": "ORD-2026-00821",
      "error_message": null,
      "created_at": "2026-08-20T10:15:00.123000",
      "executed_at": "2026-08-20T10:15:42.501000"
    }
  ]
}

curl https://api.payboom.io/withdrawals/4821 \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "id": 4821,
  "status": "executed",
  "method": "spei",
  "bank_code": "1025",
  "currency": "MXN",
  "amount_cents": 496500,
  "commission_cents": 500,
  "iva_cents": 80,
  "net_cents": 496500,
  "total_debited_cents": 497080,
  "reference": "order-8842",
  "clabe": "012180001234567895",
  "bank_name": "STP",
  "provider_reference": "ORD-2026-00821",
  "error_message": null,
  "created_at": "2026-08-20T10:15:00.123000",
  "executed_at": "2026-08-20T10:15:42.501000"
}

{
  "clabe": "012180001234567895",
  "bank_name": "STP"
}

{
  "configured": true,
  "clabe": "012180001234567895",
  "bank_name": "STP"
}

curl -X PUT https://api.payboom.io/withdrawal-account \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"clabe": "012180001234567895", "bank_name": "STP"}'

Withdrawal Webhook

Webhook de Retiro

When a withdrawal you sent a notify_url for reaches executed or failed, PayBoom sends one POST to that URL with the exact same JSON GET /withdrawals/{id} returns.

Cuando un retiro al que le enviaste notify_url llega a executed o failed, PayBoom manda un POST a esa URL con el mismo JSON exacto que retorna GET /withdrawals/{id}.

{
  "id": 4821,
  "status": "executed",
  "method": "spei",
  "bank_code": "1025",
  "currency": "MXN",
  "amount_cents": 496500,
  "commission_cents": 500,
  "iva_cents": 80,
  "net_cents": 496500,
  "total_debited_cents": 497080,
  "reference": "order-8842",
  "clabe": "012180001234567895",
  "bank_name": "STP",
  "provider_reference": "ORD-2026-00821",
  "error_message": null,
  "created_at": "2026-08-20T10:15:00.123000",
  "executed_at": "2026-08-20T10:15:42.501000"
}

Query Endpoints

Endpoints de Consulta

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

curl "https://api.payboom.io/cashbanks?country_code=MX&bank_code=1009" \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "data": [
    { "bank_id": "...", "...": "..." }
  ]
}

curl "https://api.payboom.io/operations?from=2026-07-01&to=2026-07-17&status=deposit&page=1" \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "page": 1,
  "per_page": 50,
  "total": 128,
  "total_pages": 3,
  "items": [
    {
      "payboom_reference": "pb_20260415120530123_93dfbb",
      "reference": "ORD-2026-00123",
      "provider_reference": "PROVIDER-TX-789",
      "bank_code": "1003",
      "type": "directbank",
      "amount": 500.00,
      "currency": "MXN",
      "status": "deposit",
      "settled": true,
      "created_at": "2026-04-15T12:05:30.123000",
      "notification": {
        "api_key_id": 2021,
        "payboom_reference": "pb_20260415120530123_93dfbb",
        "provider_reference": "PROVIDER-TX-789",
        "reference": "ORD-2026-00123",
        "bank_code": "1003",
        "amount": 500.00,
        "currency": "MXN",
        "status": "deposit"
      }
    }
  ]
}

curl https://api.payboom.io/operations/pb_20260717091000123_ab12cd \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "payboom_reference": "pb_20260415120530123_93dfbb",
  "reference": "ORD-2026-00123",
  "provider_reference": "PROVIDER-TX-789",
  "bank_code": "1003",
  "type": "directbank",
  "amount": 500.00,
  "currency": "MXN",
  "status": "deposit",
  "settled": true,
  "created_at": "2026-04-15T12:05:30.123000",
  "notification": {
    "api_key_id": 2021,
    "payboom_reference": "pb_20260415120530123_93dfbb",
    "provider_reference": "PROVIDER-TX-789",
    "reference": "ORD-2026-00123",
    "bank_code": "1003",
    "amount": 500.00,
    "currency": "MXN",
    "status": "deposit"
  }
}

{
  "mchOrderNo": "ORD-2026-00123"
}

{
  "success": true,
  "raw": {
    "resCode": "SUCCESS",
    "...": "..."
  }
}

curl -X POST https://api.payboom.io/payment \
  -H "Content-Type: application/json" \
  -d '{"mchOrderNo": "ORD-2026-00123"}'

Crossborder — Global Payment (VelaFi)

Crossborder — Global Payment (VelaFi)

The /crossborder family of endpoints moves money between fiat currencies through VelaFi: you fund a per-currency balance from your PayBoom operations, register a recipient in the destination country, and send a fiat-to-fiat transfer that VelaFi converts and pays out. This is a separate product from Direct Bank / Direct Card and from Cobre's MX↔CO transfer — it does not share endpoints, balances, or references with them.

La familia de endpoints /crossborder mueve dinero entre monedas fiat a traves de VelaFi: fondeas una bolsa por moneda desde tus operaciones en PayBoom, registras un destinatario en el pais destino, y envias una transferencia fiat-a-fiat que VelaFi convierte y paga. Es un producto separado de Direct Bank / Direct Card y del traspaso MX↔CO de Cobre — no comparte endpoints, bolsas ni referencias con ellos.

Supported Corridors

Corredores Soportados

A corridor is a (country, currency) pair on each side. Only the combinations below are accepted — anything else fails with unsupported_corridor.

Un corredor es un par (pais, moneda) de cada lado. Solo se aceptan las combinaciones de abajo — cualquier otra falla con unsupported_corridor.

Transfer Lifecycle

Ciclo de Vida de una Transferencia

A transfer's status is always one of the values below. docs_required/docs_review are compliance holds, not failures: funds stay reserved and no deadline runs while a transfer sits there.

El status de una transferencia siempre es uno de los valores de abajo. docs_required/docs_review son retenciones de cumplimiento, no fallas: los fondos siguen reservados y no corre ningun plazo mientras la transferencia esta ahi.

curl "https://api.payboom.io/crossborder/rails?from=MXN&to=COP" \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "onRampCountry": "Mexico",
  "onRampFiat": "MXN",
  "offRampCountry": "Colombia",
  "offRampFiat": "COP",
  "paymentListFrom": [ { "paymentId": 105, "...": "..." } ],
  "paymentListTo": [ { "paymentId": 18, "...": "..." } ],
  "corridorSupported": true
}

curl https://api.payboom.io/crossborder/balances \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "record": [
    {
      "merchantId": 8801,
      "fiat": "MXN",
      "label": "Pesos Mexicanos",
      "balance": "5000.00",
      "status": 2,
      "source": "payin",
      "icon": "account_balance",
      "availableMinor": 500000
    }
  ]
}

curl "https://api.payboom.io/crossborder/quote?from=MXN&to=ARS&amount=1000" \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{
  "price": "180",
  "quoteId": "",
  "onRampCountry": "Mexico",
  "onRampFiat": "MXN",
  "offRampCountry": "Argentina",
  "offRampFiat": "ARS",
  "quoted_dest_amount_minor": 18000000,
  "commission_minor": 2500,
  "iva_minor": 400,
  "source_amount_minor": 100000
}

curl https://api.payboom.io/crossborder/recipients \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

{ "record": [ { "id": 42, "...": "see the recipient object below" } ] }

{
  "alias": "Proveedor Bogota SAS",
  "country": "Colombia",
  "currency": "COP",
  "rail": 18,
  "fields": { "account_number": "1234567890", "document_id": "900123456" }
}

{
  "id": 42,
  "merchantId": 8801,
  "country": "Colombia",
  "fiat": "COP",
  "paymentId": 18,
  "paymentMethodName": "Proveedor Bogota SAS",
  "realName": "Proveedor Bogota SAS",
  "status": 2,
  "statusKey": "pending_verification",
  "fieldList": { "account_number": "1234567890", "document_id": "900123456" },
  "failReason": "",
  "maskedAccount": "****7890",
  "providerPaymentId": "228",
  "createTime": "1798564530123"
}

curl -X POST https://api.payboom.io/crossborder/recipients \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Proveedor Bogota SAS",
    "country": "Colombia",
    "currency": "COP",
    "rail": 18,
    "fields": { "account_number": "1234567890", "document_id": "900123456" }
  }'

{ "alias": "Proveedor Bogota SAS (nuevo nombre)" }

curl -X PATCH https://api.payboom.io/crossborder/recipients/42 \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"alias": "Proveedor Bogota SAS (nuevo nombre)"}'

{
  "recipient_id": 42,
  "amount": "1000.00",
  "source_currency": "MXN",
  "onRampCountry": "Mexico",
  "notify_url": "https://mi-sitio.com/webhook/crossborder"
}

{
  "orderId": "ord-77291",
  "clientId": "payboom-gp-3f7a9c1e2b4d5f60",
  "onRampCountry": "Mexico",
  "onRampFiat": "MXN",
  "onRampFiatAmount": "1000.00",
  "onRampFiatFee": "0",
  "onRampPaymentId": 70,
  "offRampCountry": "Colombia",
  "offRampFiat": "COP",
  "offRampFiatAmount": "180000.00",
  "offArriveRampFiatAmount": "180000.00",
  "offRampFiatFee": "0",
  "offRampPaymentId": 228,
  "orderPrice": "180",
  "orderStatus": 41,
  "failReason": "",
  "failCode": "",
  "status": "pending",
  "recipientName": "Proveedor Bogota SAS",
  "recipientId": 42,
  "createTime": "1798564530123",
  "completedTime": "",
  "mid": 8801,
  "quotedRate": "180",
  "appliedRate": "",
  "commission": "25.00",
  "iva": "4.00",
  "retryOf": null,
  "reference": "payboom-gp-3f7a9c1e2b4d5f60"
}

curl -X POST https://api.payboom.io/crossborder \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": 42,
    "amount": "1000.00",
    "source_currency": "MXN",
    "notify_url": "https://mi-sitio.com/webhook/crossborder"
  }'

curl https://api.payboom.io/crossborder/payboom-gp-3f7a9c1e2b4d5f60 \
  -H "Authorization: Bearer pb_ak_your_api_key_here"

curl -X POST https://api.payboom.io/crossborder/payboom-gp-3f7a9c1e2b4d5f60/retry \
  -H "Authorization: Bearer pb_ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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.

{
  "api_key_id": 2007,
  "payboom_reference": "pb_20260415120530123_93dfbb",
  "provider_reference": "PROVIDER-TX-789",
  "reference": "ORD-2026-00123",
  "bank_code": "1001",
  "amount": 500.00,
  "currency": "MXN",
  "status": "deposit"
}