Test your integration

ChainPay has a test mode, as Stripe does. You get test API keys, test payments, test webhooks and a test checkout page, and nothing moves real money. Full API details are in the API reference.

Switch on test mode

Sign in to the dashboard and turn on Test mode in the header. An orange bar shows while it's on, and every page shows only test data: test payments, checkout sessions, invoices, customers, payment links, products and webhook endpoints. Turn it off to go back to live data. The two never mix.

You don't need a payout wallet or a connected provider to try crypto in test mode.

Create a test API key

With test mode on, go to Developers, API keys and create a key. It starts with cpk_test_. Keys made with test mode off are live keys and start with cpk_live_. Keys made before test mode existed start with cpk_ and are live.

A test key only creates and sees test objects, and a live key only live ones. Asking a live key for a test payment returns 404. Every payment, checkout session and webhook endpoint has a livemode field, which is false in test mode.

bash
curl https://api.chainpay.ac/v1/checkout-sessions \
  -H "Authorization: Bearer cpk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "12.00", "currency": "USD" }'

Open the checkout_url it returns. The page shows a test banner, and offers only the methods that work in test mode.

Simulate a crypto payment

Test crypto payments never touch a blockchain. The deposit address reads TEST MODE: do not send funds, which isn't an address on any chain, and no network fee is added. Instead of sending coins, choose what happens. There are three ways.

  • On the checkout page. Pay with crypto, and the page shows buttons in place of the QR code: Paid, Underpaid, Expired and Failed.
  • In the dashboard. Open the payment under Payments. Its page has a "Simulate this test payment" card with the moves it can still make.
  • From your code, with a test key:
bash
curl https://api.chainpay.ac/v1/test/payments/PAYMENT_ID/simulate \
  -H "Authorization: Bearer cpk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Or with the TypeScript SDK:

typescript
import { ChainPay } from 'chainpay-sdk';

const chainpay = new ChainPay(process.env.CHAINPAY_TEST_KEY!); // cpk_test_...
chainpay.isTestMode; // true

const payment = await chainpay.createPayment({
  amount: 12,
  rail: 'crypto',
  chain: 'polygon',
  token: 'USDC',
});
// payment.livemode is false, and payment.deposit_address is
// "TEST MODE: do not send funds".

await chainpay.simulatePayment(payment.id, 'paid');    // sends payment.paid
await chainpay.simulatePayment(payment.id, 'settled'); // sends payment.settled
statusWhat it means
paidThe customer sent the full amount. Sends payment.paid.
partially_paidThe customer sent too little. Sends payment.partially_paid.
settledPaid and paid out to you. Passes through paid first, so both payment.paid and payment.settled are sent.
expiredThe time to pay ran out. Sends payment.expired.
failedThe payment failed. Sends payment.failed.

A payment only moves forward, as a real one does. A settled payment can't change, and a paid one can't go back to partially paid or expired. A move that isn't allowed returns 409. Only test crypto payments can be simulated.

Test cards

Cards, Apple Pay and Google Pay in test mode run on your own Stripe test key. With test mode on, open Connect and add your Stripe secret key that starts with sk_test_ (or a restricted rk_test_ key). It's kept apart from your live key, and live mode refuses test keys.

Then pay on the checkout page with one of Stripe's test cards. Use any future expiry date and any CVC.

Card numberWhat happens
4242 4242 4242 4242Paid straight away.
4000 0025 0000 3155Asks for 3D Secure. Approve it on the test page to pay, or fail it to see a declined check.
4000 0000 0000 0002Declined by the bank. The checkout shows the decline and lets the customer try again.

Stripe lists more cards, for other countries, brands and declines, in its testing guide. SEPA, Klarna, Afterpay, Affirm and PayPal through Stripe also run on the same test key, using Stripe's test pages.

Zelle works in test mode as it does live: mark the payment received yourself on its page.

Test webhooks

With test mode on, add an endpoint under Developers, Webhooks. Test events go only to endpoints added in test mode, and live events only to live endpoints, so a test payment never reaches your live server. Every test event carries "livemode": false, and is signed with the test endpoint's own secret.

javascript
const event = JSON.parse(rawBody);
if (event.livemode === false) {
  // A test payment: don't ship anything.
}

Simulating a payment sends the same events a real payment would, so you can check your whole flow, from payment.created to payment.settled.

What test mode doesn't do

  • Some methods are live only: Stripe Connect, PayPal apps you connect yourself, ACH, Cash App, PIX, M-Pesa, Alipay, WeChat Pay, UPI and Amazon Pay. They aren't offered in test mode.
  • No emails to customers. Test payments send no payment emails or receipts. Invoice and payment link emails in test mode go only to your own account email, marked [Test].
  • Separate numbers. Test payments don't count in your live stats, and test invoices are numbered on their own, starting with TEST-.

Going live

Turn off test mode, add a payout wallet under Settings, Payouts, and create a live key. Swap your test key for the live one on your server, and add your live webhook endpoints. Nothing you made in test mode carries over.