Troubleshoot a Pago Móvil payment that is not found

The buyer says they paid but the checkout keeps waiting or verify returns not found: check the matching rules, use the reference fallback, retry safely, and know when to contact support.

What you will do

A Pago Móvil is sent by the buyer from their own bank app, so VEXPay has to find it. Work out which case you are in, then follow the matching steps.

You see	Go to
The hosted checkout keeps waiting after the buyer paid	Hosted checkout
`POST /v1/payments/pago-movil/verify` returns 400 `MOVEMENT_NOT_FOUND` or `AMOUNT_MISMATCH`	API verify
The payment shows `FAILED` with `expired`	Expired payments

VEXPay completes the payment automatically when the transfer matches on all three: the phone the buyer entered, the amount shown (within Bs 0.02), and the time (from 2 minutes before the buyer started until the 15-minute expiry).

Ask how the buyer paid
From another phone? A different amount? Two open payments on different links? Any of these stops the automatic match.
Use the reference fallback
After 5 minutes without a match, the checkout lets the buyer pick the bank they paid from and type the bank reference. It is found when the last 6 digits and the amount match, the transfer came from that bank, was received in the last 7 days, and was not claimed before.
Check the messages
"Aún no hemos recibido…": wait a moment and check the number. "salió de otro banco": pick the bank the transfer was sent from. An amount message: the buyer did not pay the exact amount — contact VEXPay support with the reference.

API verify

Retry with backoff
The bank's notice can lag a few seconds behind a real transfer. Retry every 3–5 seconds for 60–90 seconds with the same reference; retries reuse the same payment.
Check the reference
4–32 digits. Send it as the receipt shows it, or at least the last 6 digits.
Send the optional fields you have
debtorBankCode (the payer's bank) and debtorCellPhone are required by some receiving banks. Send them when you have them, and dateMovement (YYYY-MM-DD) when the transfer is not from today.
Check the amount
AMOUNT_MISMATCH returns what was expected and what was received. The expected bolívares are your usdAmount at your Bolívar rate. Fix usdAmount or ask the buyer to complete the amount; the transfer stays claimable.
Check where the buyer paid
The buyer must pay the account returned by GET /v1/payments/pago-movil/receiving-account — never a hard-coded one.
Do not verify twice
After a 200, re-check with GET /v1/payments/by-ref/:externalRef instead of calling verify again.

curlbash

curl --request POST "${API_URL}/v1/payments/pago-movil/verify" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "usdAmount": 20.00,
    "reference": "00123456",
    "debtorBankCode": "0102",
    "debtorCellPhone": "584121234567",
    "txType": "pago_movil",
    "externalRef": "order-2051"
  }'

Expired payments

A hosted Pago Móvil that is not matched within 15 minutes becomes FAILED with expired, and payment.failed fires. A transfer that arrives later is not credited automatically. Contact VEXPay support with the bank reference, the amount and the date.

Check that it worked

GET /v1/payments/:id shows COMPLETED with the bank reference, and payment.completed arrived.
In Test, real transfers never match: use Simular pago recibido on the checkout, or a Test key for verify.

Other causes

Symptom	Likely cause	What to do
Pago Móvil not offered, or `receiving_account_not_configured`	The receiving account is not complete for your account	Contact VEXPay.
400 "no enabled provider supports Pago Móvil"	Pago Móvil is not enabled for your account	Contact VEXPay.
Several transfers share the same last 6 digits	The match is ambiguous, so nothing is claimed	Send the full reference and `debtorBankCode`; contact VEXPay support if it persists.
`payment.reversed` with `bank_not_received`	VEXPay found the money never arrived	Treat the order as unpaid. Contact VEXPay support for details.