Introduction

Finding ways to motivate your current customers to buy more and your new customers to come back is smart business. That’s where the Interswitch’s Loyalty API comes in. Loyalty/Rewards studies show that customers who belong to a loyalty program visit businesses twice as often and spend four times as much as those that don’t.

Sample Requests

The Loyalty APIs are HTTP based RESTful APIs therefore API request and response format are in JSON. We have provided sample request and responses next to each endpoint in this documentation. All you need to do is replace the dummy parameters with yours.


BASE URL

https://sandbox.interswitchng.com

Response Code

We use the standard HTTP response codes. Where anything starting with 2XX signifies approved, 4XX means client error and 5XX indicates server error. When the response codes start with 4XX or 5XX, an error object will be returned to explain further the reason for this failure.


Authentication

Authenticate your API calls by including your access token in the Authorization header of every request you make. Interswitch utilizes OAuth 2 to facilitate authorization and grants access to an application either on behalf of a user or on behalf of the application itself.

Application Authorization

To get an access token, create a project on the Interswitch Developer Console and obtain the Client ID and Secret Key of the project and encode the them using this format client_id:secret_key using base64encode. Copy the encoded value of your Client ID and Secret Key and make a call to the endpoint below with the Authorization header that contains the word Basic followed by a space and the base64-encoded value. Ensure that you use the Content-Type:application/x-www-form-urlencoded header and finally pass the grant_type=client_credentials in the body of the request.


Endpoint

POST

/passport/oauth/token

Sample Request

import requests
url = "https://sandbox.interswitchng.com/passport/oauth/token"
body = {"grant_type":"client_credentials"}
headers = {
    'authorization': "Basic SUtJQTFCNzU5M0M0NDAyQkM1RTAwQzQ2QUM4QjFDMUNDMEI4NUVFQkIwODg6c2VjcmV0",
    'content-type': "application/x-www-form-urlencoded"}
response = requests.request("POST", url, data=body, headers=headers)
print(response.text)
REQUEST PARAMETERS
Parameters Required Type Description
ClientId Yes String Application key. Navigate to `https://developer.interswitchgroup.com` for your application key
SecretKey Yes String Application secret. Navigate to `https://developer.interswitchgroup.com` for your application secret.
grant_type Yes String This must be set to client_credentials

Sample Response (Success)

{ 
  "access_token": "{Your access token}",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "profile",
  "merchant_code": "MX10003",
  "requestor_id": "123588975884",
  "client_name": "kL79ov",
  "payable_id": "359854",
  "jti": "19800d56-3ac6-44c2-b318-8f2ece419840"
}

Sample Response (Failure)

{ 
  "code": "Unauthorized",
  "description": "Bad credentials",
  "errors": null
}
RESPONSE PARAMETERS
Parameters Description
access_token A new access token that is used to authenticate against resources that belong to the app itself.
token_type Always bearer
expires_in The lifetime of the access token, in seconds

Authorization headers should be in the following format: Authorization: Bearer Encoded(clientId:secreteKey).


Getting Rewards Balance

This allows users to retrieve their reward points. Getting rewards balance involves the client application sending the user id (or card number) and information about the connecting device as arguments and getting the reward balances in return.

Endpoint

GET

/api/v1/loyalty/rewards

Sample Request

/api/v1/loyalty/rewards?timeStamp=20140602122810&transactionId=0133
REQUEST PARAMETERS
Data Element (DE) Data Type Description
merchantId String The merchant identifier(Sent as a header parameter
terminalId String The device (terminal) identifier Sent as a header parameter
PAN String The device (terminal) identifier Sent as a header parameter
expiryDate String Card expiry date (format yymm)Sent as a header parameter.
timeStamp String Local timestamp of the transaction.Format["YYYYMMDDhhmmss"]
transactionId String
RESPONSE MESSAGE
Data Element (DE) Data Type Description
rewardTrxId String The transaction ID
accounts Array An array of reward account balances.

Sample Response (Success)

{
    "rewardTrxId": "2263234",
    "accounts": [{
    "accountId": "12",
    "accountName": "",
    "accountType": "1",
    "availableBalance": "2450"
}]}
ACCOUNT OBJECT
Data Element (DE) Data Type Description
accountId String The account ID identifies the campaign under which the reward value falls e.g  "12"
accountName String The campaign  name e.g  "Reward Money".
accountType String The account type determines if the reward is monetary or non-monetary.
availableBalance String The available reward balance on the given campaign.

Earn Rewards

This method allows a user to earn rewards (points or money).  Drive customer loyalty by rewarding customers who transact on your POS terminals and ATMs. Customers can earn rewards when they use their cards on your terminals. Earning rewards involves the client application registering the transaction to be awarded, and information about the card and connecting device as arguments, getting the reward balances in return.

Endpoint

POST

/api/v1/loyalty/rewards/earn

Sample Request

{
    "expiryDate": "1612",
    "merchantId": "IBP000000000162",
    "terminalId": "20690111",
    "timeStamp": "20140600122810",
    "transactionId": "2093",
    "amount": "10"
}
REQUEST PARAMETER
Data Element (DE) Data Type Description
merchantId String The merchant identifier Sent as a header parameter.
terminalId String The device (terminal) identifier Sent as a header parameter.
PAN String The card PAN (Primary Account Number) Sent as a header parameter.
expiryDate String Card expiry date (format yymm).
timeStamp String Local timestamp of the transaction.Format["YYYYMMDDhhmmss"]
transactionId String A unique transaction ID.

The merchantId and terminalId are specifically combined. There maybe one or more terminalIds tied to a merchantId. The pan may be a card pan, an email address, a mobile number or a referral service identifier. There are constraints for each possibility:

  1. The presence of an expiryDate depicts the pan as a card pan.
  2. If a pan is an email address then it must follow the pattern of a valid email address.
  3. If a pan is a mobile number then it must follow the pattern of a valid mobile number
  4. If a pan is a referral service identifier them it must follow the pattern of a valid referral service identifier.
RESPONSE MESSAGE PARAMETER
Data Element (DE) Data Type Description
rewardTrxId String The transaction ID.
accounts Array An array of reward account balances

Sample Response (Success)

{
    "rewardTrxId": "2268927",
    "accounts": [{
    "accountId": "12",
    "accountName": "",
    "accountType": "1",
    "availableBalance": "3650"}] 
}

Sample Response (Failure)

ACCOUNT OBJECT
Data Element (DE) Data Type Description
accountId String The account ID.
accountName String The account name.
accountType String The account type.
availableBalance String The available reward balance.
{
  "errors": [{
  "code": "10002",
  "message": "null"}],
  "error": {
  "code": "10002",
  "message": "null"
}}

Burn Rewards

Loyal customers who have earned rewards can burn it and redeem items or get cash discounts in exchange. A request to get rewards balance must be made first, followed by the burn request. A list of or a single redemption mandates must be sent in the burn request body, and the initial transaction ID returned in the initial balance request.

Endpoint

POST

/api/v1/loyalty/rewards/redeem

Sample Request

{
    "redemptionMandates": [{   
    "accountId": "12",
    "accountType": "1",
    "debit": "100"}],
    "rewardTxnId": "2268927"
}
REQUEST PARAMETER
Data Element (DE) Data Type Description
rewardTrxId String The transaction ID generated by the client.
redemptionMandates Array An array of redemption mandate requests.
accountId String The account ID.
accountType String The account type.
debit String The amount to be debited from the user account.

Sample Response

{
    rewardTrxId: "2263176",     
    accounts: [{
    accountId: "12"           
    accountType: "1"           
    debit: "100"
    balance: "2300"}] 
}
RESPONSE PARAMETER DESCRIPTION
Data Element (DE) Data Type Description
rewardTrxId String The transaction ID received from point balance call.
accountName String The account name.
accountId String The account ID used to Identify the campaign pool.
debit String The point to be debited.
accountType String The account type. This is used to identify the type of account. Usually set to 1 for pool types
balance String The available reward balance.

Create Account

This call is used to create account for customer on Interswitch Loyalty platform.

Endpoint

POST

/api/v1/loyalty/accounts

Sample Request

{
    "accountId":"08030000066"
}
REQUEST PARAMETER
Data Element (DE) Data Type Description
accountId String This is the account Id for the customer. The accountId should not contain space.

Sample Response (Successful)

Http Status Code: 201

Sample Response (Duplicate)

{
    "errors": [
    {"code": "2020",
    "message": "Duplicate Account Not Allowed"}],
    "error": {
    "code": "2020",
    "message": "Duplicate Account Not Allowed"
}}

Sample Response (Invalid)

{
    "errors": [{"code": "1013",
    "message": "Account Creation  Error [UMI Format]"}],
    "error": {
    "code": "1013",
    "message": "Account Creation  Error [UMI Format]"
}}

Create Product

This call is used to create product for customer on Interswitch Loyalty platform.

Endpoint

POST

/api/v1/loyalty/products

Sample Request

{
    "productId":"08030000066",
    "productType": "ABC"
}
REQUEST PARAMETER
Data Element (DE) Data Type Description
productId String Unique identifier for customer.
productType String Product type

Sample Response (successful)

Http Status Code: 201
Content-Type: application/json

Sample Response (Duplicate)

{
    "errors": [{
    "code": "2020",
    "message": "Duplicate Account Not Allowed"}],
    "error": {
    "code": "2020",
    "message": "Duplicate Account Not Allowed"
}}

Sample Response (Invalid)

{
    "errors": [{"code": "1013",
    "message": "Account Creation  Error [UMI Format]"}],
    "error": {
    "code": "1013",
    "message": "Account Creation  Error [UMI Format]"
}}

Associate Product to Loyalty Account

This is a method call to link an existing Loyalty Account with an existing/new Product on Interswitch Loyalty platform. If the product does not exist prior to the call, the call will create a product and then link it to the specified account.

Endpoint

POST

/api/v1/loyalty/accounts/{accountId}/products

Sample Request

{
    "productId":"08030000066",
    "productType": "ABC"
}
REQUEST PARAMETER
Data Element (DE) Data Type Description
productId String Product Id
productType String Product type

Sample Response (successful)

Http Status Code: 201

Sample Response (Duplicate)

{
    "errors": [{
    "code": "2020",
    "message": "Duplicate Account Not Allowed"}],
    "error": {
    "code": "2020",
    "message": "Duplicate Account Not Allowed"
}}

Sample Response (Invalid)

{
    "errors": [{
    "code": "1013",
    "message": "Account Creation  Error [UMI Format]"}],
    "error": {
    "code": "1013",
    "message": "Account Creation  Error [UMI Format]"
}}

Transaction History

Allows user retrieve transactions history on Interswitch Loyalty platform.

Endpoint

GET

/api/v1/loyalty/transactions

Sample Request

productType=MOBIASHARA_ACCT&productid=3061XXXXXXXXXX73674&expiryDate=1612&start
Date=20151210&endDate=20151214
REQUEST PARAMETER
Data Element (DE) Data Type Description
producttype String Product Type
productID String Product Identifier
pan String This is a unique identifier the card PAN (Primary Account Number) with loyalty points
expiryDate String This is the card expiry date. Format: yymm
startDate String This is the start date of the transaction date range. Format: YYYYMMDD
endDate String This is the end date of the transaction date range. Format: YYYYMMDD

Sample Response

{
    "transactions": [{
    "id": 278345764,
    "linkId": 239687162,
    "date": "14-12-2015 23:15:00",
    "name": "SlTrader NEW Joiner STD",
    "transactionValue": "0.01",
    "transactionRewardValue": 100,
    "transactionRewardPool": "MoRewardz",
    "totalRewardValue": 100,
    "merchant": null,
    "deviceId": "-",
    "extRef": "M7367",
    "product": {
    "productId": "3061XXXXXXXXXX73674",
    "productType": "MOBIASHARA_ACCT",
    "productStatus": null,
    "pan": null,
    "expiryDate": null}}],
    "totalRecords": "5",
    "totalPages": "1"
]

Response Codes

Sample response Codes obtainable are below. Note that this list is not exhaustive.

Response Code Description
200 OK
400 BAD REQUEST
401 UNAUTHORIZED
403 FORBIDDEN
404 NOT FOUND
406 NOT ACCEPTABLE
500 INTERNAL ERROR
501 NOT IMPLEMENTED
E10 The service field tag has not been populated.  Please ask Interswitch Support for more help.
E11 This requests expects a transactionType field to be set and it is not.  Please ask Interswitch Support for more help.
E12 SecurityToken header is missing
E13 Username or password is wrong.
E14 Missing content type header.
E15 The transaction you are trying to do is not supported.
E16 The service you have specified is not available.
E17 The service provider you have specified has not been set up on the platform.
E18 The service is unreachable at the moment.
E19 A bad response was received from service provider.
E20 Your request has timed out.
E21 An unknown error has occurred. Please ask Interswitch Support for more help.
E22 Access key has not been supplied. Ensure the Authorization header has been set appropriately
E23 Nonce has not been supplied. Ensure the Nonce header has been set appropriately.
E24 Please synchronize your time with the server and ensure your time is not outside of 30mins of the Server local time. The standard time zone used is GMT
E25 Nonce has already been used
E26 Signature failed for this request.  Please ask Interswitch Support for more help.
E27 An unknown error occured during Authentication.  Please ask Interswitch Support for more help.
E28 Your credentials do not have access to this resource
E29 Timestamp is missing in your header.
E30 SecurityToken header is bad.
E31 XML data is badly formatted
E32 JSON data is badly formatted
E33 Keystore is not accessible. Contact Interswitch.
E34 The system is busy at the moment, please try again later.
E35 Bad request to service provider. Contact Interswitch.
E36 Bad request to service processor. Contact Interswitch.
E37 Bad request from client. Kindly check your message.
E38 Bad response from service provider. Contact Interswitch.
E39 Bad response from service processor. Contact Interswitch.
E40 Bad response to client. Contact Interswitch.
E41 Bad request from client. Kindly check your message.