Skip to main content

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 / responde 422 direct_debit_unavailable.
  • Crea una llave con direct_debits:write y direct_debits:read en Configuración → Integraciones → Llaves API.
  • Firma cada llamada como en toda la API de integraciones. La ruta que firmas empieza en /api e incluye el query string, tal como la envías (url.pathname + url.search). Consulta Firma de solicitudes.
  • Todo POST lleva Idempotency-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.
Confirma el pago con el webhook, no con lo que reporta tu página. Lo que pasa en el navegador del pagador sirve para mostrarle «gracias» o el error. Puede no llegar si cierra la pestaña, y cualquiera puede alterarlo desde su equipo. Marca el pedido como pagado cuando tu servidor reciba el webhook firmado payment.succeeded. Si un webhook se demora, consulta GET /{id} desde tu servidor.

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.
  • RUTA es lo que va después de /direct-debits: /banks, /{id}/execute o ?status=succeeded. Vacía para POST / y GET /.
  • CUERPO es el JSON exacto que envías. La firma usa ese mismo texto.
  • IDEMPOTENCY_KEY es obligatoria en los POST. 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
Si la lista viene vacía, la empresa no puede cobrar con débito inmediato ahora. Ofrece otro método de pago. Errores: solo los comunes a todas las rutas.

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.
  • amount es lo que el banco va a debitar, siempre en bolívares. minor viene como texto: "1313475" es Bs 13.134,75.
  • reference es el total del cobro en su moneda.
  • otp dice 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 externalDocumentId ya 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

Con splits 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 responde 403 insufficient_scope.
  • La respuesta trae splits con cada cuenta enmascarada, en el mismo orden.
  • Si splits tiene 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.
Responde 201 con el débito en uno de estos estados:
  • Un rechazo del banco no es un error HTTP. La respuesta es 201 con status: failed y el motivo en error.
  • Para reintentar después de failed, llama otra vez a POST / con el mismo externalDocumentId y una Idempotency-Key nueva. El débito rechazado no se reutiliza.
  • Si la llamada se corta, repítela con la misma Idempotency-Key y el mismo cuerpo. Recibes la misma respuesta y el débito no se envía dos veces. Con otra clave responde 409 direct_debit_not_executable: consulta GET /{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.validitySeconds dice cuántos segundos le quedan.
  • Cuando el código vence, el débito pasa a expired con error.code: otp_expired. Pide otro con POST /{id}/otp.
  • succeeded trae paymentId. failed, expired y cancelled traen error.

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 hasMore sea true, pide la siguiente página con cursor igual a nextCursor.
  • El cursor no repite ni salta débitos aunque entren nuevos mientras lees.
  • Para conciliar, cruza cada débito succeeded con tu pedido por externalDocumentId y guarda su paymentId.

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 con otp.sentTo, otp.expiresAt y 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 propio id. El anterior queda expired. El código nuevo cuenta para el límite de 3 por hora.
  • Ejecuta siempre con el id de 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ébito failed, expired o cancelled trae error:
  • code es estable para cualquier banco. Úsalo en tu código.
  • message está en español, listo para mostrar al pagador.
  • bankCode es 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.paymentId es el paymentId del débito. Tu externalDocumentId llega en data.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.
Un débito creado con esta API llega en payment.failed así:
  • paymentId va en null: un débito rechazado no crea pago. Identifícalo con directDebitId, que es el id del débito.
  • error es el mismo objeto de GET /{id}. Si falló por algo de Cobrix, trae bank_error sin bankCode.

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á en processing, pedir un código o ejecutar otro débito de ese cliente responde 409 payer_debit_in_progress. Un débito otp_sent, expired o cancelled no 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 id ajeno responde 404, nunca 403.

Probar en sandbox

  1. Pide a Cobrix que active el débito inmediato en tu empresa de sandbox.
  2. Crea una llave de sandbox con direct_debits:read y direct_debits:write.
  3. Configura tus webhooks y verifica la firma.
  4. Llama a GET /banks y confirma que trae bancos.
  5. Pide un código con POST / y ejecútalo con POST /{id}/execute.
  6. Confirma que tu servidor recibe payment.succeeded.
  7. Prueba también un código vencido, un cobro cancelado y un rechazo.
En sandbox el banco es real: el pagador recibe un SMS y el débito mueve dinero. Prueba con una cuenta tuya y un monto pequeño.

Firma de solicitudes

Cómo calcular Cobrix-Signature en tu lenguaje.

Webhooks de pagos

Firma y contenido de payment.succeeded y payment.failed.