Test mode

Test your integration before real money moves.

Every business account has a test mode. It uses the same API, the same checkout and the same webhooks as live, with test keys, test cards and test buyers. Nothing you do there touches real money, real banks or real customers.

1. Get a test key

In your dashboard, open API keys, choose Test keys and create one. Test keys start with pclk_test_; live keys start with pclk_live_. You don't need to finish verification to use test mode.

Every answer to a test key says "livemode": false and has the header Payclio-Mode: test. A test key never sees live data, and a live key never sees test data.

curl -X POST https://payclio.com/api/v1/payment-requests \
  -H "Authorization: Bearer pclk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100.00", "currency": "NAD", "reference_type": "order", "reference_id": "1001" }'

# 200   (header Payclio-Mode: test)
{ "data": { "payment_request": { "token": "...", "hosted_url": "https://app.payclio.com/req/...", ... } },
  "livemode": false }

2. Pay the test link

A test link's checkout has an orange TEST MODE bar. Pay it any of three ways:

  • Test cards. Use any future expiry date, any CVC and any name.
  • Test buyers. Each business has two test buyers with 10,000.00 in NAD, USD and ZAR test money. Choose one and press Pay as test buyer, like a customer paying from their Payclio wallet. Reset their balances on the API keys page.
  • Simulate. Simulate successful payment and Simulate declined card settle the link at once, without a card.
Test cardWhat happens
4242 4242 4242 4242Paid straight away.
4000 0025 0000 3155Asks for 3D Secure, then paid.
4000 0000 0000 0002Declined (card_declined).
4000 0000 0000 9995Declined (insufficient_funds).

3. Receive test webhooks

On the Webhooks page, choose Test endpoints and add your staging server's address. Test payments send the same signed events as live ones, marked "livemode": false. Use Send test event to send an example of any event (marked "test_event": true) whenever you like.

{
  "id": "evt_...",
  "event": "payment_request.paid",
  "created_at": "2026-11-15T10:00:00Z",
  "livemode": false,
  "data": { "token": "...", "status": "paid", "amount": "100.00", "currency": "NAD",
            "reference_type": "order", "reference_id": "1001", ... }
}

4. See it in your dashboard

Switch on Test mode at the top of your dashboard to see test links, invoices, payments, balances and refunds. Everything works as in live mode, except money can't leave: withdrawals, Pay, payouts, saved cards and card subscriptions are off in test mode.

Reset test data on the API keys page gives you a clean test account. Your test keys and test webhook endpoints keep working.

5. Go live

Before you switch, check that:

  1. Your integration creates links with the test key and handles the answer.
  2. A test payment reaches your server as payment_request.paid and you mark the order paid once.
  3. A declined card and an expired link leave the order unpaid.
  4. Your webhook checks the X-Payclio-Signature header and ignores events older than 5 minutes.
  5. Your server checks "livemode" so a test event can never mark a real order paid.
  6. Your business is verified, then you swap the test key for a live key and add a live webhook endpoint.

The dashboard shows this checklist with what your account has already done, on the API keys page under Test keys.