Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt

Use this file to discover all available pages before exploring further.

El modo hosted genera un link de checkout al cual rediriges al cliente. Cobrix se encarga de renderizar el formulario, capturar el método de pago y notificarte vía webhook.

​
Diagrama del flujo

​
Paso 1 · Crear el pago

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",
    "externalReference": "order-123",
    "metadata": { "source": "web" }
  }'

​
Campos importantes

CampoUso
customerEmailIdentifica al cliente. Si no existe, se crea automáticamente.
amountMinorMonto en unidades menores (10000 = 100,00).
currencyVES, USD o CRC.
callbackUrlURL absoluta HTTPS a la que llegará el webhook.
externalReferenceÚtil para conciliar con tu sistema.

​
Paso 2 · Redirigir al cliente

window.location.href = payment.checkoutUrl
El cliente completa el pago en el checkout de Cobrix. El estado del pago pasa de pending → processing → completed (o failed).
Los pagos hosted expiran a las 24 horas. Pasado ese tiempo el estado cambia a expired.

​
Paso 3 · Recibir el webhook

Al completarse el pago, Cobrix hace un POST a callbackUrl: 
{
  "eventType": "external_payment.completed",
  "resourceType": "external_payment",
  "companyId": "company-uuid",
  "payload": {
    "id": "a1b2c3d4-...",
    "status": "completed",
    "amountMinor": 15000,
    "currency": "VES",
    "invoiceId": "inv-uuid",
    "paymentId": "pay-uuid"
  }
}
Ver Webhooks para el handler completo.

​
Cancelar un pago pendiente

Antes de que el cliente complete el pago, puedes cancelarlo: 
curl -X DELETE "https://api.cobrix.co/api/external/payments/{id}" \
  -H "X-API-Key: sk_live_acme_..."
Solo pagos en estado pending pueden cancelarse (cualquier otro estado devuelve 409).

​
Verificar estado manualmente

Si el webhook no llega o quieres confirmar antes de una operación crítica: 
curl "https://api.cobrix.co/api/external/payments/{id}" \
  -H "X-API-Key: sk_live_acme_..."

​
Errores comunes

MensajeCausaSolución
"Idempotency-Key header is required"Falta el headerAgrega un UUID v4
"Customer has no pending invoices"Problema de generación de facturaVerifica amountMinor y currency
"Company has reached the maximum number of active sessions"Demasiados pagos hosted activosCancela pagos pendientes o espera a que expiren