Most failed first calls to Interswitch aren't code bugs. They're often caused by a test key being sent to a live endpoint, a token generated from the wrong Passport host, or a terminal ID that only exists in the sandbox environment. These configuration mix-ups can be frustrating, especially when your implementation looks correct.
This guide brings together where to find your Interswitch credentials, which endpoints to use in test and live environments, and some of the common configuration issues developers encounter when integrating with Interswitch products.
Where your credentials come from
Interswitch credentials come from different platforms, depending on the service you're integrating with. One common source of confusion is obtaining credentials from the wrong platform or assuming that credentials from one service will work for another.
Here's a breakdown of where to find them:
| Place | Address | Services | What you get there |
|---|---|---|---|
| Quickteller Business (QTB) | business.quickteller.com, Developer Tools | IPG (Web Checkout, Card Payments API, Pay Bill), Merchant Wallets, Payouts, webhooks | Merchant code, pay item ID, client ID and secret, webhook secret, wallet ID |
| API Marketplace | developer.interswitchgroup.com | Identity (BVN, NIN, CAC and more), VAS (value added services - airtime and data), WhatsApp OTP | Client ID and secret per project, on the project's Test Keys tab |
| Issued by Interswitch during onboarding | Your onboarding email | VAS (bills, airtime) and IMTO | Test client ID and secret, terminal ID and reference prefix; live values after go-live |
IMTO credentials - https://remittance-portal-ui-sandbox.interswitchng.com/login
Test mode and live mode in QTB
Quickteller Business displays test keys in test mode and live keys in live mode.
Switching the dashboard to test mode to retrieve your test credentials doesn't change your live credentials or affect an application already running in production. Simply switch back to live mode when you're done. You don't need to set up a virtual card to test.
Tokens: one flow, two hosts
client ID and secret, Base64-encoding the result, and sending it to Passport to generate an access token.
Here's an example using the sandbox environment:
curl -X POST 'https://passport-sandbox.interswitchng.com/passport/oauth/token' \
-H 'Authorization: Basic <base64(clientId:clientSecret)>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=profile'
Test and live token endpoints
| Environment | Token endpoint |
|---|---|
| Test | https://passport-sandbox.interswitchng.com/passport/oauth/token |
| Live | https://passport.interswitchng.com/passport/oauth/token |
These are the two Passport hosts identified in our integration research for the services covered here.
Other Passport hosts you might encounter
Some older documentation and Postman collections contain alternative Passport URLs. These can cause authentication issues when developers use them with credentials intended for another environment.
| Host you might see | Use instead | Why |
|---|---|---|
| qa.interswitchng.com/passport/oauth/token | passport-sandbox | returns "Bad credentials" for valid keys |
| passport-v2.k8.isw.la/passport/oauth/token (IMTO docs, Marketplace Postman) | passport-sandbox | Not publicly reachable |
| sandbox.interswitchng.com/passport/oauth/token | passport-sandbox | Older guides; use the dedicated Passport host |
The API Marketplace uses https://passport-sandbox.interswitchng.com/passport/oauth/token.
How long does a token last
Don't hard-code token expiry times. Token lifetimes differ by product. The documentation shows 86,400 seconds for the payment gateway, 43,199 seconds for VAS and 39,999 seconds for IMTO. Marketplace tokens have also returned an expiry of 1,799 seconds (30 minutes). The access token expires within the period returned in the
expires_infield of the response. This value is in seconds. Your application should cache the token and refresh it before it expires rather than generating a new token for every API request.
Read your token before you debug. Decoding your access token can help you identify which services it is provisioned for and the environment it belongs to.
Some useful claims to inspect include:
| Claim | What it tells you |
|---|---|
| aud | Which services the token can call. If the service you need isn't included, your client may not be provisioned for it |
| merchant_code | The merchant associated with the token. It must match the merchant code in your requests |
| terminalID | Your VAS terminal ID. For example, 3PBL0001 is a shared test terminal |
| environment (where present) | The environment associated with the token: TEST or LIVE |
| exp | When the token expires |
If an API returns an error indicating that your token doesn't contain the required resource, inspect the aud claim before troubleshooting your implementation.
Remember: never share your complete access token or client secret when asking for technical support
Test and live, service by service
This table brings together the test credentials, endpoints and live configurations for the different Interswitch services.
| Service | Test credentials | Test hosts | Live credentials | Live hosts |
|---|---|---|---|---|
| IPG: Web Checkout | Default test merchant MX6072, pay item 9405967 |
newwebpay-sandbox.interswitchng.com/inline-checkout.js; redirect: newwebpay-sandbox.interswitchng.com/collections/w/pay; requery: sandbox.interswitchng.com/collections/api/v1/gettransaction.json
|
Your merchant code and pay item ID (format Default_Payable_MX...) from your QTB dashboard in live mode | Script and redirect: newwebpay.interswitchng.com; requery: webpay.interswitchng.com
|
| IPG: Card Payments API, Pay Bill | QTB test client ID and secret | sandbox.interswitchng.com |
QTB live client ID and secret | api.interswitchng.com |
| VAS (bills, airtime) | Client ID and secret from your setup guide; terminal ID 3PBL0001; reference prefix 1453 | qa.interswitchng.com/quicktellerservice/api/v5 |
Live client ID, secret, terminal ID and prefix, issued after SVA onboarding | Issued with your live credentials |
| Payout | QTB test client ID and secret; wallet ID from the Wallets menu | payouts-sandbox.interswitchng.com/api/v1/payouts |
QTB live client ID and secret; live wallet ID | payouts.interswitchng.com/api/v1/payouts |
| Merchant Wallets | QTB Developer Tools in test mode, once Wallets is enabled for you | sandbox.interswitchng.com |
QTB live credentials | Ask support |
| IMTO | Business portal client ID and secret; wallet created and funded on the portal | sandbox.interswitchng.com/imto |
Issued at go-live | Issued at go-live |
| API Marketplace | Project Test Keys tab | sandbox.interswitchng.com/marketplace-routing/api/v1/ |
Shown on the project after you request go-live | api-marketplace-routing.interswitchng.com/marketplace-routing/api |
A note on VAS: VAS calls require a
TerminalIdheader in addition to the Bearer token. Sending only the token can result in a401response.
A note on Web Checkout: Test merchant credentials
MX6072and9405967. The pay item ID can also appear asDefault_Payable_MX6072.
The mix-ups we see every week
These issues come from questions developers raise in the Interswitch Developer Community. If you're experiencing any of these, the cause may be a configuration mismatch rather than an issue with your implementation.
| Symptom | Usual cause | Fix |
|---|---|---|
| 401 "Bad credentials" from the token endpoint, with keys you've double-checked | Token requested from qa.interswitchng.com or passport-v2.k8.isw.la | Use passport-sandbox.interswitchng.com for test keys |
| Token works, but the API returns 401 | VAS or Send Money call without the TerminalId header, or a base URL copied from the wrong environment | Add TerminalId; check every base URL in your Postman environment, not just the first request |
| "Invalid token does not contain resource id (isw-paymentgateway)" | Your client isn't provisioned for that service | Decode the token, check aud, and ask support to enable the service |
| Production keys "don't work" | Live keys sent to a sandbox host, or test keys to a live host | Live keys only with live hosts, test keys only with test hosts |
| "Wallet not found" | Calling with test credentials for a wallet created in live, or the reverse | Use the credentials from the same mode the wallet was created in |
| Live VAS calls fail with your test terminal | Using 3PBL0001 in production | Use the terminal ID issued at go-live; 3PBL0001 is shared and test-only |
| Keys generated in the dashboard fail, keys from support work | New dashboard keys not yet mapped on Interswitch's side | Don't regenerate again; ask support to map your client ID |
| Keys generated in the dashboard fail, keys from support work | New dashboard keys not yet mapped on Interswitch's side | Don't regenerate again; ask support to map your client ID |
| Can't find merchant code or terminal ID after signing up on the Developer Console | Developer Console keys cover Marketplace APIs; VAS terminal IDs and IPG merchant codes come from elsewhere | Merchant code: QTB. VAS terminal ID: your setup guide or go-live email |
| Can't see test keys because your account is live | QTB shows test keys only in test mode | Switch to test mode, copy them, switch back; your live keys don't change |
| Inline checkout script returns 404 | Old QA script URL newwebpay.qa.interswitchng.com | Use newwebpay-sandbox.interswitchng.com |
| Sandbox URL returns an error in the browser | Sandbox APIs aren't meant to be opened in a browser | Call them from Postman, curl or your server |
| Wallet or payout request rejected though the token is valid | merchantCode in the request differs from the one in the token | Use the merchant code from the token's claims |
| Live checkout shows MERCHANT_OR_PAYMENT_ITEM_DOES_NOT_EXIST | Live merchant or pay item may not yet be active, or credentials from the wrong environment are being used | Confirm that your account is fully activated in live mode and that you're using the correct live merchant code and pay item ID. Contact support if the issue persists |
Questions the docs answer but developers often miss
Developers ask these questions repeatedly because the answers are sometimes spread across several documentation pages or older guides contain conflicting information.
What's the live Passport token URL? https://passport.interswitchng.com/passport/oauth/token. The Authentication page only shows the sandbox host; the live one appears on the Payouts page.
Where do I find my VAS terminal ID? For testing, the shared terminal ID is
3PBL0001. Your production terminal ID is issued during go-live. It isn't available on the Developer Console.
Can I use my merchant code as my terminal ID? No. They serve different purposes. A terminal ID is built from a channel ID, your terminal owner code and digits. For example,
3PBL0001. A merchant code identifies your merchant account. For example, MX6072.
What's a request reference prefix, and do I need one? For VAS, every requestReference or transferCode must start with your prefix (1453 in test). You receive your live prefix at go-live. Without it, production requests fail.
Is qa.interswitchng.com still in use? Partly. Passport is gone from that host and returns 404, so use passport-sandbox.vasv5 at /quicktellerservice/api/v5 and requery at /collections/api/v1/gettransaction.json are both still served. The newwebpay.qa subdomain is fully retired; use newwebpay-sandbox.
Do I need separate credentials for each service? Yes. Your credentials are provisioned per service. A token that works for one API returns 401 on another until that service is enabled for your client.
What's the production base URL for VAS? It's sent with your live credentials after onboarding.
Which VAS documentation is current? The Bills Payment page for API v5. Guides that use /api/v2/quickteller paths describe the older v2 API, and v2 credentials don't work on v5.
Do I need IP whitelisting? No. The production Passport host answers from internet-facing servers without IP whitelisting. If your server cannot reach the endpoint while your laptop can, investigate restrictions on your side first. One thing to check is whether the gateway's WAF is resetting connections that carry a default library User-Agent. This can look like a network restriction.
Can I test every biller and payment method in sandbox? Sandbox has a limited set of test billers and test cards (see the Bills Payment page). Sandbox card purchases go through the OTP flow; test cards don't authorise immediately. Visa 3DS also cannot be completed in sandbox.
Who is my relationship manager? Your relationship manager is assigned to you by Interswitch. They’ll provide commission and pricing for you. It isn't shown on any dashboard.
Are the card-encryption modulus and exponent the same in test and live? Yes
How you get live credentials
Live credentials aren't automatically issued after signing up. Each service has its own onboarding and activation process.
| Service | Path to live credentials |
|---|---|
| IPG (QTB) | Complete KYC, wait for your account to be activated, switch QTB to live mode; Developer Tools then shows your live client ID, secret, merchant code and pay item ID |
| VAS | Test with the Postman collection, complete the UAT test script, send to your relationship manager; after the VAS onboarding you receive live client ID, secret, terminal ID, reference prefix and base URLs |
| Payouts and Merchant Wallets | Ask your relationship manager to enable Wallets and Payouts on QTB; then use QTB live credentials and fund your live wallet by bank transfer |
| IMTO | Register and complete profiling on the business portal; live hosts are issued at go-live |
| API Marketplace | On your project, request go-live; once approved, live credentials appear on the project |
Go-live checklist
Before moving your integration to production, confirm that you've updated all environment-specific configurations.
Live token host: passport.interswitchng.com
Every base URL switched, including requery and status URLs
Live merchant code, pay item ID, terminal ID and reference prefix in config; no 3PBL0001 anywhere
Web Checkout mode set to LIVE
Split aliases exist in live (if you split payments)
Live webhook URL set and tested with a few real payments
A small real transaction, confirmed by requery with code 00
Still stuck? Check #environment-status in the Interswitch Developer Community Slack for outage updates. If you still need help, ask in #help and include - business name, relationship manager, environment (test or live), service you're integrating.
Never share your client secret, access token in the community.
FAQ
Which token URL do I use for testing? https://passport-sandbox.interswitchng.com/passport/oauth/token.
Which token URL do I use in production? https://passport.interswitchng.com/passport/oauth/token.
Where do I find my merchant code and pay item ID? In Quickteller Business, under Developer Tools.
Where do I find my VAS terminal ID? Test: 3PBL0001 in your setup guide. Live: issued at go-live.
Why does my token work in test but not in live? Test and live use different keys and hosts. Live keys only work against live hosts.
Got further questions or need support? Join our community on Slack and we'll be right there to help you through.

Top comments (0)