Skip to main content
Build and verify your integration with test keys and test cards. When it works end to end and your account is activated, switch to live keys to accept payments.

​
Service URLs

Use the same URLs in test and live mode: The SDKs use these URLs by default. Embedded checkout takes its frame URL from the session’s embed_url.

​
Test mode and live mode

Each API key carries its mode in its name. The mode segment — test or live — determines which dataset the request reads and writes: Every object the API returns carries a livemode boolean, and so does every webhook event. Test-mode objects have "livemode": false; live-mode objects have "livemode": true. A test key can never see, mutate, or charge live data, and the reverse holds too.
Examples use a placeholder secret key, sk_v1_test_.... Your real keys share this shape — the test or live mode segment selects test or live data. Copy them from the dashboard.

​
Test with a sandbox card

Use this card in Checkout or Ionic Blocks to test your integration: Use it to exercise the real flow — create a checkout session or payment intent, confirm it, and watch the resulting webhook arrive — exactly as you will in production. Test both the approval path and a decline so your error handling is exercised before real buyers hit it.

​
Go-live checklist

1

Prove the flow in test mode

Run your full integration against test keys: collect a payment, verify the result from your backend (not just the browser redirect), and confirm your webhook endpoint receives and verifies the event. Exercise a decline and a retry with the same Idempotency-Key.
2

Activate your account for live payments

Live processing requires your account’s payment capability to be approved and activated. Complete activation before switching keys — a live key cannot charge until the capability is active.
3

Switch to live keys

Replace your test secret key with your live secret key (sk_v1_live_…) in your server configuration, and your test publishable key with the live publishable key in your client. Keep the secret key in your secret manager. Only the publishable key belongs in your browser integration.
4

Register your live payment website

Domain registrations are mode-scoped. For Blocks, register the website in live mode under Developers → Web domains; a platform registers it under Connect → Domains. Embedded checkout uses its domain registration, and Apple Pay has a separate domain setup.
5

Register live webhook endpoints

Webhook endpoints are mode-scoped: a test-mode endpoint only receives test events. Create your endpoints again with a live key, and store the new whsec_… signing secret each one returns — it is shown only once.
6

Verify with a real transaction

Run one real, low-value payment with a live key and a real card, confirm it settles, then refund it. This proves your live keys, payment setup, and webhook delivery all work together before you open the flow to buyers.

​
What changes between test and live

Most behavior is identical by design — that is the point of test mode. A few things differ:
Test and live data never mix. IDs created in test mode (cus_…, pi_…, sub_…) do not exist in live mode. Re-create the objects your integration needs — customers, products, prices, payment links — with a live key, or create them on first use in production.

​
Operational guidance

  • Keep matching test keys and live keys in separate configuration. Check livemode on the result before fulfilling.
  • Register live webhook endpoints and verify a live signature before launch. A missing live endpoint means your fulfillment never fires for real orders.
  • Move idempotency keys, decline handling, and webhook verification into production unchanged; they were the point of building in test mode. Don’t simplify them for launch.
  • Retrieve the PaymentIntent or checkout session from your backend before fulfilling a live order. Do not rely on the browser redirect.
  • After go-live, watch payment_intent.payment_failed and invoice.payment_failed events to catch real-world declines you didn’t see in the sandbox.

​
Launching a Connect integration

Each receiving merchant needs an active live connection with the permissions your integration uses. Connections, customers, and object IDs are separate in test and live mode, so each live request uses the merchant’s live customer and payment IDs. For card saving, the platform key and the merchant’s connection need setup_intents:write and setup_intents:read. Verify one live SetupIntent for the intended merchant and customer before recording saved cards. Register a live platform webhook endpoint and match event.account to the merchant stored with each payment. See Accept payments for connected accounts and Save cards for connected accounts.

​
What’s next

Handle webhook events

Verify each event’s signature and fulfill orders from it.

Reliable API requests

Retry safely and recover when a response does not arrive.

Errors

Read the error envelope and what each status code means.

Decline codes

Look up what each card decline means and whether the same card can succeed later.