Run an immediate debit

What débito inmediato is

Débito inmediato pulls bolívares from a payer’s bank account after the bank SMS’s a one-time code. Amounts are in Bs. (VES). The execute response uses the banking-network operation payload, and the gateway stores a payment you can recover by externalRef. When the bank returns AC00 (pending), the gateway polls ConsultarOperaciones and fires payment.completed or payment.failed when the operation settles.

Step 01

Authenticate

Call the gateway with your tenant API key. Keep the key on your server—never ship it in browser or mobile code.

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

Step 02

Three-step lifecycle

1. 01
   Request the debit authorization code

   POST /v1/payments/debit/otp with banco, monto (VES), telefono, and cedula. Success typically returns code 202. The payer’s bank SMS’s the OTP.

2. 02
   Collect the OTP from the payer

   Ask the customer for the 6–8 digit code from their bank SMS (or bank app). Your application owns this step—the gateway does not forward the OTP to you.

3. 03
   Execute the debit

   POST /v1/payments/debit with the same payer fields plus nombre, otp, concepto, and optional externalRef. ACCP means accepted (payment.completed webhook). AC00 means pending—the gateway polls until ACCP or a terminal Guía V3.0 reject code, then fires payment.completed or payment.failed. On timeout, recover with GET /v1/payments/by-ref/:externalRef.

1. Request OTP

POST /v1/payments/debit/otp — send this JSON body. The payer bank SMS’s the code to 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. Execute the debit

POST /v1/payments/debit — same payer fields as OTP, plus nombre, otp (from the bank SMS), concepto, and optional externalRef for recovery lookup.

{
  "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. Pending operations (AC00)

When the debit returns AC00, the payment stays PENDING and you receive payment.pending. The gateway polls ConsultarOperaciones about once a minute until ACCP (payment.completed) or a terminal Guía V3.0 reject code (payment.failed)—there is no timeout, so slow bank settlement still completes and notifies. Subscribe to those webhook events—you do not need to poll yourself.

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

Recover by externalRef

After a timeout or uncertain execute response, look up the latest payment for your correlation id. The receipt includes status, paymentId, bankReference, and the externalRef you sent.

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

How to read the outcome

Reject codes for débito, crédito inmediato, and domiciliación (R4 Conecta Guía V3.0). The API returns these as HTTP 422 with r4Code, and stores failureCode on the payment.

Next steps

• Configure webhook endpoints for payment.completed and payment.failed (/webhooks).
• Compare with C2P when you need payment intents (/c2p).
• See credit, disbursement, and change under Advanced payments (/advanced-payments).
• Explore the interactive API reference at /api-reference.