The official Python library for the VEX Pay API: accept Venezuelan payments (Pago Móvil C2P, cards, débito inmediato), pay out to merchants, create checkout sessions, and verify signed webhooks.
- Sync (
VexPay) and async (AsyncVexPay) clients with the same methods - Typed Pydantic v2 models generated from the VEX Pay OpenAPI contract
- Safe retries: every
POSTcarries anIdempotency-Key, so a retried charge never charges twice - Auto-pagination
- Webhook signature verification with replay protection
- Python 3.9+
pip install vexpayfrom vexpay import VexPay
vexpay = VexPay() # reads VEXPAY_API_KEY from the environment
quote = vexpay.quotes.retrieve({"usdAmount": 25})
print(f"$25 = Bs {quote.vesAmount} at BCV {quote.bcvRate}")Keep your API key on the server. Use your test-mode key while you build; it runs against the sandbox provider. Request bodies and query parameters use the API's field names (usdAmount, debtorBankCode, …) — pass a dict or one of the models in vexpay._generated.models.
C2P is two steps: create an intent (the payer's bank sends them a token by SMS), then charge with the token your customer types in.
from vexpay import VexPay
vexpay = VexPay()
payer = {
"usdAmount": 25,
"debtorId": "V12345678",
"debtorCellPhone": "584141234567",
"debtorBankCode": 102,
}
intent = vexpay.payments.c2p.request({**payer, "externalRef": "order-1042"})
token = input("Bank token: ") # the customer reads it from their bank SMS
payment = vexpay.payments.c2p.execute({**payer, "intentId": intent.intentId, "token": token})
print(payment.paymentId, payment.status) # "COMPLETED" or "PENDING" — confirm with the payment.* webhookLet VEX Pay collect the payment details. Redirect the buyer to url, or embed the checkout on your own site with @vexpay/js and the one-time clientSecret.
from vexpay import VexPay
vexpay = VexPay()
session = vexpay.checkout.sessions.create(
{
"amountUsd": 25,
"reference": "order-1042",
"description": "Pedido #1042",
"successUrl": "https://shop.example/gracias",
"metadata": {"orderId": "1042"},
}
)
print(session.url) # redirect here, or send session.clientSecret to the browser (never log or store it)
# Later — fulfil only after checking on the server:
current = vexpay.checkout.sessions.retrieve(session.id)
if current.status == "paid":
print("ship order 1042")The hosted page lets the buyer pick the currency — bolívares, stablecoins or Colombian pesos — and offers every method your account accepts. Limit it with methods (c2p, vpos, usdt, usdc, cop).
USDT settles in USDT, into your VEX Pay USDT balance (never converted to VES). It must be enabled on your account — otherwise these calls fail with method_not_allowed (403). Pay-ins cost 2.5 % + 0.50 USDT; payouts cost the network fee listed by crypto.networks.list().
from vexpay import VexPay, VexPayError
vexpay = VexPay()
try:
networks = vexpay.crypto.networks.list({"amountUsdt": "50.00"})
except VexPayError as err:
if err.code != "method_not_allowed":
raise
networks = [] # USDT isn't enabled on this account
if any(n.receiveEnabled for n in networks):
# Hosted USDT checkout: the buyer picks a network and gets a deposit address.
session = vexpay.checkout.sessions.create(
{
"amountUsd": 25,
"reference": "order-1042",
"methods": ["usdt"],
"successUrl": "https://shop.example/gracias",
}
)
print(session.url)
print(vexpay.crypto.balance.retrieve())Static deposit addresses (crypto.deposit_addresses.create({"customerRef": "user_123", "network": "BEP20"})) fire payment.completed with that customerRef on every deposit. With a Test key, crypto.simulate_deposit({"customerRef": "user_123", "network": "BEP20", "amount": "40.00"}) makes a deposit arrive at that address (same payment, fee and webhook, livemode: false). Payouts (crypto.payouts.create({... "idempotencyKey": "withdrawal-981"})) debit amount + network fee and end in payout.completed (with txHash) or payout.failed (refunded). USDT payment.completed events add amountUsdt, feeUsdt, network, txHashes and checkoutSession.reference. Don't fulfil when underpaid is True.
USDC (Polygon and Base) uses the same calls with "currency": "USDC", has its own balance and must be enabled on your account separately. Without currency, every call stays in USDT.
usdc = vexpay.crypto.balance.retrieve({"currency": "USDC"})
balances = vexpay.crypto.balances.list() # USDT and USDC
vexpay.crypto.payouts.create(
{
"currency": "USDC",
"network": "BASE",
"address": "0x…",
"amount": "50.00",
"idempotencyKey": "withdrawal-982",
}
)Responses and events include currency, amount and fee for both coins (amountUsdt / feeUsdt stay on USDT only). Credit your customer in the currency the webhook reports.
Turn available VES or Colombian pesos into your USDT balance. A quote locks the rate (market USDT rate in that currency plus your spread) for 60 seconds; accepting it debits the source at once (conversion.created) and returns a PENDING conversion. VEX Pay then delivers the USDT and sends conversion.completed (or conversion.canceled, with the VES or COP returned). Conversions are on for every account that has USDT enabled (COP also needs COP enabled) — otherwise the calls fail with conversions_not_enabled (403). In test mode they complete immediately. COP amounts are whole pesos.
quote = vexpay.conversions.quotes.create({"sourceAmountVes": "10000.00"}) # or {"targetAmountUsdt": "50.00"}
print(quote.rate, quote.targetAmountUsdt, quote.expiresAt)
conversion = vexpay.conversions.create(
{"quoteId": quote.id, "reference": "treasury-2026-10-03"},
idempotency_key="convert-2026-10-03",
)
for c in vexpay.conversions.list({"status": "PENDING"}):
print(c.id, c.sourceAmount, c.sourceCurrency, "→", c.targetAmountUsdt)
vexpay.conversions.cancel(conversion.id) # only while PENDING
# Colombian pesos: same flow with sourceCurrency "COP".
cop_quote = vexpay.conversions.quotes.create({"sourceCurrency": "COP", "sourceAmount": "1000000"})
# Auto-convert 50% of each completed COP payment (after the fee) to USDT; 0 turns it off.
vexpay.conversions.settings.update({"autoConvert": {"COP": {"percent": 50}}})Collect pesos from buyers in Colombia through Bre-B, Nequi or Daviplata. Amounts are whole pesos, payments complete asynchronously (payment.completed / payment.failed), and completed payments go to your COP balance net of the COP fee. COP must be enabled on your account — otherwise the calls fail with method_not_allowed (403).
from vexpay import VexPay
vexpay = VexPay()
# What your account can use now (Bre-B, Nequi, Daviplata) and what each needs.
catalog = vexpay.cop.channels()
buyer = {"email": "juan@example.com", "phone": "3001234567", "documentType": "CC", "documentNumber": "1234567890"}
# Bre-B: no buyer data. Show next.qrPngBase64 as an image and next.transferKey as text.
breb = vexpay.cop.payments.create(
{"amountCop": 100000, "channel": "breb", "reference": "order-1042"},
idempotency_key="order-1042-cop",
)
# Nequi: the buyer approves a push in the Nequi app.
vexpay.cop.payments.create({"amountCop": 50000, "channel": "nequi", "buyer": buyer})
# Daviplata: with next.type 'submit_otp' the buyer reads you the SMS code; submit it.
davi = vexpay.cop.payments.create({"amountCop": 50000, "channel": "daviplata", "buyer": buyer})
vexpay.cop.payments.submit_otp(davi.id, {"otp": "123456"})
status = vexpay.cop.payments.retrieve(breb.id).status # pending | completed | failed | canceled | refunded
available = vexpay.cop.balance.retrieve().availableCopcancel(id) cancels a pending payment and refund(id) refunds a completed one in full within 96 hours (a payment that can no longer be refunded through the API fails with refund_not_supported). A webhook for a COP payment has data["method"] == "COP", with channel, amountCop and lowercase status.
Test mode (test API keys use a sandbox):
| Channel | What to use | Result |
|---|---|---|
| Bre-B | No buyer data | QR and key from the sandbox. Never send real money to them — sandbox keys are reachable from real banks and the money is not credited. |
| Nequi | Phone 3991111111, any valid document and email |
Completes on its own within about a minute; 3992222222 is declined |
| Daviplata | Same buyer data (CC, CE or TI only) |
With submit_otp, OTP 123456, 000000 or 111111 completes it; any other code fails with invalid_otp |
With a test API key, VPOS test cards return a fixed outcome without reaching the bank: 4242424242424242 succeeds, 4000000000009995 is declined with G51 (insufficient funds), 4000000000000259 completes and is then charged back, and more. A decline fails exactly like a live one (422, the bank code in code and failureCode, a payment.failed webhook). With a live key these numbers are refused with 400 test_card_in_live_mode. Full list: test cards.
VEX Pay signs every delivery with a VexPay-Signature header. Verify it with the raw request body — parsing and re-serializing JSON changes the bytes and breaks the signature (Flask: request.get_data(), Django: request.body, FastAPI: await request.body()).
import os
from typing import Optional
from vexpay import PaymentEvent, SignatureVerificationError, Webhook
def handle_webhook(raw_body: bytes, signature: Optional[str]) -> int:
"""Framework-agnostic handler: returns the HTTP status to answer with."""
try:
event = Webhook.construct_event(raw_body, signature, os.environ["VEXPAY_WEBHOOK_SECRET"])
except SignatureVerificationError:
return 400
if isinstance(event, PaymentEvent) and event.event == "payment.completed":
data = event.data
reference = data.externalRef or (data.checkoutSession.reference if data.checkoutSession else None)
print("paid", data.paymentId, reference)
return 204Deliveries older than 5 minutes are rejected as possible replays; pass tolerance= (seconds) to change that. Each delivery also carries a VexPay-Event-Id header you can use to deduplicate. In your own tests, sign fixtures with Webhook.generate_test_header(payload, secret).
Every error extends VexPayError and carries status, the API code (e.g. insufficient_balance), and the response body.
from vexpay import ConflictError, InvalidRequestError, NotFoundError, VexPay, VexPayError
vexpay = VexPay()
try:
vexpay.payouts.create(
{
"merchantId": "4f0c6f1e-2b7d-4c1a-9e3f-5a6b7c8d9e0f",
"monto": "1523.40",
"concepto": "Liquidación semana 30",
"externalRef": "po_2026_30_maria",
}
)
except InvalidRequestError as error:
print("fix the request:", error.code, error.message)
except NotFoundError:
print("no such merchant")
except ConflictError as error:
print("externalRef reused with a different payload", error.body)
except VexPayError as error:
print(error.status, error.code, error.message)| Class | When |
|---|---|
AuthenticationError |
401 — missing or invalid API key |
InvalidRequestError |
400, 403, 410, 422 — fix the request |
NotFoundError |
404 |
ConflictError |
409 — e.g. external_ref_conflict, external_ref_already_paid (body paymentId), idempotency_key_reused |
RateLimitError |
429, after retries |
APIError |
5xx, after retries |
APIConnectionError / APITimeoutError |
no HTTP answer, after retries |
SignatureVerificationError |
a webhook did not verify |
The SDK retries connection errors, timeouts, 429, 5xx, and 409 idempotency_request_in_progress up to max_network_retries times (default 2) with exponential backoff, honouring Retry-After. Every POST gets a random Idempotency-Key that stays the same across its retries. Supply your own to make retries safe across process restarts too:
from vexpay import VexPay
vexpay = VexPay(max_network_retries=3, timeout=20.0)
quote = vexpay.quotes.retrieve({"usdAmount": 10}, timeout=5.0)
session = vexpay.checkout.sessions.create(
{"amountUsd": 10, "reference": "order-1043"},
idempotency_key="order-1043-session",
)
print(quote.vesAmount, session.id)merchants.transfer(id, {...}) credits a seller from your platform balance: send amountVes, or amountUsd to convert at the official BCV rate (fails with rate_unavailable, 503, when no rate can be read), plus a transferKey that makes it idempotent. The result is the seller balance plus transfer (amounts and rate used). Read the movements and the monthly statement back:
from vexpay import VexPay
vexpay = VexPay()
merchant = vexpay.merchants.list({"limit": 1}).items[0]
# vexpay.merchants.transfer(merchant.merchantId, {"amountUsd": "100.00", "transferKey": "payroll-2026-11-u1"})
for movement in vexpay.merchants.list_transactions(merchant.merchantId, {"limit": 20}):
print(movement.type, movement.amountVes)
statement = vexpay.merchants.retrieve_statement(merchant.merchantId, {"month": "2026-11"})
print(statement.openingVes, statement.closingVes, len(statement.movements))
csv = vexpay.merchants.retrieve_statement_csv(merchant.merchantId, {"month": "2026-11"})
print(csv.splitlines()[0] if csv else "")list() on payouts, merchants, and products returns the first page; iterate it to walk every item across pages:
from vexpay import VexPay
vexpay = VexPay()
page = vexpay.merchants.list({"limit": 100})
print(len(page.items), page.next_cursor)
for merchant in vexpay.merchants.list({"status": "verified", "isActive": "true"}):
print(merchant.merchantId, merchant.name)
recent = vexpay.payouts.list({"limit": 50}).to_list(limit=200)
print(len(recent))AsyncVexPay has the same resources; await the calls, and use async for to paginate:
import asyncio
from vexpay import AsyncVexPay
async def main() -> None:
async with AsyncVexPay() as vexpay:
banks = await vexpay.banks.list()
print(len(banks), "banks")
first_page = await vexpay.products.list({"limit": 10})
print(len(first_page.items))
async for payout in vexpay.payouts.list():
print(payout.payoutId, payout.status)
asyncio.run(main())from vexpay import VexPay
with VexPay(
api_key="sk_test_…", # default: VEXPAY_API_KEY env var
base_url="http://localhost:3010", # default: https://api.vexpay.app
timeout=30.0,
max_network_retries=2,
) as vexpay:
print(len(vexpay.banks.list()), "banks")Pass http_client=httpx.Client(...) (or httpx.AsyncClient) to control proxies, connection pooling, or instrumentation.
| Namespace | Methods |
|---|---|
banks |
list |
quotes |
retrieve |
balance |
retrieve |
balance.transactions |
list (auto-paginating; every movement in your VES balance — reconcile with ledgerNetVes) |
balance.topups |
create, list, retrieve, instant, simulate (load your own Bs balance by Pago Móvil; enabled per account) |
payments |
retrieve, retrieve_by_ref, reverse |
payments.c2p |
request, execute |
payments.vpos |
create |
payments.pago_movil |
verify |
payments.debit · credit · operations · dispersals · change |
débito/crédito inmediato and disbursements (advanced payments) |
checkout.sessions |
create, retrieve |
crypto |
simulate_deposit (Test mode only) |
crypto.balance |
retrieve |
crypto.balances |
list |
crypto.deposit_addresses |
create |
crypto.networks |
list |
crypto.payouts |
create, retrieve |
conversions |
create, list, retrieve, cancel |
conversions.quotes |
create |
conversions.settings |
retrieve, update |
cop.payments |
create, retrieve, submit_otp, cancel, refund |
cop |
channels |
cop.balance |
retrieve |
merchants |
create, list, retrieve, retrieve_by_ref, update, delete, retrieve_balance, transfer, list_transactions, retrieve_statement, retrieve_statement_csv, list_audit_events, start_verification, confirm_verification |
merchants.payout_methods |
list, create, set_default, delete, start_verification, confirm_verification |
payouts |
create, create_instant, create_batch, list, retrieve, retrieve_by_ref |
products |
create, list, retrieve, update, delete, create_link, list_links |
payment_links |
retrieve, update, delete |
tenant_payout_account |
retrieve, upsert, create, start_verification, confirm_verification |
webhook_endpoints |
create, list, update, delete, send_test |
customers |
create, list, retrieve, update, delete |
customers.payment_methods |
list |
prices |
create, list, retrieve, update |
subscriptions |
create, list, retrieve, update, cancel |
invoices |
list, retrieve, void, mark_uncollectible, pay |
setup_sessions |
create, retrieve |
payment_methods |
retrieve, detach (domiciliación; payments.methods() lists bolívar pay-in methods) |
Webhook / client.webhooks |
construct_event, generate_test_header (offline) |
MIT