Tu servidor pide el código al banco del pagador, el pagador lo escribe en tu web y tu servidor lo envía. Cobrix calcula los bolívares, aplica el pago al documento de cobro y te avisa por webhook.
direct_debits:readdirect_debits:write
Operaciones
Todas las rutas empiezan en/api/integrations/v1/{companyId}/direct-debits.
¿Prefieres que Cobrix muestre los campos del pago? Usa el componente de débito inmediato. Con esta API, tu web pide los datos y el código.
Antes de empezar
- La empresa necesita el débito inmediato activo. Si no lo tiene,
POST /responde422 direct_debit_unavailable. - Crea una llave con
direct_debits:writeydirect_debits:readen Configuración → Integraciones → Llaves API. - Firma cada llamada como en toda la API de integraciones. La ruta que firmas empieza en
/apie incluye el query string, tal como la envías (url.pathname + url.search). Consulta Firma de solicitudes. - Todo
POSTllevaIdempotency-Key. Consulta Idempotencia. - Llama siempre desde tu servidor. La llave nunca va en el navegador.
El flujo
1
Muestra los bancos
Llama a
GET /banks y arma la lista de bancos de tu formulario.2
Pide el código
Con el cobro y los datos del pagador, llama a
POST /. El banco envía un SMS al pagador. Guarda el id que responde Cobrix.3
Ejecuta con el código
El pagador escribe el código en tu web y tu servidor lo envía con
POST /{id}/execute. Responde succeeded, processing, failed o expired.4
Espera el resultado
Si queda
processing, el banco todavía no confirma. Espera el webhook o consulta GET /{id}.5
Entrega el pedido
Cuando tu servidor recibe el webhook
payment.succeeded, el dinero está cobrado y el pago aplicado al documento.6
Concilia
Lista tus débitos con
GET / y compáralos con tus pedidos.Ejemplos con curl
Los ejemplos usan esta función de shell. Firma cada llamada y la envía. Tus datos van en variables de entorno, nunca en el código.RUTAes lo que va después de/direct-debits:/banks,/{id}/executeo?status=succeeded. Vacía paraPOST /yGET /.CUERPOes el JSON exacto que envías. La firma usa ese mismo texto.IDEMPOTENCY_KEYes obligatoria en losPOST. Si repites una llamada por un timeout, usa la misma clave y el mismo cuerpo.
Listar bancos
GET /banks · Scope direct_debits:read
Los bancos desde los que el pagador puede pagar. Usa code como payer.bankCode al pedir el código.
Respuesta 200
Pedir el código
POST / · Scope direct_debits:write
Crea el cobro y pide al banco del pagador que le envíe el código por SMS. El cobro es el mismo de POST /checkouts: cliente, documento de cobro y sesión. Cobrix calcula el monto en bolívares. Nunca lo envíes tú.
También acepta
lines, dueDate y expiresInHours, igual que crear el cobro del checkout embebido. No envíes otros campos: Cobrix responde 400 invalid_request.
Respuesta 201
- Guarda
id. Lo usas para ejecutar, consultar, pedir otro código o cancelar. amountes lo que el banco va a debitar, siempre en bolívares.minorviene como texto:"1313475"es Bs 13.134,75.referencees el total del cobro en su moneda.otpdice a qué teléfono llegó el código (enmascarado) y cuándo vence. La vigencia la pone el banco.- Una referencia abierta se reutiliza. Si
externalDocumentIdya existe y sigue abierta, Cobrix la actualiza y abre un cobro nuevo.
También pueden salir los errores comunes, como
400 invalid_request o 500 internal_error.
Repartir la venta
Consplits indicas a qué cuentas va el dinero de esta venta y en qué porcentaje. Tiene el mismo formato, las mismas reglas y los mismos errores que en Links de cobro, sección «Repartir la venta entre varias cuentas».
- La llave necesita además
payout_splits:write. Sin ese permiso responde403 insufficient_scope. - La respuesta trae
splitscon cada cuenta enmascarada, en el mismo orden. - Si
splitstiene un error, Cobrix responde antes de crear el cobro o las cuentas.
Ejecutar con el código
POST /{id}/execute · Scope direct_debits:write
Envía al banco el código que escribió el pagador.
otp son los dígitos que el banco envió por SMS. Tu servidor lo reenvía y no lo guarda. Cobrix tampoco lo guarda ni lo devuelve.
201 con el débito en uno de estos estados:
- Un rechazo del banco no es un error HTTP. La respuesta es
201constatus: failedy el motivo enerror. - Para reintentar después de
failed, llama otra vez aPOST /con el mismoexternalDocumentIdy unaIdempotency-Keynueva. El débito rechazado no se reutiliza. - Si la llamada se corta, repítela con la misma
Idempotency-Keyy el mismo cuerpo. Recibes la misma respuesta y el débito no se envía dos veces. Con otra clave responde409 direct_debit_not_executable: consultaGET /{id}.
Consultar un débito
GET /{id} · Scope direct_debits:read
El estado actual de un débito.
Respuesta 200
- Mientras espera su código,
otp.validitySecondsdice cuántos segundos le quedan. - Cuando el código vence, el débito pasa a
expiredconerror.code: otp_expired. Pide otro conPOST /{id}/otp. succeededtraepaymentId.failed,expiredycancelledtraenerror.
Listar para conciliar
GET / · Scope direct_debits:read
Los débitos de los cobros que creó tu integración, del más nuevo al más viejo. Todos los filtros son opcionales.
Respuesta 200
- Mientras
hasMoreseatrue, pide la siguiente página concursorigual anextCursor. - El cursor no repite ni salta débitos aunque entren nuevos mientras lees.
- Para conciliar, cruza cada débito
succeededcon tu pedido porexternalDocumentIdy guarda supaymentId.
Pedir otro código
POST /{id}/otp · Scope direct_debits:write
Para cuando el código venció o no llegó. Sirve para un débito en otp_sent o expired. Usa el mismo cobro y el mismo pagador.
Va sin cuerpo, con o sin Content-Type: application/json. Firma con el cuerpo vacío.
Respuesta 201
- Si el código sigue vigente (
otp_sent), responde ese mismo débito conotp.sentTo,otp.expiresAty los segundos que le quedan. El banco no envía otro SMS. - Si el código venció (
expired), responde un débito nuevo, con su propioid. El anterior quedaexpired. El código nuevo cuenta para el límite de 3 por hora. - Ejecuta siempre con el
idde esta respuesta.
Cancelar
POST /{id}/cancel · Scope direct_debits:write
Cancela un débito que espera su código (otp_sent). Úsalo si el pagador elige otro método o abandona la compra. Va sin cuerpo, con o sin Content-Type: application/json.
Respuesta 201
Estados
Los mismos seis estados para cualquier banco.processing se resuelve solo: Cobrix sigue consultando al banco hasta tener su respuesta. Mientras tanto, no pidas código ni ejecutes otro débito del mismo cliente: Cobrix responde 409 payer_debit_in_progress.
expired también llega solo. Desde que vence el código, el débito se lee expired en GET /{id}, en GET / y en sus filtros. Un minuto después, Cobrix lo cierra aunque nadie lo consulte. Un débito vencido no se cobra, no bloquea otro débito del cliente y no envía webhook.
Por qué no se cobró
Un débitofailed, expired o cancelled trae error:
codees estable para cualquier banco. Úsalo en tu código.messageestá en español, listo para mostrar al pagador.bankCodees el código propio del banco, solo para soporte. Puede cambiar con el banco. Solo viene cuando el código es del banco.
Errores comunes a todas las rutas
Todos los errores HTTP de estas rutas traen{ "error": { "code", "message" } }. Consulta también Errores y rate limits.
Un campo con formato incorrecto, o que no está en esta página, responde
400 invalid_request. field es el primer campo con problema y details trae todos:
500 internal_error es un fallo de Cobrix, no del banco ni de tus datos. El mensaje es genérico y no trae detalles internos. Si envías X-Request-Id, la respuesta lo devuelve como requestId: dáselo a soporte.
Webhooks
Configura tus webhooks en Integraciones › Webhooks y verifica la firma de cada uno. Consulta Firma de webhooks.payment.succeeded:data.paymentIdes elpaymentIddel débito. TuexternalDocumentIdllega endata.documents[].externalInvoiceId.payment.failed: sale una sola vez por débito. No sale cuando el código vence ni cuando cancelas: nada llegó al banco.
payment.failed así:
paymentIdva ennull: un débito rechazado no crea pago. Identifícalo condirectDebitId, que es eliddel débito.errores el mismo objeto deGET /{id}. Si falló por algo de Cobrix, traebank_errorsinbankCode.
Límites
- Códigos por pagador: 3 por hora por documento del pagador, aunque pague para distintos clientes tuyos. También 3 por hora por cliente. Después,
429 rate_limited. - Un código a la vez: si llegan dos pedidos de código para el mismo pagador al mismo tiempo, uno pasa y el otro recibe
429 rate_limited. - Un débito en curso por cliente: mientras un débito de un cliente (
customerExternalId) está enprocessing, pedir un código o ejecutar otro débito de ese cliente responde409 payer_debit_in_progress. Un débitootp_sent,expiredocancelledno bloquea. - Llamadas por llave: 120 por minuto por ruta.
- Datos mínimos: las respuestas y los webhooks nunca traen el código, ni el documento, el teléfono o la cuenta completos.
- Cada débito es de su empresa y su integración. Un
idajeno responde404, nunca403.
Probar en sandbox
- Pide a Cobrix que active el débito inmediato en tu empresa de sandbox.
- Crea una llave de sandbox con
direct_debits:readydirect_debits:write. - Configura tus webhooks y verifica la firma.
- Llama a
GET /banksy confirma que trae bancos. - Pide un código con
POST /y ejecútalo conPOST /{id}/execute. - Confirma que tu servidor recibe
payment.succeeded. - Prueba también un código vencido, un cobro cancelado y un rechazo.
Firma de solicitudes
Cómo calcular
Cobrix-Signature en tu lenguaje.Webhooks de pagos
Firma y contenido de
payment.succeeded y payment.failed.
