Getting started

Sandbox vs Live

TagPay runs sandbox and live traffic side by side on the same hostname. There is no separate URL, no environment flag, no toggle in the dashboard. The key you authenticate with is the entire signal.

Mode is determined by the key prefix

Mode is determined by the key, not by a flag. When a request hits the TagPay API, the auth layer reads the secret-key prefix and resolves the mode from it alone:

• sk_test_* → sandbox. No real money moves. Test cards, fake balances.
• sk_live_* → live. Real cards, real settlement, real customers.

A merchant with both key pairs can switch modes simply by swapping the key in the Authorization header. No admin action, no API call, nothing else.

What happens at signup

When you sign up, TagPay provisions a sandbox subsidiary at the core-banking vendor on your behalf and stores the returned sandbox keys against your merchant record. The pk_test_* and sk_test_* pair appear in the dashboard immediately — you can start integrating in under a minute.

Live keys do not exist yet. Any request signed with a sk_live_* key will fail because there's no live subsidiary to route to.

Going live

When you submit business verification (KYC) and TagPay's ops team approves it, a background job obtains live subsidiary keys from the core-banking vendor and stores them against your merchant record. Your pk_live_* and sk_live_* pair then appears in the dashboard under Developers → API keys.

Switching modes in your app

Pick the right key per environment. The recommended pattern is one secret-key env var, wired to the correct value per deploy target:

# dev / staging
TAGPAY_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx
# production
TAGPAY_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx

Your application code reads process.env.TAGPAY_SECRET_KEY and never branches on mode. The same code path takes a test payment in dev and a real payment in production.

See Authentication for the full key reference.

Sandbox test data

Sandbox mode accepts only the test cards below. Use any future expiry date and any 3-digit CVV. The card number drives the outcome:

Real card numbers will be rejected in sandbox. Real test cards in live mode will be charged.

Testing a bank transfer or USSD payment

Open a checkout in test mode (a session created with your sk_test_ key). Choose Bank Transfer or USSD to process a payment. Because sandbox virtual accounts are real accounts you can't send live money to, use the Simulate payment button in the test-mode banner: it fires a charge.success webhook for that transaction exactly as a real customer transfer would, so you can verify your webhook handler end to end.