Developer guide
VEX Pay siteAPI reference
Browse documentation

Charge an exact bolívar amount (for example Bs 2.000,00)

Create a checkout session with amountVes so the buyer is asked for exactly the bolívares you set, whatever the exchange rate.

What you will do

With amountUsd, the bolívar amount the buyer sees is your dollars × the rate at payment time, so it is rarely round (for example Bs 1.996,33). When your prices are in bolívares, send `amountVes` instead: Pago Móvil, Débito Inmediato and card ask for exactly that amount, whatever the rate.

  • Your API key on your server.
  • Bolívar methods (Pago Móvil, Débito Inmediato or card) enabled on your account.
  • The amount in bolívares, up to 2 decimals.

Steps

  1. Create the session with amountVes

    Call POST /v1/checkout/sessions with amountVes (for example 2000.00) and no amountUsd. Send exactly one of the two.

  2. Keep the response

    The response has amountVes: "2000.00" and amountUsd, its dollar value at your Bolívar rate (BCV or market) now. amountUsd is informative; the charge is always amountVes.

  3. Send the buyer the url

    Share the url by WhatsApp, email or a redirect. The checkout shows Bs 2.000,00 for Pago Móvil, Débito Inmediato and card.

  4. Confirm the payment

    When it is paid, payment.completed fires with vesAmount: "2000.00" and your reference. You can also read the session with GET /v1/checkout/sessions/:id: status becomes paid.

curlbash
curl --request POST "${API_URL}/v1/checkout/sessions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountVes": 2000.00,
    "description": "Order #2051",
    "reference": "order-2051",
    "methods": ["pago_movil", "c2p"]
  }'
Node SDKjavascript
const session = await vexpay.checkout.sessions.create({
  amountVes: 2000, // exactly Bs 2.000,00
  description: 'Order #2051',
  reference: 'order-2051',
  methods: ['pago_movil', 'c2p'],
});
// session.amountVes === '2000.00'
// session.amountUsd: '2.18' (2000 at your rate)
// Send session.url to the buyer.
Responsejson
{
  "id": "cs_9f2a4b7c1d3e",
  "status": "open",
  "url": "https://pay.vexpay.app/pay/cs-9f2a4b7c1d3e",
  "amountVes": "2000.00",
  "amountUsd": "2.18",
  "reference": "order-2051",
  "methods": ["pago_movil", "c2p"]
}

Good to know

  • The minimum charge and the maximum (US$100,000) are checked against amountVes at your Bolívar rate when you create the session.
  • USDT and USDC stay available: the buyer pays Bs ÷ the rate at payment time, rounded up to the cent.
  • Colombian pesos (cop) are not offered on a bolívar-priced session.
  • amountVes is null on sessions created with amountUsd.

Check that it worked

  • Open the url: the checkout asks for Bs 2.000,00.
  • In Test, press Simular pago recibido on the Pago Móvil waiting screen: the session becomes paid and payment.completed arrives with vesAmount: "2000.00".

If something goes wrong

SymptomLikely causeWhat to do
400 invalid_data: "Send exactly one of amountUsd or amountVes"Both amounts sent, or neitherSend only amountVes.
400 invalid_data naming copcop requested on a bolívar-priced sessionRemove cop from methods.
422 amount_below_minimumamountVes is worth less than your minimum chargeRaise the amount; minimumUsd in the error is the minimum in dollars.
503 rate_unavailableThe Bolívar rate could not be readTry again in a few minutes.

Related: Pago Móvil-only link · Pago Móvil verification · Webhooks