Payments - Cobrix Docs

Create Hosted Payment

Crea un pago que redirige al cliente al checkout de Cobrix.

POST /api/external/payments

Headers

Header	Requerido	Descripción
`X-API-Key`	✅	API key de la empresa
`Idempotency-Key`	✅	UUID v4 único por request
`Content-Type`	✅	`application/json`

Body

customerEmail

string

required

Email del cliente (se usa para encontrar o crear al cliente).

customerName

string

Nombre del cliente (máx. 200 caracteres).

amountMinor

integer

required

Monto en unidades menores (debe ser > 0).

currency

string

required

Código ISO 4217: VES, USD o CRC.

description

string

Descripción del pago (máx. 500 caracteres).

callbackUrl

string

URL a la que Cobrix enviará el webhook.

externalReference

string

Referencia interna de tu sistema (máx. 255 caracteres).

metadata

object

Pares clave-valor arbitrarios.

curl -X POST "https://api.cobrix.co/api/external/payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_acme_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerEmail": "[email protected]",
    "customerName": "Jane Doe",
    "amountMinor": 15000,
    "currency": "VES",
    "description": "Suscripción mensual",
    "callbackUrl": "https://tu-app.com/webhooks/cobrix"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "mode": "hosted",
  "amountMinor": 15000,
  "currency": "VES",
  "description": "Suscripción mensual",
  "customerEmail": "[email protected]",
  "customerName": "Jane Doe",
  "checkoutUrl": "https://checkout.cobrix.co/checkout/eyJhbGci...",
  "invoiceId": "inv-uuid",
  "externalReference": "order-123",
  "expiresAt": "2026-03-27T14:30:00.000Z",
  "createdAt": "2026-03-26T14:30:00.000Z"
}

Los pagos hosted expiran a las 24 horas y pasan automáticamente al estado expired.

Create Direct Payment

Crea un pago que se completa de inmediato (backend-to-backend, sin interacción del cliente).

POST /api/external/payments/direct

Headers

Iguales a Create Hosted Payment.

Body

customerEmail

string

required

Email del cliente.

customerName

string

Nombre del cliente (máx. 200 caracteres).

amountMinor

integer

required

Monto en unidades menores.

currency

string

required

VES, USD o CRC.

paymentMethod

string

required

Método de pago (ver tabla abajo).

paymentDetails

object

Metadatos específicos del método.

description

string

Descripción (máx. 500 caracteres).

callbackUrl

string

URL del webhook.

externalReference

string

Referencia interna (máx. 255 caracteres).

metadata

object

Pares clave-valor arbitrarios.

Métodos de pago soportados

Valor	Moneda	Descripción
`pago_movil`	VES	Pago Móvil (Venezuela)
`bank_transfer`	VES	Transferencia bancaria (Venezuela)
`zelle`	USD	Zelle
`binance`	USD	Binance / cripto
`sinpe`	CRC	SINPE Móvil (Costa Rica)
`sinpe_transferencia`	CRC	SINPE Transferencia (Costa Rica)
`cash`	—	Efectivo genérico
`cash_usd`	USD	Efectivo en USD
`cash_ves`	VES	Efectivo en VES
`card`	—	Tarjeta
`paypal`	USD	PayPal
`c2p`	—	Pago C2P
`wallet`	—	Billetera digital
`other`	—	Otro

curl -X POST "https://api.cobrix.co/api/external/payments/direct" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_acme_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerEmail": "[email protected]",
    "amountMinor": 15000,
    "currency": "VES",
    "paymentMethod": "pago_movil",
    "description": "POS #456",
    "externalReference": "pos-456"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "mode": "direct",
  "amountMinor": 15000,
  "currency": "VES",
  "customerEmail": "[email protected]",
  "invoiceId": "inv-uuid",
  "paymentId": "pay-uuid",
  "externalReference": "pos-456",
  "expiresAt": "2026-03-27T14:30:00.000Z",
  "completedAt": "2026-03-26T14:30:00.000Z",
  "createdAt": "2026-03-26T14:30:00.000Z"
}

Los pagos directos regresan con status: "completed" inmediatamente. Si se proporciona callbackUrl, también se despacha un webhook.

Get Payment

GET /api/external/payments/{id}

Headers

Header	Requerido
`X-API-Key`	✅

curl "https://api.cobrix.co/api/external/payments/{id}" \
  -H "X-API-Key: sk_live_acme_..."

{
  "id": "a1b2c3d4-...",
  "status": "completed",
  "mode": "hosted",
  "amountMinor": 15000,
  "currency": "VES",
  "completedAt": "2026-03-26T14:45:00.000Z"
}

Código	Razón
`404`	Pago no encontrado o pertenece a otra empresa

List Payments

GET /api/external/payments

Headers

Header	Requerido
`X-API-Key`	✅

Query parameters

Parámetro	Tipo	Default	Descripción
`status`	string	—	`pending`, `processing`, `completed`, `failed`, `expired`, `canceled`
`mode`	string	—	`hosted` o `direct`
`from`	string	—	Fecha ISO 8601 (inclusive)
`to`	string	—	Fecha ISO 8601 (inclusive)
`page`	integer	`1`	Número de página
`limit`	integer	`20`	Elementos por página

curl "https://api.cobrix.co/api/external/payments?status=pending&mode=hosted&page=1&limit=20" \
  -H "X-API-Key: sk_live_acme_..."

{
  "payments": [
    { "id": "...", "status": "pending", "mode": "hosted" },
    { "id": "...", "status": "completed", "mode": "direct" }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Cancel Payment

Cancela un pago en estado pending. No es posible cancelar pagos en otros estados.

DELETE /api/external/payments/{id}

Headers

Header	Requerido
`X-API-Key`	✅

curl -X DELETE "https://api.cobrix.co/api/external/payments/{id}" \
  -H "X-API-Key: sk_live_acme_..."

{
  "id": "a1b2c3d4-...",
  "status": "canceled",
  "mode": "hosted"
}

Código	Razón
`404`	Pago no encontrado
`409`	Pago no está en estado `pending`

Ciclo de vida del pago

             ┌───────────┐
             │  pending  │
             └─────┬─────┘
                   │
        ┌──────────┼──────────┬──────────┐
        ▼          ▼          ▼          ▼
  ┌──────────┐ ┌────────┐ ┌──────────┐ ┌────────────┐
  │processing│ │expired │ │ canceled │ │ completed  │
  └─────┬────┘ └────────┘ └──────────┘ └────────────┘
        │                            (solo modo direct)
    ┌───┴────┐
    ▼        ▼
┌─────────┐ ┌───────┐
│completed│ │failed │
└─────────┘ └───────┘

Estado	Terminal	Descripción
`pending`	No	Pago creado, esperando acción del cliente (hosted)
`processing`	No	Cliente envió el pago, en verificación
`completed`	Sí	Pago exitoso
`failed`	Sí	Pago fallido
`expired`	Sí	Timeout de 24h (modo hosted)
`canceled`	Sí	Cancelado vía `DELETE`

Diferencias por modo

	Hosted	Direct
Estado inicial	`pending`	`completed`
Interacción del cliente	Sí	No
`checkoutUrl`	Sí	No
`paymentId`	Al completarse	Inmediato
Expiración	24h	24h (ya completado)

Documentation Index

​Create Hosted Payment

​Headers

​Body

​Create Direct Payment

​Headers

​Body

​Métodos de pago soportados

​Get Payment

​Headers

​List Payments

​Headers

​Query parameters

​Cancel Payment

​Headers

​Ciclo de vida del pago

​Diferencias por modo

Create Hosted Payment

Headers

Body

Create Direct Payment

Headers

Body

Métodos de pago soportados

Get Payment

Headers

List Payments

Headers

Query parameters

Cancel Payment

Headers

Ciclo de vida del pago

Diferencias por modo