Ejecuta un débito inmediato

Qué es el débito inmediato

El débito inmediato debita bolívares de la cuenta del pagador después de que el banco envía un código OTP por SMS. Los montos van en Bs. (VES). La respuesta de ejecución usa el payload de la red bancaria, y el gateway guarda un pago que puedes recuperar por externalRef. Cuando el banco devuelve AC00 (pendiente), el gateway consulta ConsultarOperaciones y dispara payment.completed o payment.failed al liquidar la operación.

Paso 01

Autentica

Llama al gateway con la clave de API de tu tenant. Mantén la clave en tu servidor; nunca la incluyas en código del navegador o de una aplicación móvil.

API_URL=https://api.banking.chuventures.com
VEXPAY_API_KEY=vk_live_replace_me

Paso 02

Ciclo de vida en tres pasos

1. 01
   Solicita el código de autorización de débito

   POST /v1/payments/debit/otp con banco, monto (VES), telefono y cedula. El éxito suele devolver code 202. El banco del pagador envía el OTP por SMS.

2. 02
   Obtén el OTP del pagador

   Pide al cliente el código de 6–8 dígitos del SMS (o app) de su banco. Tu aplicación controla este paso: el gateway no te reenvía el OTP.

3. 03
   Ejecuta el débito

   POST /v1/payments/debit con los mismos datos del pagador más nombre, otp, concepto y externalRef opcional. ACCP significa aceptado (webhook payment.completed). AC00 significa pendiente: el gateway consulta hasta ACCP o un código de rechazo terminal de la Guía V3.0 y luego dispara payment.completed o payment.failed. Si hay timeout, recupera con GET /v1/payments/by-ref/:externalRef.

1. Solicita el OTP

POST /v1/payments/debit/otp — envía este cuerpo JSON. El banco del pagador envía el código por SMS a telefono.

{
  "banco": "0191",
  "monto": 50.00,
  "telefono": "584144555555",
  "cedula": "V12345678"
}

curl --request POST "https://api.banking.chuventures.com/v1/payments/debit/otp" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "banco": "0191",
    "monto": 50.00,
    "telefono": "584144555555",
    "cedula": "V12345678"
  }'

2. Ejecuta el débito

POST /v1/payments/debit — los mismos campos del pagador que en el OTP, más nombre, otp (del SMS del banco), concepto y externalRef opcional para recuperación.

{
  "banco": "0191",
  "monto": 50.00,
  "telefono": "584144555555",
  "cedula": "V12345678",
  "nombre": "Maria Perez",
  "otp": "19807849",
  "concepto": "pago Condominio1",
  "externalRef": "fine_736a0b42-0b6e-454c-b87e-7f3c0e47057b"
}

curl --request POST "https://api.banking.chuventures.com/v1/payments/debit" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "banco": "0191",
    "monto": 50.00,
    "telefono": "584144555555",
    "cedula": "V12345678",
    "nombre": "Maria Perez",
    "otp": "19807849",
    "concepto": "pago Condominio1",
    "externalRef": "fine_736a0b42-0b6e-454c-b87e-7f3c0e47057b"
  }'

{
  "code": "ACCP",
  "reference": "16142940",
  "id": "6785d97e-2092-49f0-9f7d-3d5921f0b13f",
  "paymentId": "3fd84b2d-9ad1-4f74-a2d9-0f2f56984db5",
  "externalRef": "fine_736a0b42-0b6e-454c-b87e-7f3c0e47057b"
}

{
  "code": "AC00",
  "message": "Operación en Espera de Respuesta del Receptor",
  "Id": "e63a7892-f00f-46a4-b7d1-a6e8ac7ab094",
  "paymentId": "3fd84b2d-9ad1-4f74-a2d9-0f2f56984db5",
  "externalRef": "fine_736a0b42-0b6e-454c-b87e-7f3c0e47057b"
}

3. Operaciones pendientes (AC00)

Cuando el débito devuelve AC00, el pago queda PENDING y recibes payment.pending. El gateway consulta ConsultarOperaciones aproximadamente cada minuto hasta ACCP (payment.completed) o un código de rechazo terminal de la Guía V3.0 (payment.failed)—sin timeout, así que una liquidación bancaria lenta igual completa y notifica. Suscríbete a esos webhooks: no necesitas consultar tú mismo.

curl "https://api.banking.chuventures.com/v1/payments/operations/OPERATION_ID" \
  --header "x-api-key: ${VEXPAY_API_KEY}"

Recupera por externalRef

Tras un timeout o una respuesta incierta, consulta el pago más reciente para tu id de correlación. El comprobante incluye status, paymentId, bankReference y el externalRef que enviaste.

curl "https://api.banking.chuventures.com/v1/payments/by-ref/fine_736a0b42-0b6e-454c-b87e-7f3c0e47057b" \
  --header "x-api-key: ${VEXPAY_API_KEY}"

Cómo interpretar el resultado

Códigos de rechazo para débito, crédito inmediato y domiciliación (Guía R4 Conecta V3.0). La API los devuelve como HTTP 422 con r4Code y guarda failureCode en el pago.

Siguientes pasos

• Configura endpoints de webhook para payment.completed y payment.failed (/es/webhooks).
• Compara con C2P cuando necesites intenciones de pago (/es/c2p).
• Consulta crédito, desembolsos y vuelto en Pagos avanzados (/es/advanced-payments).
• Explora la referencia interactiva de la API en /api-reference.