Verifica una transferencia de Pago Móvil

Pago Móvil en el checkout

El checkout, los links de pago y las sesiones de checkout pueden ofrecer Pago Móvil junto a tarjeta y Débito Inmediato (el débito bancario con clave OTP, c2p). El comprador envía el Pago Móvil desde la app de su banco y VEXPay lo confirma solo: no necesitas llamar a verify.

1. 01
   El comprador ingresa sus datos

   Cédula o RIF y el teléfono desde el que pagará.

2. 02
   VEXPay le muestra a dónde pagar

   El banco, teléfono y RIF de destino, y el monto exacto en bolívares, cada uno con botón de copiar. El monto se calcula a tu tasa del bolívar (BCV o mercado) del momento en que empieza.

3. 03
   El comprador paga desde la app de su banco

   Desde el mismo teléfono que indicó. VEXPay compara la transferencia por teléfono, monto y hora, completa el pago y envía payment.completed, normalmente en segundos.

4. 04
   Alternativa: banco y referencia

   Si pagó desde otro teléfono y no se confirma en 5 minutos, elige el banco desde el que pagó y escribe el número de referencia para confirmarlo.

curl --request POST "${API_URL}/v1/checkout/sessions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "amountUsd": 10.00, "methods": ["pago_movil"] }'

Muestra al cliente a dónde pagar

Antes de que el cliente abra la app de su banco, muéstrale la cuenta a la que debe enviar el Pago Móvil. El banco, el teléfono y la identificación vienen de GET /v1/payments/pago-movil/receiving-account; nunca los escribas a mano.

curl "${API_URL}/v1/payments/pago-movil/receiving-account" \
  --header "x-api-key: ${VEXPAY_API_KEY}"

const account = await vexpay.payments.pagoMovil.receivingAccount();
if (account.configured) {
  // Show: account.bankName (account.bankCode), account.phone, account.identification
}

account = vexpay.payments.pago_movil.receiving_account()
if account.configured:
    # Show: account.bankName (account.bankCode), account.phone, account.identification
    ...

{
  "provider": "…",
  "bankCode": "0000",
  "bankName": "Banco receptor",
  "phone": "04125555555",
  "identification": "13536734",
  "configured": true,
  "missing": [],
  "livemode": true
}

La cuenta sigue tu enrutamiento de Pago Móvil: el mismo proveedor que usa POST /v1/payments/pago-movil/verify según tus proveedores habilitados y predeterminado, omitiendo cualquier proveedor que no tenga permitido Pago Móvil en tu cuenta. No hay forma de cambiarlo, así que lo que muestras siempre es la cuenta que verify revisa. Consúltala al momento del checkout o guárdala en caché por poco tiempo; solo cambia cuando cambia tu enrutamiento.

Verifica la referencia

curl --request POST "${API_URL}/v1/payments/pago-movil/verify" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "usdAmount": 8.75,
    "reference": "12345678",
    "dateMovement": "2026-07-20",
    "externalRef": "order_demo_1044"
  }'

reference debe contener entre 4 y 32 dígitos. dateMovement es opcional y usa el formato YYYY-MM-DD.

Envía la referencia tal como aparece en el comprobante del banco del cliente, o al menos sus últimos 6 dígitos: los bancos numeran la misma transferencia de forma distinta, así que cuando la transferencia se confirma con la notificación del banco, VEXPay compara los últimos 6 dígitos. Si el cliente envió más bolívares de los solicitados, el pago se completa por el monto realmente recibido — toma vesAmount y usdAmount del recibo, no de tu solicitud. Si envió menos, sigue fallando por diferencia de monto.