DEV Community

Chizurum Egwunwankwo for Interswitch Developer Community

Posted on Edited on

Interswitch Credentials, Portals and Environments - the test and live cheat sheet

documentation for Interswitch payment gateway, API Marketplace, VAS, Payout and IMTO

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'
Enter fullscreen mode Exit fullscreen mode

Test and live token endpoints

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_in field 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 TerminalId header in addition to the Bearer token. Sending only the token can result in a 401 response.

  • A note on Web Checkout: Test merchant credentials MX6072 and 9405967. The pay item ID can also appear as Default_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


Got further questions or need support? Join our community on Slack and we'll be right there to help you through.

Top comments (0)