API de Pagos Unificada

La API de Pagos Unificada (versión 6) permite procesar transacciones con cualquier red de tarjeta — Visa, Mastercard y American Express — enviando exactamente el mismo body. El servidor detecta automáticamente la red a partir del número de tarjeta y enruta la operación al procesador correspondiente.

Autenticación

Todos los endpoints de esta API requieren un JWT enviado en el header Authorization.

Paso 1 — Obtener el token

POST /api/v2/auth
Content-Type: application/json

Body:

Campo	Tipo	Requerido	Descripción
`correo`	string	Sí	Correo electrónico del usuario
`contrasena`	string	Sí	Contraseña del usuario

Ejemplo:

curl -X POST https://webserver.zigu.mx/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "correo": "usuario@ejemplo.com",
    "contrasena": "tu-contrasena"
  }'

Respuesta exitosa (200):

{
  "payload": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Respuesta de error (401):

"Usuario y/o contraseña incorrecto"

El token tiene una vigencia de 24 horas y está firmado con APP_SECRET.

Paso 2 — Incluir el token en cada petición

Añade el header Authorization con el prefijo BMToken seguido del token obtenido:

Authorization: BMToken eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

caution

Si el token está ausente, expirado o inválido, el servidor responde con 401 { "error": "No autorizado" }.

POST `/api/v6/payment/charge`

Procesa un cobro. La red de la tarjeta se detecta automáticamente.

URL: POST /api/v6/payment/charge
Autenticación: Authorization: BMToken <token>
Content-Type: application/json

Parámetros del body

Campos obligatorios

Campo	Tipo	Descripción
`cardNumber`	string	Número completo de la tarjeta (PAN)
`expiryMonth`	string	Mes de vencimiento (`MM`, ej. `"07"`)
`expiryYear`	string	Año de vencimiento (`YY` o `YYYY`, ej. `"26"` o `"2026"`)
`amount`	number	Monto a cobrar en pesos con hasta 2 decimales (ej. `150.35`)
`orderId`	string	Identificador único del pedido en tu sistema
`customerEmail`	string	Correo electrónico del cliente
`businessId`	string	ID del negocio registrado en la plataforma

Campos opcionales — Datos del cliente

Campo	Tipo	Descripción
`cvv`	string	Código de seguridad de la tarjeta
`customerFirstName`	string	Nombre del cliente
`customerLastName`	string	Apellido del cliente
`customerIp`	string	IP del cliente (solo aplica para Visa/Mastercard)
`currency`	string	Moneda. Default: `"MXN"`

Campos opcionales — Dirección de facturación (solo Visa/Mastercard)

Estos campos solo se envían al procesador cuando la tarjeta no es Amex.

Campo	Tipo	Descripción
`billingAddress`	string	Dirección (calle y número)
`billingCity`	string	Ciudad
`billingState`	string	Estado
`billingZip`	string	Código postal
`billingCountry`	string	País en formato ISO 3166-1 alpha-2. Default: `"MX"`

Campos opcionales — 3D Secure

Aplican tanto para Amex como para Visa/Mastercard.

Campo	Tipo	Descripción
`authenticationValue`	string	Valor de autenticación 3DS (CAVV/AAV)
`eci`	string	Electronic Commerce Indicator. Default: `"05"` si se incluye `authenticationValue`

Campos opcionales — Meses sin intereses (MSI)

Campo	Tipo	Descripción
`planType`	string	Tipo de plan de financiamiento
`installments`	number	Número de meses. Default: `1`

Ejemplos

Cobro básico (Visa o Mastercard):

curl -X POST https://webserver.zigu.mx/api/v6/payment/charge \
  -H "Authorization: BMToken eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "26",
    "cvv": "123",
    "amount": 500.00,
    "currency": "MXN",
    "orderId": "ORDEN-001",
    "customerEmail": "cliente@ejemplo.com",
    "customerFirstName": "Juan",
    "customerLastName": "García",
    "businessId": "clbusiness123",
    "billingAddress": "Av. Insurgentes 1234",
    "billingCity": "Ciudad de México",
    "billingState": "CDMX",
    "billingZip": "06600",
    "billingCountry": "MX"
  }'

Cobro con tarjeta Amex (mismo endpoint, sin datos de dirección):

curl -X POST https://webserver.zigu.mx/api/v6/payment/charge \
  -H "Authorization: BMToken eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "378282246310005",
    "expiryMonth": "12",
    "expiryYear": "26",
    "cvv": "1234",
    "amount": 500.00,
    "orderId": "ORDEN-002",
    "customerEmail": "cliente@ejemplo.com",
    "businessId": "clbusiness123"
  }'

Cobro con 3D Secure:

curl -X POST https://webserver.zigu.mx/api/v6/payment/charge \
  -H "Authorization: BMToken eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "26",
    "amount": 1200.00,
    "orderId": "ORDEN-003",
    "customerEmail": "cliente@ejemplo.com",
    "businessId": "clbusiness123",
    "authenticationValue": "AAABBkIgAAAAAAAAQxhAAAAAAAA=",
    "eci": "05"
  }'

Cobro a meses sin intereses:

curl -X POST https://webserver.zigu.mx/api/v6/payment/charge \
  -H "Authorization: BMToken eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "26",
    "amount": 3600.00,
    "orderId": "ORDEN-004",
    "customerEmail": "cliente@ejemplo.com",
    "businessId": "clbusiness123",
    "planType": "MSI",
    "installments": 12
  }'

Respuesta exitosa (`200`)

{
  "success": true,
  "transactionId": "1234567890",
  "status": "APPROVED",
  "statusMessage": "APPROVED",
  "authCode": "ABC123",
  "amount": 500.00,
  "currency": "MXN",
  "orderId": "ORDEN-001",
  "cardBrand": "VISA",
  "last4": "1111",
  "apiResponse": "00",
  "apiAdvice": ""
}

Campo	Tipo	Descripción
`success`	boolean	`true` si la transacción fue aprobada
`transactionId`	string	ID de la transacción en el procesador (usar para reversos)
`status`	string	Estado de la transacción (`APPROVED`, `DECLINED`, etc.)
`statusMessage`	string	Descripción del estado
`authCode`	string	Código de autorización del procesador
`amount`	number	Monto cobrado
`currency`	string	Moneda
`orderId`	string	Identificador del pedido enviado en el request
`cardBrand`	string	Red detectada: `VISA`, `MASTERCARD` o `AMEX`
`last4`	string	Últimos 4 dígitos de la tarjeta
`apiResponse`	string	Código de respuesta interno del gateway
`apiAdvice`	string	Mensaje de asesoría del gateway

Códigos de error

Código HTTP	Causa	Respuesta
`400`	Parámetros inválidos o faltantes	`{ "error": "mensaje de validación" }`
`400`	Red de tarjeta no reconocida	`{ "error": "Marca de tarjeta no reconocida" }`
`401`	Token ausente o inválido	`{ "error": "No autorizado" }`
`404`	`businessId` no existe	`{ "error": "Negocio no encontrado" }`
`502`	Fallo en la tokenización de la tarjeta	`{ "error": "No se pudo tokenizar la tarjeta", "detail": {...} }`
`500`	Error interno del servidor	`{ "error": "mensaje de error" }`

Notas importantes

Formato del monto: siempre en pesos mexicanos con hasta 2 decimales (ej. 150.35). El servidor lo normaliza internamente a "150.35" antes de enviarlo al gateway.
Conserva el transactionId: el valor transactionId de la respuesta del cobro es el que debes usar en los endpoints de /reverse. Corresponde al TRANS_ID del gateway.
Redes soportadas: solo se aceptan tarjetas Visa (4...), Mastercard (51–55... / 22–27...) y American Express (34... / 37...).
Vigencia del token JWT: 24 horas. Repite el flujo de autenticación una vez vencido.

API de Pagos Unificada

Autenticación​

Paso 1 — Obtener el token​

Paso 2 — Incluir el token en cada petición​

POST /api/v6/payment/charge​

Parámetros del body​

Campos obligatorios​

Campos opcionales — Datos del cliente​

Campos opcionales — Dirección de facturación (solo Visa/Mastercard)​

Campos opcionales — 3D Secure​

Campos opcionales — Meses sin intereses (MSI)​

Ejemplos​

Respuesta exitosa (200)​

Códigos de error​

Notas importantes​