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.

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.

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

{ 
  "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"
}

{ 
  "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.

/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.

{
    "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.

{
    "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

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

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.

{
    "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.

{
    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.

{
    "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.

Http Status Code: 201

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

{
    "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.

{
    "productId":"08030000066",
    "productType": "ABC"
}

REQUEST PARAMETER
Data Element (DE)	Data Type	Description
productId	String	Unique identifier for customer.
productType	String	Product type

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

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

{
    "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.

{
    "productId":"08030000066",
    "productType": "ABC"
}

REQUEST PARAMETER
Data Element (DE)	Data Type	Description
productId	String	Product Id
productType	String	Product type

Http Status Code: 201

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

{
    "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.

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

{
    "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.