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
- Create the session with amountVes
Call
POST /v1/checkout/sessionswithamountVes(for example2000.00) and noamountUsd. Send exactly one of the two. - Keep the response
The response has
amountVes: "2000.00"andamountUsd, its dollar value at your Bolívar rate (BCV or market) now.amountUsdis informative; the charge is alwaysamountVes. - Send the buyer the url
Share the
urlby WhatsApp, email or a redirect. The checkout shows Bs 2.000,00 for Pago Móvil, Débito Inmediato and card. - Confirm the payment
When it is paid,
payment.completedfires withvesAmount: "2000.00"and yourreference. You can also read the session withGET /v1/checkout/sessions/:id:statusbecomespaid.
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"]
}'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.{
"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
amountVesat 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. amountVesisnullon sessions created withamountUsd.
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
paidandpayment.completedarrives withvesAmount: "2000.00".
If something goes wrong
| Symptom | Likely cause | What to do |
|---|---|---|
400 invalid_data: "Send exactly one of amountUsd or amountVes" | Both amounts sent, or neither | Send only amountVes. |
400 invalid_data naming cop | cop requested on a bolívar-priced session | Remove cop from methods. |
422 amount_below_minimum | amountVes is worth less than your minimum charge | Raise the amount; minimumUsd in the error is the minimum in dollars. |
503 rate_unavailable | The Bolívar rate could not be read | Try again in a few minutes. |
Related: Pago Móvil-only link · Pago Móvil verification · Webhooks