Skip to content
Bolívar Connect

API for integrators

If your company prefers to integrate instead of using our till or the widget, Bolívar Connect gives you an API over your own Banco de Venezuela account. You register the key BDV gives you once and, from then on, your system verifies the payments you receive, checks your balance and gives change with your Bolívar Connect API key.

How it works

Section titled “How it works”

  1. Generate your key in BDVenLínea Empresas (Reconciliation API) for your business account.

  2. Register it in Bolívar Connect. We check with the bank that the key opens the account you declare; if not, it is not stored.

    Ventana de terminal
    curl -X PUT $BASE/v1/bancos/bdv/credencial \
      -H "x-api-key: $KEY" -H 'content-type: application/json' \
      -d '{"apiKey":"<your BDV key>","cuenta":"0102…","rif":"J123456789","telefono":"04141234567"}'

    The response never includes the key: only "llave": "••••A5B2".

  3. Use it with your Bolívar Connect API key:

    Ventana de terminal
    # Payments received today, from any bank
    curl $BASE/v1/bancos/bdv/pagos -H "x-api-key: $KEY"
    

    # Verify a payment by the last digits of the reference and the amount
    curl -X POST $BASE/v1/bancos/bdv/verificaciones -H "x-api-key: $KEY" \
      -H 'content-type: application/json' \
      -d '{"referencia":"2135","monto":"500.00","pedido":"A-102"}'

Endpoints

Section titled “Endpoints”
Method Path Permission What it does
PUT /v1/bancos/bdv/credencial tenant:write Registers or replaces your BDV key
GET /v1/bancos/bdv/credencial tenant:write or bdv:read Status of your credential (without the key)
PATCH /v1/bancos/bdv/credencial tenant:write Turns on money movement and sets the daily cap
DELETE /v1/bancos/bdv/credencial tenant:write Revokes the credential and deletes the encrypted key
GET /v1/bancos/bdv/credencial/usos tenant:write or bdv:read Every use made of your key
GET /v1/bancos/bdv/saldo bdv:read Available and held balance
GET /v1/bancos/bdv/pagos bdv:read Payments received today and whether they were already verified
POST /v1/bancos/bdv/verificaciones bdv:verify Verifies a payment and marks it as used
POST /v1/bancos/bdv/vueltos bdv:move Gives change via Pago Móvil (moves money)
GET /v1/bancos/bdv/comisiones?periodo=hoy|30d bdv:read The bank’s fees per operation

Registering, configuring and revoking the key touch your real account: with an sk_test_ key they respond 403 live_key_required. Reads, verification and change with sk_test_ come from a simulated bank.

Verifying a payment

Section titled “Verifying a payment”

estado can be:

State Meaning
aprobado The payment is in your account, for the exact amount, and was marked as used for pedido
ya_usado That receipt already paid another order (pedido says which)
monto_distinto The reference exists but for another amount (pago.monto)
ambiguo Several payments end in those digits: send more
no_encontrado There is no payment with that reference today
referencia_corta At least 4 digits are needed

“Already used” is guaranteed by our database: the same receipt cannot pay two orders even if it arrives at the same time via the web, the till and your API.

Giving change: three keys to move money

Section titled “Giving change: three keys to move money”

Change comes out of your account, so all three are needed:

  1. An API key with the bdv:move permission. Default keys do not have it; create it separately: POST /v1/tenant/api-keys with "scopes": ["bdv:move"].
  2. Money movement turned on with a daily cap: PATCH /v1/bancos/bdv/credencial with {"moverDinero": true, "limiteDiario": "500.00"}. Without a cap it is not turned on.
  3. The Idempotency-Key header. If you resend the same request with the same key, it is not paid twice.

If the bank does not confirm the result, the response is "estado": "desconocido" (unknown). Do not resend with another Idempotency-Key: check your movements first.

How we protect your key

Section titled “How we protect your key”
  • Encrypted with AWS KMS (envelope encryption, AES-256-GCM). Our database only holds ciphertext; the master key never leaves AWS.
  • Bound to your company: the encryption carries your identifier, so your key cannot be decrypted for another client.
  • Write-only: no endpoint returns it, not even to you.
  • Used only in memory, right when calling the bank, and never written to logs.
  • Moving money is off until you turn it on, and always with a cap.
  • Audit: you see every use in /credencial/usos.
  • Revocation: delete it here or revoke it in BDVenLínea whenever you want. If the bank rejects it, we mark it as invalid and let you know.

Errors

Section titled “Errors”
Code When
bank_credential_missing You have not registered your key
bank_credential_invalid The bank rejected the key or the service is not enrolled
bank_credential_mismatch The account does not correspond to that key
money_movement_disabled Money movement is not turned on
daily_limit_exceeded The change would exceed your daily cap
idempotency_key_required Idempotency-Key is missing on an operation with money
bank_rejected The bank rejected the operation (balance, beneficiary data…)
bank_unavailable The bank did not respond; retry