Guía para desarrolladores
Sitio de VEX PayReferencia de API
Explorar documentación

Cobra un monto exacto en bolívares (por ejemplo Bs 2.000,00)

Crea una sesión de checkout con amountVes para que al comprador se le pidan exactamente los bolívares que indiques, sin importar la tasa.

Qué vas a hacer

Con amountUsd, el monto en bolívares que ve el comprador es tus dólares × la tasa al momento de pagar, así que casi nunca es redondo (por ejemplo Bs 1.996,33). Si tus precios están en bolívares, envía `amountVes`: Pago Móvil, Débito Inmediato y tarjeta piden exactamente ese monto, sin importar la tasa.

  • Tu clave de API en tu servidor.
  • Métodos en bolívares (Pago Móvil, Débito Inmediato o tarjeta) activos en tu cuenta.
  • El monto en bolívares, con hasta 2 decimales.

Pasos

  1. Crea la sesión con amountVes

    Llama a POST /v1/checkout/sessions con amountVes (por ejemplo 2000.00) y sin amountUsd. Envía solo uno de los dos.

  2. Guarda la respuesta

    La respuesta trae amountVes: "2000.00" y amountUsd, su valor en dólares a tu tasa Bolívar (BCV o mercado) en este momento. amountUsd es informativo; el cobro siempre es amountVes.

  3. Envíale el url al comprador

    Comparte el url por WhatsApp, correo o una redirección. El checkout muestra Bs 2.000,00 para Pago Móvil, Débito Inmediato y tarjeta.

  4. Confirma el pago

    Cuando se paga, llega payment.completed con vesAmount: "2000.00" y tu reference. También puedes leer la sesión con GET /v1/checkout/sessions/:id: status pasa a 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": "Pedido #2051",
    "reference": "order-2051",
    "methods": ["pago_movil", "c2p"]
  }'
Node SDKjavascript
const session = await vexpay.checkout.sessions.create({
  amountVes: 2000, // exactamente Bs 2.000,00
  description: 'Pedido #2051',
  reference: 'order-2051',
  methods: ['pago_movil', 'c2p'],
});
// session.amountVes === '2000.00'
// session.amountUsd: '2.18' (2000 a tu tasa)
// Send session.url to the buyer.
Respuestajson
{
  "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"]
}

Bueno saber

  • El cobro mínimo y el máximo (US$100.000) se revisan con amountVes a tu tasa Bolívar al crear la sesión.
  • USDT y USDC siguen disponibles: el comprador paga Bs ÷ la tasa al momento de pagar, redondeado hacia arriba al céntimo.
  • Los pesos colombianos (cop) no se ofrecen en una sesión con precio en bolívares.
  • amountVes es null en las sesiones creadas con amountUsd.

Comprueba que funcionó

  • Abre el url: el checkout pide Bs 2.000,00.
  • En Test, pulsa Simular pago recibido en la pantalla de espera de Pago Móvil: la sesión pasa a paid y llega payment.completed con vesAmount: "2000.00".

Si algo sale mal

SíntomaCausa probableQué hacer
400 invalid_data: "Send exactly one of amountUsd or amountVes"Enviaste los dos montos, o ningunoEnvía solo amountVes.
400 invalid_data que menciona copPediste cop en una sesión con precio en bolívaresQuita cop de methods.
422 amount_below_minimumamountVes vale menos que tu cobro mínimoSube el monto; minimumUsd en el error es el mínimo en dólares.
503 rate_unavailableNo se pudo leer la tasa BolívarIntenta de nuevo en unos minutos.

Relacionado: Enlace solo Pago Móvil · Verificación de Pago Móvil · Webhooks