Docs / Authentication
Authenticate every request Tenant API keys scope requests and payment records to one integration.
Send the raw tenant key in the x-api-key header on every /v1 request. Missing, invalid, inactive, or rotated keys return 401.
curl bash Copy curl "${API_URL}/v1/banks" \
--header "x-api-key: ${VEXPAY_API_KEY}"Server-side only Treat the API key as a secret. Load it from a secret manager or server environment variable; do not expose it through NEXT_PUBLIC_ variables.
Live and Test keys Each commercial account has a Live twin and a Test twin. Mode is implied by which key you send. Local seed: dev-local-api-key (live) and dev-local-api-key-test (test). Webhook payloads include livemode: true|false. VEXPay routes each method to a partner bank for you — you never pick or configure the bank. Test keys use sandbox rails or the bank's test environment, so no real money moves — card payments in Test accept only the VPOS test cards (VPOS ) — fixed numbers that return each outcome — and decline real cards without charging them. The exception is merchant micro-deposits and payouts, which move real céntimos even in Test (the pair is always under Bs 0.50). Confirm the amounts your phone actually received.
Provider routing per method VEXPay ops can limit which payment methods (Pago Móvil, VPOS, Débito Inmediato incl. C2P, Crédito Inmediato) your account may use (for example, Pago Móvil only). Routed calls (C2P, VPOS, Pago Móvil verify / receiving account, merchant payouts and micro-deposits) automatically pick an allowed provider, and return 400 when none is. The advanced débito and crédito endpoints under /v1/payments (debit/otp, debit, credit, credit/account, credit/disburse, payouts, change) return 403 when that method is not enabled on your account. In Test mode the débito endpoints are never restricted, but the direct crédito endpoints (credit, credit/account, credit/disburse, payouts, change) are always refused with 403 — send funds with POST /v1/payouts instead.
A rotated key invalidates the previous key for that mode only (Live or Test). Update the secret in each environment atomically and verify with GET /v1/banks.
