HTTP INTERFACE TO INTOUCHPAY PAYMENTS GATEWAY

1. API FUNCTIONS

The IntouchPay payments gateway provides application programming interfaces (APIs) for third-party
applications (App for short) to connect to it and use its payments processing capability to send and
receive payments. The App is generally developed by various partners of theIntouchpay gateway.

Table 1 describes functions of the gateway APIs provided by the IntouchPay.

Table 1 Functions of gateway capability APIs

FUNCTION DESCRIPTION API

The App (functioning as the client) invokes the RequestPayment

Receiving Payment API to initiate a payment request to a subscriber on Intouchpay • RequestPayment
(functioning as the server).

The intouchpay gateway will then respond with a pending status

to the App awaiting for subscriber confirmation of the transaction.

After confirmation the Intouchpay gateway will invoke the App on

the App transaction status url with the status of the transaction.

Sending Payment The App (functioning as the client) invokes the RequestDeposit • RequestDeposit
API to initiate a deposit request to a subscriber on Intouchpay
(functioning as the server).

The intouchpay gateway will then process the transaction and

respond with a transaction status response.

1.1. Level of Requirement for Parameters

The App developer must develop APIs based on the level of requirement for each parameter.

Type Description
Mandatory A parameter is always mandatory in a request.
Parameters with the Mandatory requirement are used for access authentication or
service processing. If a parameter with the Mandatory requirement is left empty in a
request, access authentication or service processing fails and the request fails.
Conditional A parameter is mandatory or optional in specified conditions.
Parameters with the Conditional requirement are used for access authentication or
service processing in specified conditions. If the specified conditions is met but a
parameter with the Conditional requirement is left empty in a request, access
authentication or service processing fails and the request fails.
Optional A parameter is always optional.
Parameters with the Optional requirement are not used for service processing.

1.2. Request Format

Parameters are submitted to the intouchpayurlas http-form post.

1.3. Response Format

The Intouchpay gateway will provide a response in the json format.

2. RECEIVING PAYMENT REQUEST

2.1. Function

The App (functioning as the client) invokes the RequestPayment API to initiate a payment request to a
subscriber on Intouchpay (functioning as the server).

The intouchpay gateway will then respond with a pending status to the App awaiting for subscriber
confirmation of the transaction. After confirmation the Intouchpay gateway will invoke the App on the App
transaction status url with the status of the transaction.

Partners must code the App based on the API field requirements so that the App can send correct
requests to IntouchPay. Intouchpay sends a response within 60 seconds by default.

THIRD PARTY INTOUCHPAY MOBILE MONEY USSD MOBILE MONEY

PROVIDER SUBSCRIBER

Request Payment

Request Payment

SMS to Inform on a pending Debit Request/USSD Push

Request Payment Response (Pending)

Dial *182#
Request Payment Response (Pending) Select Pending approvals
Select transaction
Enter PIN

Payment Approval USSD Req

Payment Approval USSD Req

Payment Completed Request

Payment Completed Request

Payment Completed Response

Payment Completed Response

3
 2.2. Request URI

The request URI is the destination URI of the requestpaymentrequest sent by the App to the
IntouchPay to enable a payment request to be sent to the subscriber. The URI is provided by
Intouchpay in the following format:

http://IP:Port/api/requestpayment/

In the format, IP and Port indicate the service IP address and port number of the API provided by
the Intouchpay. Contact carriers to obtain the IP address and port number.

2.3. Request

The App functions as the client and sends a requestpaymentmessage to intouchpayto enable a
payment request to be sent to the subscriber.

Example in Python Programming language

data={
'username':'bob',
'timestamp':'20161231115242',
'amount':100,
'password': 'd3cfd05492a2376003f5af9e2e6643b67',
'mobilephone': 250785971082,
’requesttransactionid’:34555
}

response=requests.post('https://www.intouchpay.co.rw/api/requestpayment/', data=data)

2.4. Password Generation

The request password is generated as per the steps below.

1. Username+accountno+partnerpassword+timestamp
2. Encrypt the resulting string using SHA256 encryption
3. Get the hexdigest of the resulting encryption

Example in Python

password = hashlib.sha256(username+accountno+partnerpassword+timestamp).hexdigest()

2.5. Request Parameters

Parameter Name Data Format Description Mandatory

username string User name assigned to your account Yes
timestamp string Timestamp of the transaction preferably in Yes
UTC formatted as yyyymmddhhmmss
amount string/Float/Integer Amount to be paid Yes
mobilephoneno String Mobile phone number making the payment Yes
requesttransactionid string Unique request transaction id of the Yes
transaction from the App
accountno string Account number of your account Yes
partnerpassword string The partner password of your account Yes

4
2.6. RECEIVING PAYMENT RESPONSE

The intouchpay gateway will respond with a json response as below and an HTTP response 200 OK.

{
'status': 'Pending',
'requesttransactionid': '4522233',
'success': True,
'responsecode': '1000',
'transactionid': 1425,
'message': 'Transaction Pending'
}

2.7. RECEIVING PAYMENT REQUEST COMPLETION

The intouchpaygateway acts as a client and Invokes the App by sending it the status of the
pending transaction via an HTTP post. Which can either be successfull or failed. Partners are
required to provide an end point url to which the intouchpay gateway will submit the request.

Below is an example in Python programming language

data = {
'requesttransactionid':''4522233',
'transactionid':'6004994884',
'responsecode' :'01',
'status':'Successfull',
'statusdesc':'Successfully Processed Transaction',
'referenceno':'312333883'
}

r = requests.post(url, json={'jsonpayload':data},headers={'content-
type':"application/json"},verify=False)

or

r = requests.post(url,json={'jsonpayload':data},auth=(username, password),headers={'content-
type':"application/json"},verify=False)

5
2.8. COMPLETE RECEIVING PAYMENT REQUEST COMPLETION RESPONSE

The App will respond with an HTTP 200 OK response and the following parameters in json format

'message': 'success',
'success': True
,'request_id': '4522233'
}

2.9. Response Codes

Below is a table showing the response codes for the Receiving Payment response

RESPONSE CODE DESCRIPTION

1000 Pending
01 Successfull
0002 Missing Username Information
0003 Missing Password Information
0004 Missing Date Information
0005 Invalid Password
0006 User Does not have an intouchPay Account
0007 No such user
0008 Failed to Authenticate
2100 Amount should be greater than 0
2200 Amount below minimum
2300 Amount above maximum
2400 Duplicate Transaciton ID
2500 Route Not Found
2600 Operation Not Allowed
2700 Failed to Complete Transaction
527 Failed Due to Insufficient Funds
515 Mobile number not registered on mobile money.
682 Insufficient balance or Number not registered on mobile money
100 General Failure
1200 Invalid Number
1100 Number not supported on this Mobile money network

6
3. SENDING PAYMENT REQUEST

3.1. Function

The App (functioning as the client) invokes the RequestDeposit API to initiate a deposit request to a
subscriber on Intouchpay (functioning as the server).

The intouchpay gateway will then attempt to perform the deposit transaction as per request, and will invoke
the App with the response of the deposit request status.

Partners must code the App based on the API field requirements so that the App can send correct
requests to IntouchPay. Intouchpay sends a response within 60 seconds by default.

THIRD PARTY INTOUCHPAY MOBILE MONEY MOBILE MONEY

PROVIDER SUBSCRIBER

Request Deposit

Request Deposit

SMS to Inform on receipt of funds

Request Deposit Response (Pending)

Request Deposit Response

3.2. Request URI

The request URI is the destination URI of the requestdeposit request sent by the App to the
IntouchPay to enable a deposit transaction to be made to the subscriber. The URI is provided by
Intouchpay in the following format:

http://IP:Port/api/requestdeposit/

In the format, IP and Port indicate the service IP address and port number of the API provided by
the Intouchpay. Contact carriers to obtain the IP address and port number.

3.3. Request

The App functions as the client and sends a requestdepositmessage to intouchpay to enable a
deposit request to be sent to the subscriber.

Example in Python Programming language

data={
'username':'bob',
'timestamp':'20161231115242',
'amount':100,
"withdrawcharge": 1,

"reason": "xxxxxxxxxx ",

 "sid": "1",

'password': 'd3cfd05492a2376003f5af9e2e6643b67',
'mobilephone': 250785971082,
’requesttransactionid’:34555,
}

response=requests.post('https://www.intouchpay.co.rw/api/requestdeposit/', data=data)

3.4. Password Generation

The request password is generated as per the steps below.

4. Username+accountno+partnerpassword+timestamp
5. Encrypt the resulting string using SHA256 encryption
6. Get the hexdigest of the resulting encryption

Example in Python

password = hashlib.sha256(username+accountno+partnerpassword+timestamp).hexdigest()

3.5. Request Parameters

Parameter Name Data Format Description Mandatory

username string User name assigned to your account Yes
timestamp string Timestamp of the transaction preferably in Yes
UTC formatted as yyyymmddhhmmss
amount string/Float/Integer Amount to be paid Yes
withdrawcharge integer Set to 1 to include Withdraw Charges in
amount sent to subscriber
reason string Reason for Sending Payment
sid integer Service ID. Set to 1 For Bulk Payments
mobilephoneno String Mobile phone number making the payment Yes
requesttransactionid string Unique request transaction id of the Yes
transaction from the App
accountno string Account number of your account Yes
partnerpassword string The partner password of your account Yes

3.6. MAKING PAYMENT RESPONSE

The intouchpay gateway will respond with a json response as below and an HTTP response 200 OK.

Success response:

"requesttransactionid":"1201",

"referenceid":"1123",

"responsecode":"2001",

"success": true
8
 }

Failure response:

"requesttransactionid":"1201",

"success":false,

"responsecode":"xxxx"

*Note: referenceid is only returned as part of response if the requestdeposit request was successful

3.7. Response Codes

Below is a table showing the response codes for the Receiving Payment response

RESPONSE CODE DESCRIPTION

0002 Missing Username Information
0003 Missing Password Information
0004 Missing Date Information
0005 Invalid Password
0006 User Does not have an intouchPay Account
0007 No such user
0008 Failed to Authenticate
0002 Missing Username Information
0003 Missing Password Information

1100 Error in Request

1101 Service ID not Recognized
1102 Invalid Mobile Phone Number
1103 Payment Above Allowed Maximum
1104 Payment Below Allowed Minimum
1105 Network Not Supported
1106 Operation Not Permitted
1107 Payment Account Not Configured
1108 Insufficient Account Balance
1110 Duplicate Remit ID

2001 Request Successful

2003 Transaction Not Allowed
2102 Subscriber Could not be Identified
2105 Non Existent Mobile Account
2106 Own Mobile Account Provided
2107 Invalid Amount Format

9
2108 Insufficient Funds on Source Account
2109 Daily Limit Exceeded
2110 Source Account Not Active
2111 Mobile Account Not Active
2100 General Failure

2500 Service Failure

2510 Service Temporarily Unavailable
2518 Could Not Perform Operation
2520 Incorrect Account Password
2522 Invalid Amount
2525 Resource Not Active
2600 Network Failure - Request Timed Out

10
4. BALANCE INQUIRY

4.1. Function

The App (functioning as the client) invokes the GetBalance API to query account balance on Intouchpay
(functioning as the server).

The intouchpay gateway will then attempt to query the account balance as per request, and will invoke the
App with the response of the getbalance request status.

Partners must code the App based on the API field requirements so that the App can send correct
requests to IntouchPay. Intouchpay sends a response within 60 seconds by default.

4.2. Request URI

The request URI is the destination URI of the getbalance request sent by the App to the
IntouchPay to enable a deposit transaction to be made to the subscriber. The URI is provided by
Intouchpay in the following format:

http://IP:Port/api/getbalance/

In the format, IP and Port indicate the service IP address and port number of the API provided by
the Intouchpay. Contact carriers to obtain the IP address and port number.

4.3. Request

The App functions as the client and sends a getbalancemessage to intouchpay to enable a
deposit request to be sent to the subscriber.

Example in Python Programming language

data={
'username':'bob',
'timestamp':'20161231115242',
'password': 'd3cfd05492a2376003f5af9e2e6643b67',
}

response=requests.post('https://www.intouchpay.co.rw/api/getbalance /', data=data)

4.4. Password Generation

The request password is generated as per the steps below.

7. Username+accountno+partnerpassword+timestamp
8. Encrypt the resulting string using SHA256 encryption
9. Get the hexdigest of the resulting encryption

Example in Python

password = hashlib.sha256(username+accountno+partnerpassword+timestamp).hexdigest()
 4.5. Request Parameters

Parameter Name Data Format Description Mandatory

username string User name assigned to your account Yes
timestamp string Timestamp of the transaction preferably in Yes
UTC formatted as yyyymmddss
accountno string Account number of your account Yes
partnerpassword string The partner password of your account Yes

4.6. MAKING PAYMENT RESPONSE

The intouchpay gateway will respond with a json response as below and an HTTP response 200 OK.

Success response:

"balance":"0.0"

"success": true

Failure response:

"success":false,

"responsecode":"007",

“message”: “No such user”

4.7. Response Codes

Below is a table showing the response codes for the Receiving Payment response

RESPONSE CODE DESCRIPTION

0002 Missing Username Information
0003 Missing Password Information
0004 Missing Date Information
0005 Invalid Password
0006 User Does not have an intouchPay Account
0007 No such user
0008 Failed to Authenticate
0002 Missing Username Information
0003 Missing Password Information

12