Onboard a seller and verify their payout account

For marketplaces: register a seller, confirm their Pago Móvil destination with two micro-deposits, and set their commission so you can split payments and pay them out.

What you will do

A seller is someone your marketplace collects for. In the API a seller is a merchant (/v1/merchants). Before you can pay a seller, their Pago Móvil destination must be verified with two small deposits that the seller reads from their bank.

A marketplace account (VEXPay sets the business model; see Seller or marketplace).
The seller's name, cédula or RIF, contact email and phone, and the bank and phone of their Pago Móvil.
A webhook endpoint subscribed to merchant.verified and merchant.rejected.

Steps

Register the seller
POST /v1/merchants with your own seller id as externalRef (unique, and the idempotency key), name, identification (V/E + 8 digits or J/G + 9 digits), contactEmail, contactPhone, and bankCode (4 digits) + phone (11-digit local mobile, for example 04121234567) for their first payout method. Optionally add applicationFeePercent (their commission) and autoPayoutEnabled.
Start verification
POST /v1/merchants/:id/payout-methods/:methodId/verify/start. VEXPay sends two deposits of a few céntimos to the seller's Pago Móvil.
The seller reads the two amounts
Ask the seller for both amounts from their bank statement. They have 2 days.
Confirm the amounts
POST /v1/merchants/:id/payout-methods/:methodId/verify with amount1 and amount2. You have 3 attempts.
Set the commission (optional)
Per seller with PATCH /v1/merchants/:id or the Commission column in Portal → Merchants, or a default for everyone in Portal → Merchants → Default commission.

Registerbash

curl --request POST "${API_URL}/v1/merchants" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "externalRef": "seller-881",
    "name": "Panadería La Esquina",
    "identification": "J123456789",
    "contactEmail": "ventas@laesquina.example",
    "contactPhone": "04121234567",
    "bankCode": "0102",
    "phone": "04121234567",
    "applicationFeePercent": 5
  }'

Confirm micro-depositsbash

curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods/METHOD_ID/verify" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "amount1": "0.37", "amount2": "0.82" }'

Check that it worked

You received merchant.verified for the seller.
GET /v1/merchants/:id/payout-methods shows the method as verified.
The seller appears as active in Portal → Merchants with the commission you set.

If something goes wrong

Symptom	Likely cause	What to do
422 `merchant_identification_missing`	No cédula/RIF on file for the seller	Add `identification` with `PATCH /v1/merchants/:id`.
422 `credit_rejected` or `merchant.rejected`	The bank rejected the destination (bank, phone or cédula do not match)	Check the details with the seller and add a corrected method.
`amounts_mismatch` with `attemptsLeft`	Wrong amounts	Re-read the statement. After 3 failures the method is locked for 24 hours.
410 `window_expired`	Not confirmed within 2 days	Start verification again.
409 `external_ref_conflict`	Same `externalRef` sent with different data	Use the existing seller (`GET /v1/merchants?externalRef=…`) or a new id.

Next: Split payments. Related: Merchants & payouts · Marketplace settlement