Inicio rápido
De cero a tu primer cobro de prueba acreditado en tu saldo, en sandbox.
En esta guía haces en sandbox el recorrido completo: te autenticas, ves qué tienes disponible, abres un cobro, simulas el depósito del pagador y ves el dinero en tu saldo.
Antes de empezar
Necesitas una clave de sandbox (psp_test_…). Caibo emite las claves al abrir tu cuenta; si aún no tienes una, pídela a tu contacto en Caibo. La clave se muestra una sola vez: guárdala en tu gestor de secretos, nunca en el código.
Configura tu clave
export CAIBO_API_KEY="psp_test_..."
export CAIBO_API="https://api-sandbox.caibopay.app"Comprueba la conexión
GET/v1/accountcurl "$CAIBO_API/v1/account" \
-H "Authorization: Bearer $CAIBO_API_KEY"{
"id": "acct_01m3sg8r0000000000000000",
"name": "Mi Empresa",
"status": "active",
"environment": "sandbox",
"primary_treasury_asset": "USDT",
"credential": {
"type": "api_key",
"id": "key_01m3sg8s0000000000000000",
"prefix": "abc123def456",
"scopes": ["read", "write"],
"created_at": "2026-10-18T12:00:00Z"
},
"created_at": "2026-10-01T09:00:00Z"
}environment confirma dónde estás. scopes dice qué puede hacer la clave: read para consultar, write para crear y mover dinero.
Mira qué puedes cobrar
GET/v1/capabilitiescurl "$CAIBO_API/v1/capabilities?product=payin" \
-H "Authorization: Bearer $CAIBO_API_KEY"Cada elemento describe algo que puedes hacer: method, currency, country, los campos que pide, cómo se cobra (collection) y si está disponible ahora para ti (available). Ver Qué puedes hacer.
Registra tu webhook
Así te enteras de cada cobro sin tener que consultar. La URL debe ser https y pública.
curl "$CAIBO_API/v1/webhook-endpoints" \
-H "Authorization: Bearer $CAIBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://tu-empresa.com/webhooks/caibo", "event_types": ["payin.completed", "funding_account.active"] }'La respuesta trae secret (whsec_…) una sola vez. Guárdalo: con él verificas la firma de cada aviso.
Abre un cobro
Sandbox tiene una cuenta de prueba en USD que recibe cualquier depósito y que puedes "pagar" tú mismo. Cada creación lleva un Idempotency-Key único por operación.
curl "$CAIBO_API/v1/funding-accounts" \
-H "Authorization: Bearer $CAIBO_API_KEY" \
-H "Idempotency-Key: quickstart-cobro-001" \
-H "Content-Type: application/json" \
-d '{ "method": "bank_transfer", "currency": "USD" }'{
"id": "fa_01m3sg9w0000000000000000",
"status": "pending",
"method": "bank_transfer",
"currency": "USD",
"settlement_currency": "USDT",
"created_at": "2026-10-18T12:00:00Z"
}En segundos pasa a active, te llega funding_account.active y la cuenta trae en instructions los datos para el pagador:
curl "$CAIBO_API/v1/funding-accounts/fa_01m3sg9w0000000000000000" \
-H "Authorization: Bearer $CAIBO_API_KEY"Simula el depósito del pagador
Solo en sandbox: deposita en la cuenta como lo haría tu cliente. El monto va en la moneda de tu saldo (settlement_currency).
curl "$CAIBO_API/v1/sandbox/deposits" \
-H "Authorization: Bearer $CAIBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "funding_account_id": "fa_01m3sg9w0000000000000000", "amount": "100.00" }'Responde 202. El depósito recorre el mismo camino que uno real y, cuando se confirma, recibes payin.completed.
Mira tu saldo
GET/v1/balancescurl "$CAIBO_API/v1/balances" -H "Authorization: Bearer $CAIBO_API_KEY"{
"data": [
{
"currency": "USDT",
"primary": true,
"available": "100.000000",
"pending": "0.000000",
"reserved": "0.000000",
"in_settlement": "0.000000",
"earnings": "0.000000",
"total": "100.000000",
"as_of": "2026-10-18T12:01:00Z"
}
]
}