API ReferenceDeveloper ConsoleDeveloper Community

Card Payments API

Suggest Edits

Card payment APIs allow businesses to accept card payments online and in mobile apps. They provide a secure and efficient way to process payments and can be integrated with various payment methods.

It also allows you to manage the payment flow from end to end. This means that you can build your own user interfaces and customer experiences.

📘

You must have a PCI DSS compliance certificate to use the Card Payments API.

Getting started with the Card Payments API

Prerequisite:

To get started with the Card Payments API, you will need to

1: Generate an access token

You can use the Interswitch OAuth 2.0 client credentials grant type to generate an access token. To do this, make a POST request to the following endpoint:

<https://apps.qa.interswitchng.com/passport/oauth/token>

In the Authorization header, set the value to Basic <base64_encoded_client_credentials>, where <base64_encoded_client_credentials> is the base64 encoded string of your client ID and secretkey, separated by a colon (:).

For more information click here

In the request body, set the following parameter:

grant_type: client_credentials

Request

{
    "customerId": "1407002510",
    "amount": "20000",
    "transactionRef": "12n345mmm0km655",
    "currency": "NGN",
    "authData": "UXkWjeEhriu0Sn0TkwD7avRNpbwd8b1GFBp3pF4AqWE+xh7g0NslORTk8Tj6N1Ujug7UkuVKtDbjedEJadvHQht8D37RJqaljE1J1BWkbftfHhETMnLmAhthr6jFnrVXKGNRRCEaDx
qj+ssw5Yh4zInVQGAAc2R5l/nSgBiMP+4wThanlJyB+xPL8F7smByidJZy0FpuEEDBzjxdqXfVyEwLzYJH9zIFSCxeogINtx4W4UVWm7z/ObCom+oJXT2jmRhx3xrFmTFvL2HJV1Gwz
cu1dAIzq2arGfc+z+9gDzWEo3tzRuH/mSE739c5bC4dxRpaKHIeokNVtOUxZpCBcA=="
}'

If the request is successful, you will receive a JSON response containing the access token. You can then use the access token to authenticate your requests to the Interswitch API.

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9jb2RlIjoiTVg2MDcyIiwicmVxdWVzdG9yX2lkIjoiMTIzODA4NTk1MDMiLCJpbmNvZ25pdG9fcmVxdWVzdG9yX2lkIjoiMTIzODA4NTk1MDMiLCJwYXlhYmxlX2lkIjoiMzM1OTciLCJjbGllbnRfZGVzY3JpcHRpb24iOm51bGwsImNsaWVudF9pZCI6IklLSUFCMjNBNEUyNzU2NjA1QzFBQkMzM0NFM0MyODdFMjcyNjdGNjYwRDYxIiwiYXVkIjpbImFwaS1nYXRld2F5IiwiYXJiaXRlciIsImNhZXNhciIsImhpbXMtcG9ydGxldCIsImluY29nbml0byIsImlzdy1jb2xsZWN0aW9ucyIsImlzdy1jb3JlIiwiaXN3LWluc3RpdHV0aW9uIiwiaXN3LWxlbmRpbmctc2VydmljZSIsImlzdy1wYXBlIiwiaXN3LXBhcHJzIiwiaXN3LXBhcHNzIiwiaXN3LXBheW1lbnRnYXRld2F5IiwiaXN3LXBvc3Qtb2ZmaWNlIiwia3ljLXNlcnZpY2UiLCJwYXNzcG9ydCIsInBvc3RpbGlvbi1hcGkiLCJwcm9qZWN0LXgtY29uc3VtZXIiLCJwcm9qZWN0LXgtbWVyY2hhbnQiLCJxdC1zZXJ2aWNlIiwicXVpY2t0ZWxsZXItZXRsci1yZXF1ZXJ5IiwicmVjdXJyZW50LWJpbGxpbmctYXBpIiwidHJhbnNmZXItc2VydmljZS1hZG1pbiIsInRyYW5zZmVyLXNlcnZpY2UtY29yZSIsInZhdWx0Iiwidm91Y2hlci1hcGkiLCJ3YWxsZXQiLCJ3ZWJwYXktcG9ydGxldCJdLCJjbGllbnRfYXV0aG9yaXphdGlvbl9kb21haW4iOiJNWDYwNzIiLCJzY29wZSI6WyJjbGllbnRzIiwicHJvZmlsZSJdLCJhcGlfcmVzb3VyY2VzIjpbInJpZC1QT1NUL2FwaS92MS9wdXJjaGFzZXMiLCJyaWQtUE9TVC9hcGkvdjEvcHVyY2hhc2VzLyoqIiwicmlkLVBVVC9hcGkvdjEvcHVyY2hhc2VzIiwicmlkLVBVVC9hcGkvdjEvcHVyY2hhc2VzLyoqIiwicmlkLUdFVC9hcGkvdjEvcHVyY2hhc2VzIiwicmlkLUdFVC9hcGkvdjEvcHVyY2hhc2VzLyoqIiwicmlkLURFTEVURS9hcGkvdjEvcHVyY2hhc2VzIiwicmlkLURFTEVURS9hcGkvdjEvcHVyY2hhc2VzLyoqIiwicmlkLVBPU1QvYXBpL3YyL3B1cmNoYXNlcyIsInJpZC1QT1NUL2FwaS92Mi9wdXJjaGFzZXMvKioiLCJyaWQtUFVUL2FwaS92Mi9wdXJjaGFzZXMiLCJyaWQtUFVUL2FwaS92Mi9wdXJjaGFzZXMvKioiLCJyaWQtR0VUL2FwaS92Mi9wdXJjaGFzZXMiLCJyaWQtR0VUL2FwaS92Mi9wdXJjaGFzZXMvKioiLCJyaWQtREVMRVRFL2FwaS92Mi9wdXJjaGFzZXMiLCJyaWQtREVMRVRFL2FwaS92Mi9wdXJjaGFzZXMvKioiLCJyaWQtUE9TVC9hcGkvdjMvcHVyY2hhc2VzIiwicmlkLVBPU1QvYXBpL3YzL3B1cmNoYXNlcy8qKiIsInJpZC1QVVQvYXBpL3YzL3B1cmNoYXNlcyIsInJpZC1QVVQvYXBpL3YzL3B1cmNoYXNlcy8qKiIsInJpZC1HRVQvYXBpL3YzL3B1cmNoYXNlcyIsInJpZC1HRVQvYXBpL3YzL3B1cmNoYXNlcy8qKiIsInJpZC1ERUxFVEUvYXBpL3YzL3B1cmNoYXNlcyIsInJpZC1ERUxFVEUvYXBpL3YzL3B1cmNoYXNlcy8qKiJdLCJleHAiOjMyNzQ4MDc2MzMsImNsaWVudF9uYW1lIjoiUjdqSmhyRWd5TCIsImNsaWVudF9sb2dvIjpudWxsLCJqdGkiOiIyMzlkZWY0My0wZmU3LTRlM2UtYTM2Zi04NTgyOGZjZDVkZTAifQ.JKs7UMK1QwGCw4Vkobp_qUBXQN27yzJAPmgyId7FuFZu-xY8oseKUwSrRlNlMQ3mQirZyTfHfakOXiUKda1wNHrnB3yyefcT2D16EJfCriEub4vhdvJGjMie5D5x0tHZvA98vK7uPZnTxPLNpoZKteo7VKmnwuVPp_fXBlDndkU3zxCYkWRfOpKU1lpJBhU8N22BSTLUTYmeCVILjsQj1w9acDYby8ewJxDXLKawuDtwZXOn0DUpo4kUZ0bIJHqPuP69Rnti8zvKfKPMbcIq1mcUg_AlGkFJLg92w15cXVuKxT7dqx0zDHYh7Qh1DXAltC3mWdQUvVSqfBAiixYSgg",
  "token_type": "bearer",
  "expires_in": 1577847599,
  "scope": "clients profile",
  "merchant_code": "MX6072",
  "client_authorization_domain": "MX6072",
  "requestor_id": "12380859503",
  "api_resources": [
    "rid-POST/api/v1/purchases",
    "rid-POST/api/v1/purchases/**",
    "rid-PUT/api/v1/purchases",
    "rid-PUT/api/v1/purchases/**",
    "rid-GET/api/v1/purchases",
    "rid-GET/api/v1/purchases/**",
    "rid-DELETE/api/v1/purchases",
    "rid-DELETE/api/v1/purchases/**",
    "rid-POST/api/v2/purchases",
    "rid-POST/api/v2/purchases/**",
    "rid-PUT/api/v2/purchases",
    "rid-PUT/api/v2/purchases/**",
    "rid-GET/api/v2/purchases",
    "rid-GET/api/v2/purchases/**",
    "rid-DELETE/api/v2/purchases",
    "rid-DELETE/api/v2/purchases/**",
    "rid-POST/api/v3/purchases",
    "rid-POST/api/v3/purchases/**",
    "rid-PUT/api/v3/purchases",
    "rid-PUT/api/v3/purchases/**",
    "rid-GET/api/v3/purchases",
    "rid-GET/api/v3/purchases/**",
    "rid-DELETE/api/v3/purchases",
    "rid-DELETE/api/v3/purchases/**"
  ],
  "incognito_requestor_id": "12380859503",
  "client_name": "R7jJhrEgyL",
  "client_logo": null,
  "payable_id": "33597",
  "client_description": null,
  "jti": "239def43-0fe7-4e3e-a36f-85828fcd5de0"
}

2: Make a purchase request

Once you have an access token, make a POST request to the following endpoint:

<https://qa.interswitchng.com/api/v3/purchases>

In the Authorization header, set the value to Bearer <access_token>, where <access_token> is the access token you generated in step 1.

In the request body, include the following parameters:

  • customerId: The ID of the customer making the purchase.
  • amount: The purchase amount in Nigerian naira (NGN).
  • currency: The currency of the purchase which must be NGN.
  • authData: The encrypted card details of the customer's card. You can generate one from here
  • transactionRef: A unique reference for the transaction.
    If the purchase is successful, you will receive a JSON response containing the transaction details.

Respones:

{
  "transactionRef": "fhfgrgte",
  "paymentId": "474552283",
  "message": "Kindly enter the OTP sent to 234805***1111",
  "amount": "10000.00",
  "responseCode": "T0",
  "plainTextSupportMessage": "Didn't get the OTP? Dial *723*0# on your phone (MTN,Etisalat,Airtel) Glo,use *805*0#."
}

For more information, see the Interswitch Purchase API documentation

3: Handle authentication requirements

📘

T0 indicates Verve/Mastercard, and the response S0 is gotten when it is a cardinal transaction. This occurs when using visa cards. Click here to read more about visa transactions.

Depending on the configuration tied to the card and your business profile, the purchase request may result in two scenarios:

a. Immediate Authorization:
If the card is configured for immediate authorization, you will receive a response indicating whether the transaction was successful or failed. You can then proceed to check the transaction status.

b. Authentication Required:
If authentication is needed, you will receive a response code indicating whether an OTP has been sent to the customer's phone (T0) or 3D Secure authentication is required (S0).

If the response code is T0, the customer must provide the OTP to complete the transaction. You can then call the Interswitch Authenticate OTP API to authenticate the OTP by making POST request to the following endpoint:

https://qa.interswitchng.com/api/v3/purchases/otps/auths

In the request body, include the following parameters:

  • paymentId: This typically represents a unique identifier associated with a payment or transaction.
  • otp: This stands for One-Time Password. It is a temporary, unique code used for authentication or verification purposes.
  • transactionId: This is a unique identifier assigned to a specific transaction. It serves as a reference code for that transaction and is used to retrieve and track transaction details.
  • eciFlag: The Electronic Commerce Indicator (ECI) Flag e.g Visa:07 (Optional)

Response:

{
  "transactionRef": "fhfgrgte",
  "message": "Approved by Financial Institution",
  "transactionIdentifier": "FBN|API|MX6072|10-10-2023|474552283|723413",
  "amount": "10000.00",
  "responseCode": "00",
  "retrievalReferenceNumber": "000106923853",
  "stan": "000008",
  "terminalId": "3PXM0001",
  "bankCode": "011"
}

If the response code is S0, the customer must complete 3D Secure authentication. Once the authentication is complete, you can call the Interswitch Authorize Transaction (3D Secure) API to authorize the transaction.

For more information, see the Interswitch Authenticate OTP API documentation

4: Confirm the status of the transaction

Once you have made the purchase request and handled any authentication requirements, you should confirm the transaction status.

You can make a GET request to the following endpoint:

https://qa.interswitchng.com/collections/api/v1/gettransaction

In the Authorization header, set the value to Bearer <access_token>, where <access_token> is the access token you generated in step 1.

In the request query path, include the following parameters:

  • merchantcode: The unique code identifying the merchant associated with the transaction.
  • transactionreference: The reference code that uniquely identifies the transaction you want to retrieve.
  • amount: The transaction amount for additional verification.

If the transaction is successful, you will receive a JSON response containing the transaction details.

Response:

{
    "Amount": 9108,
    "CardNumber": "506099*********7499",
    "MerchantReference": "202311301354481LIFJ",
    "PaymentReference": "FBN|API|MX6072|30-11-2023|474568251|335432",
    "RetrievalReferenceNumber": "000106923853",
    "Stan": "000008",
    "Channel": "API",
    "TerminalId": "3PXM0001",
    "SplitAccounts": [],
    "TransactionDate": "2023-11-30T01:55:09",
    "ResponseCode": "00",
    "ResponseDescription": "Approved by Financial Institution",
    "BankCode": "011",
    "PaymentId": 474568251,
    "RemittanceAmount": 0
}

For more information, see the Interswitch Transaction Status API documentation

📘

Resend OTP

Sometimes, you might need to resend the OTP, make call to Resend OTP

Updated 5 months ago