Test your whole integration in Test mode

What you will do

Every account has a Live and a Test side. Test works from day one, uses sandboxes, and never charges a real buyer. By the end of this playbook you will have completed a test payment for each method you plan to offer, received and verified its webhook, and read the result in your balance.

• Access to the portal (the login link VEXPay sent you).
• A server that can make HTTPS requests and receive one public HTTPS webhook (use a tunnel when developing locally).

Steps

1. 01
   Switch the portal to Test

   Use the Live | Test toggle in the portal header. You stay signed in. Everything you create while Test is selected belongs to your Test account.

2. 02
   Create a Test key

   Open Credentials, name the key after the integration that will use it (for example "Backend") and click Create key. Copy the key when it is shown and store it in your server environment as VEXPAY_API_KEY.

3. 03
   Register a Test webhook endpoint

   Open Webhooks → New endpoint, or call POST /v1/webhooks with the Test key. Save the signing secret — it is shown only once. Then click Send test. Full detail: Set up webhooks.

4. 04
   Pay once with every method you will offer

   Create a checkout session (or a payment link) with the Test key and pay it. The test controls for each method are in the table below.

5. 05
   Try the failure paths too

   Use a wrong code, let a payment expire, or use a card that declines, and check that your system reacts to payment.failed and payment.canceled without fulfilling the order.

6. 06
   Read the result

   Call GET /v1/payments/:id and GET /v1/balance with the Test key. Test accounts have no balance hold, so test credits are available at once.

curl --request POST "${API_URL}/v1/checkout/sessions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountUsd": 5.00,
    "description": "Test order",
    "reference": "test-order-1"
  }'
# Open the "url" from the response and pay with the test controls below.

Check that it worked

• Each test payment shows COMPLETED in GET /v1/payments/:id (COP: completed in GET /v1/cop/payments/:id) and on the portal Payments page.
• Your endpoint received payment.completed with livemode: false, and your signature check passed. Portal → Webhooks → Delivery history shows the delivery as successful.
• Your order was marked paid exactly once, even when you replayed the same event.

What behaves differently in Test

• No balance hold: test credits are available immediately (live credits are held for 24 hours).
• Conversions to USDT complete in the same request, and test stablecoin payouts complete at once without a transaction hash.
• Payout-account and seller micro-deposits, and Bolívar payouts, move real céntimos even in Test (always under Bs 0.50 in total). Use a real Pago Móvil destination and read the amounts from the statement.
• USDT, USDC and Colombian pesos appear in Test only when VEXPay has enabled them on your account.

If something goes wrong

Related: Integration path · Going live · Go live