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.

​
Ambiente de Staging

El ambiente de Staging te permite probar toda la integración sin procesar pagos reales.
RecursoURL
APIhttps://api-staging.cobrix.co
Checkout UIDevuelto como checkoutUrl al crear un pago hosted
Formato de keysk_test_*

​
Escenarios recomendados

EscenarioQué hacerResultado esperado
Pago hosted exitosoCompletar pago en el checkoutstatus: completed + webhook
Pago hosted fallidoUsar datos de método que rechacenstatus: failed
Pago hosted expiradoEsperar 24h sin completarstatus: expired
CancelaciónDELETE /payments/{id}status: canceled
Pago directoPOST /payments/directstatus: completed inmediato
Reintento idempotenteRepetir POST con misma Idempotency-KeyMismo id devuelto
Rate limitEnviar > 60 req/min429 Too Many Requests

​
Datos de prueba — Pago Móvil (VES)

Usa estos datos en el checkout de Staging para simular diferentes resultados:

​
Pago aceptado

CampoValor
Banco0001 (Banco Central de Venezuela)
Teléfono4145223698
CédulaV15854963
OTP12345678

​
Pago rechazado

CampoValor
Banco0001
Teléfono4121234597
CédulaV12345708
OTP12345678

​
Pago pendiente

CampoValor
CédulaV8866332211
Teléfono4227786632
OTP12345678

​
Exponer tu webhook local

Para recibir webhooks en tu máquina: 
# ngrok
ngrok http 3000
# usar https://abc123.ngrok.io/webhooks/cobrix como callbackUrl
Alternativa: webhook.site para inspeccionar los eventos sin escribir código.

​
Script de smoke test

#!/bin/bash
set -euo pipefail

BASE=https://api-staging.cobrix.co
KEY=${COBRIX_API_KEY:?missing}

echo "→ Creando pago hosted..."
PAYMENT=$(curl -fs -X POST "$BASE/api/external/payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerEmail": "test-'$(date +%s)'@example.com",
    "amountMinor": 15000,
    "currency": "VES",
    "description": "smoke test"
  }')

ID=$(echo "$PAYMENT" | jq -r .id)
URL=$(echo "$PAYMENT" | jq -r .checkoutUrl)
echo "  id=$ID"
echo "  checkoutUrl=$URL"

echo "→ Consultando pago..."
curl -fs "$BASE/api/external/payments/$ID" -H "X-API-Key: $KEY" | jq .status

echo "→ Cancelando pago..."
curl -fs -X DELETE "$BASE/api/external/payments/$ID" -H "X-API-Key: $KEY" | jq .status

​
Verificar tu handler de webhook

Puedes simular un webhook contra tu endpoint local: 
curl -X POST "http://localhost:3000/webhooks/cobrix" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "external_payment.completed",
    "resourceType": "external_payment",
    "companyId": "test-company",
    "payload": {
      "id": "test-payment-id",
      "status": "completed",
      "amountMinor": 15000,
      "currency": "VES",
      "invoiceId": "test-invoice",
      "paymentId": "test-payment"
    }
  }'
Asegúrate de que tu handler maneje el caso en que GET /payments/{id} devuelva 404 para un id de prueba — es útil separar la lógica de dedup de la llamada de verificación.

​
Checklist de testing

POST /payments crea pago hosted con status: pending y checkoutUrl
POST /payments/direct crea pago con status: completed
GET /payments/{id} devuelve el pago
GET /payments devuelve lista paginada
DELETE /payments/{id} cancela pagos pending y rechaza los demás (409)
Reintento con misma Idempotency-Key → mismo pago, sin duplicados
Webhook external_payment.completed llega al callback
Handler responde 200 en < 5s y deduplica por payload.id
Rate limit 429 se maneja con backoff exponencial