API ReferenceDeveloper ConsoleDeveloper Community

Authentication

Suggest Edits

We have two ways by which we secure our APIs at Interswitch:

  1. OAuth 2.0: Here, you will be making a call to our system in order to get an access token which must be attached to the header of your request. This will authenticate that you are permitted to use the service. More details can be found below.

  2. Interswitch Auth: This is for our existing legacy application users where you need to generate certain parameters such as nonce, signature, timestamp and signature method. All these parameters are to be attached to the header of every request. It is explained in detail below.

OAuth 2.0

Our Services are protected by systems that require you having an access token that has been granted by our authentication service. You can only access services which have been granted you or your client using the access token.

How do I get my Access Token ?

The steps are:

STEP 1: Make an API call to get your Access Token

Below is how to make an API call to get your access token

curl https://sandbox.interswitchng.com/passport/oauth/token \
-H "Authorization: Basic Base64(CLIENT_ID:SECRET_KEY)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-D '{
	"grant_type": "client_credentials"
}'
-X POST

📘

NOTE

Your CLIENT_ID and SECRET_KEY can be gotten from your Quickteller Business Dashboard. You can also get them on your developer console profile, or it would be shared to you by your integration partner.

Your response should appear in the format below:

{
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOlsiY2Flc2FyIiwiY2FyZGxlc3Mtc2VydmljZSIsImNyZWRpdC1zY29yZS1zZXJ2aWNlIiwiZGlyZWN0LXRvLWFjY291bnQiLCJpbmNvZ25pdG8iLCJpc3ctY29sbGVjdGlvbnMiLCJpc3ctY29yZSIsImlzdy1sZW5kaW5nLXNlcnZpY2UiLCJpc3ctcGF5bWVudGdhdGV3YXkiLCJwYXNzcG9ydCIsInBheW1lbnQtc2VydmljZSIsInBheW1lbnRzZXJ2aWNlIiwicHJvamVjdC14LWNvbnN1bWVyIiwicHJvamVjdC14LW1lcmNoYW50IiwicHdtIiwidmF1bHQiLCJ2b3VjaGVyLWFwaSIsIndhbGxldCJdLCJtZXJjaGFudF9jb2RlIjoiTVgxODciLCJwcm9kdWN0aW9uX3BheW1lbnRfY29kZSI6IjAwMTY0NjM5ODU0IiwicmVxdWVzdG9yX2lkIjoiMDAxMTc2MTQ5OTIiLCJzY29wZSI6WyJwcm9maWxlIl0sImV4cCI6MTYyNzYzOTU4NywianRpIjoiYTUzNTI0NjUtMzc1Yy00YmRiLWIwZmYtMDI1NDE1NjM5YmVjIiwicGF5YWJsZV9pZCI6IjIzMjQiLCJjbGllbnRfaWQiOiJJS0lBOTYxNEI4MjA2NEQ2MzJFOUI2NDE4REYzNThBNkE0QUVBODRENzIxOCIsInBheW1lbnRfY29kZSI6IjA0MjU5NDEzMDI0NiJ9.AqYq_5BMyVN49QWEqmoc6ZN7YXAdxK3WP4cijKLlTPcEmvzeDYUhZOu2J3-eMxEr1-46OGiMbCGQ2ezyz0oAfjeURpQ42-6P6eNXdXJrhYPGoALGsoz1Gwa66s6i8Lwq81n9PEkdQN8b6B0Gm-vQqWNl7OEWM2rZ8EotjlwbQn2vbMVlQPKvIXw--38IF-fdhq0VUbP6MKm9YVWxvcyEqhU6nAZnoEtG73U1aZSSA0bfjmAs0xmUCScURg9ufGCVn47J82UEkErUBJJTJg1SQ4bZkkWKJIDrd7S0-bUA_42cWb7y7PtwJYM4FJv94Ew_0ky9kv5dpv19ecgEfHvKCQ",
    "token_type": "bearer",
    "expires_in": 86400,
    "scope": "profile",
    "merchant_code": "MX18227",
    "production_payment_code": "00164639854",
    "requestor_id": "0055614992",
    "payable_id": "2324",
    "jti": "a5352465-375c-4bdb-b0ff-025415639bec"
}

📘

The Access token expires in the time returned by the expires_in value in the response. This value is in seconds. You can reuse the same access token for your calls till it expires.

STEP 2: Make an API call to any of our endpoints.

Say you want to make a call to the Card Payment API, you can use the generated access token as shown below:

curl https://api.interswitchng.com/api/v3/purchases\
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.ey.my47J82UEkErUBJJTJg1SQ4bZkkWKJIDrd7S0-bUA_42cWb7y7PtwJYM4FJv94Ew_0ky9kv5dpv19ecgEfHvKCQ" \
-H "Content-Type: application/json" \
-d '{
    "customerId": "1407002510",
    "amount": "20000",
    "transactionRef": "12n345mmm0km655",
    "currency": "NGN",
    "authData": "abcde=="
}' 
-X POST

Interswitch Auth (Legacy Systems)

Authentication

To use the endpoints for this service, you need to send the following HTTP header parameters with every request.

S/NHeader ParameterDescription
1.TimestampRequest timestamp in unix. It must be in seconds
2.NonceA uniquely generated value for each request. It must not be repeated and the length must NOT be more than 64 characters
3.AuthorizationThe describes the realm and identity of the user requesting access to the resource.
4.SignatureThis must be represented in base 64. The signature is calculated from a combination of defined data elements separated by '&'.
5.SignatureMethodThis refers to the cryptographic hash function used to calculate the signature e.g SHA1
6.Content-TypeThis is the MIME type of the body of the request e.g application/json.

Authorization Computation

All messages must be authorized using the standard 'Basic' authorization model of the web. The HTTP header authorization should be set to the base 64 encoded value of your client ID which can be gotten from your dashboard.

'InterswitchAuth ' . base64_encode(CLIENT_ID);

Signature Computation

The signature method should be SHA1 calculated against the data elements in the table above arranged in the order shown below:

$signature = 'GET' . '&' . urlencode($endpoint) . '&' . time()
    					. '&' . $nonce . '&' . <CLIENT_ID> . '&' . <SECRET_KEY>;
$hashedSignature = base64_encode(sha1($signature, true));

NOTE: CLIENT_ID and SECRET_KEY can be gotten from your dashboard.
Remember nonce is a uniquely generated value for each request which must have been generated earlier.

Sample Authentication Headers

Below is a sample authentication header

{
  "Authorization": "InterswitchAuth SUtJQUVFMzhDMjRBMzYzRTRGQzAxREVCRkJGRTlGOERDMUY0QkNCMkJDNDg=",
  "Content-Type": "application/json",
  "Nonce": "091f90dbbf9748f0b2854a038dbdac44",
  "SignatureMethod": "SHA1",
  "Signature": "mf73jzzhaVN8U0oZ7iiKcVgEzBY=",
  "Timestamp": "1440071245" 
}

Updated 5 months ago