Api Document3

Integration Guide
GSMA Hackathon – Easypaisa Integration Guide

Version 1.1
3rd Oct 2017
1
Integration Guide
Document Information
Version History
Version # Date Prepared By Reviewed By Reason for change
V 1.0 23rd Sept Usama - -
V1.1 3rd Oct Usama - -
2
Integration Guide
Table of Contents
Introduction .................................................................................................................................................. 5
1. Getting Started.................................................................................................................................. 5
1.1 Generate Token ........................................................................................................................ 5
2. API Fundamentals ............................................................................................................................. 5
2.1 URI ............................................................................................................................................. 5
2.2 Operations................................................................................................................................. 5
2.3 HTTP Header Information ......................................................................................................... 6
2.4 User credentials and channel details ........................................................................................ 6
3. Get Company List .............................................................................................................................. 6
3.1 Request: .................................................................................................................................... 6
3.2 Response: .................................................................................................................................. 7
3.3 JSON Response .......................................................................................................................... 7
4. Bills API .............................................................................................................................................. 7
4.1 Request Parameters: ................................................................................................................. 7
4.2 Response Parameters: .............................................................................................................. 7
4.3 JSON Response: ......................................................................................................................... 8
5. Bill payments API .............................................................................................................................. 8
5.2 Response Parameters: .............................................................................................................. 9
5.3 JSON Request/Response: .......................................................................................................... 9
6. Merchant Payment ........................................................................................................................... 9
6.2 Response Parameters: ............................................................................................................ 10
6.3 JSON Request/Response: ........................................................................................................ 10
7. Deposit into Account ...................................................................................................................... 11
7.1 Request Parameters: ............................................................................................................... 11
8. Money Transfer to Mobile Account ................................................................................................ 12
3
Integration Guide

9. Money Transfer to Bank Account ................................................................................................... 14
10. Error Handling ............................................................................................................................. 16
4
Integration Guide
Introduction
For GSMA Hackathon, following list of Easypaisa transactions (both subscriber and merchant initiated)
are exposed using which developers can come up with ideas, build solutions and financial products to
complete the GSMA challenges.
Using these APIs developers can perform bill payments, money transfers, merchant payments and cash
deposit functionalities into their products. API list is provided below:
1. Get Company List

2. Bill Inquiry
3. Bill Payment
4. Merchant Payment
5. Deposit into Account
6. Money Transfer to Mobile Account
7. Money Transfer to Bank Account
1. Getting Started
All APIs are authorized through OAuth2 token generated from generate token API provided below,
access token returned is then passed in header as Bearer.
1.1 Generate Token

 Generate Oauth access token by using below URL in post request.
 Use ( Basic Base64Encode(consumer_key:consumer_secret) as Authorization header with
provided URL to generate token.
 Consumer_key and consumer_secret will be pre-shared at event.
 Oauth token is valid for 60 minutes, after which a new token is to be generated.
URL: https://api.telenor.com.pk/oauthtoken/v1/generate?grant_type=client_credentials
2. API Fundamentals
2.1 URI
All services exposed are harmonized on Mobile Money standards and use the following URI format:
https://api.telenor.com.pk/{version}/mm/{Resource}
Where:
• Version is as per standards defined in the API Versioning section. Initial version is v1.1
• mm is literal for ‘Mobile Money’
• Resource identifies the object and resource that is the subject of the API.
2.2 Operations
These API supports two types of HTTP operations as shown below:
• POST: Used to perform financial transactions.

• GET: Used to return a representation of resources.
5
Integration Guide
2.3 HTTP Header Information

The following header information can be supplied for the mobile money API.
Header Value Optionality Notes

Authorization Oath Bearer Mandatory Bearer {token returned from
generate token API}
X-API-Key Pre shared key to be passed Mandatory “TelenorAPIGW”
X-Channel Pre shared channel to be passed Mandatory Details provided in below table
for transactions
X-User- Used to pass end user Mandatory base64Encode(username:password)

Credential-1 credentials for account base64Encode(userid@msisdn:pin)
base64Encode(msisdn:pin)
details provided in below table
Content-Type application/json Optional Mandatory in POST request
2.4 User credentials and channel details

Below are the formats/values to be used for user credentials and channel header against all APIs.
APIs Credentials X-User Credentials X-Channel

Type
Get Company List System User Pre-shared credentials gsma1
Bill Inquiry System User Pre-shared credentials gsma1
Bill Payment Merchant base64Encode(userid@msisdn:pin) gsmamerchant
Credentials
Merchant Payment Merchant Pre-shared credentials gsmamerchant
Credentials
Deposit into Account Merchant base64Encode(userid@msisdn:pin) gsmamerchant
Credentials
Money Transfer to Subscriber base64Encode(msisdn:pin) gsma2
Mobile Account Credentials
Money Transfer to Subscriber base64Encode(msisdn:pin) gsma2
Bank Account Credentials
3. Get Company List

This API is used to fetch biller company details which include company names, service provider accounts
and categories for registered bill companies. It is static data and can be dumped into respective
databases for further use. GET operation is used for this API and URI for this is given below.
URL:
https://api.telenor.com.pk/v1.1/mm/billcompanies
3.1 Request:
Request body is empty as this is a GET operation.
6
Integration Guide
3.2 Response:
Parameter Type Optionality Description Value
Company String Mandatory Display name for bill
name company
Service String Mandatory Company code to be
provider passed for Bill inquiry
and payment
Sub type String Mandatory Subcategory for bill
company. Example
(water, solar)
Type String Mandatory Type of company for
payment
3.3 JSON Response

Response
{
"companies": [
{
"company_name": "AJK-BARKIYAT",
"service_provider":
"electricity_barkiyatajk.sp",
"sub_type": "Electricity",
"type": "Bill"
},
{
"company_name": "AJK-BARKIYAT",
"service_provider":
"electricity_barkiyatajk.sp",
"sub_type": "Electricity",
"type": "Bill"
}
],
"description": "success",
"resultCode": "00"
}
4. Bills API
The Bills API is used for inquiry of billing details against a specific consumer number for a company. This
is a GET operation where the consumer number, customer MSISDN and bill company details (service
provider returned from get companies list) are passed in URL as given below:
URL:
https://api.telenor.com.pk/v1.1/mm/account/msisdn@923xxxxxxxxx$consumerno@xxxxxxx$billcompany@electri
city_fesco.sp/bills
4.1 Request Parameters:

Request body is empty as this is a GET operation.
4.2 Response Parameters:

Amount Due String Mandatory Amount due for bill Amount due for specific
payment consumer number and billing
company is returned which is
7
Integration Guide
passed in Bill Payment API
Currency String Mandatory Currency of amount “PKR”
Due date Date Mandatory Due date for bill payment Due date for bill payment is
returned
Bill Status String Mandatory Bill Status for provided Status for the bill
consumer number and
billing company
4.3 JSON Response:

Response
{
"currency": "PKR",
"amountDue": "10.00",
"dueDate": "170930",
"billStatus": "unpaid",
"metadata": [
{
"key": "Description",
"value": "PROCESSED_OK"
},
{
"key": "ResultCode",
"value": "00"
}
]
}
5. Bill payments API

Bill Payments API allows merchant to pay bills for customer over the counter. With this API a specific bill
associated with a consumer number can be paid for customer. Customer MSISDN is to be passed in URL in
given format. Action for this API would be POST and URL format is given below,
URL:
https://api.telenor.com.pk/v1.1/mm/accounts/msisdn@923xxxxxxxxx/bills/0/payments

Paid Amount String Mandatory Amount for bill payment Enter the amount for
transaction returned from
bill inquiry API against
specific consumer number
Supplementary Bill Ref Mandatory Addition billing details for Consumer number and billing
Reference Details Array bill payment company details to be passed
as payment reference
type/payment reference
value pair
8
Integration Guide

Paid Amount String Mandatory Amount for payment Amount paid by customer
Customer String Mandatory Transaction receipt for Transaction ID for executed

Reference paid bill transaction is returned
Supplementary Ref Mandatory Addition billing details for Description and result code
Bill Reference Array bill payment for transaction are returned as
Details payment reference
type/payment reference value
pair
5.3 JSON Request/Response:
Request Response
{ {
"currency": "PKR", "currency": "PKR",
"paidAmount": "5.00", "paidAmount": "5.00",
"supplementaryBillReferenceDetails": [ "customerReference": "1124745",
{ "supplementaryBillReferenceDetails": [
"paymentReferenceType": "consumerno", {
"paymentReferenceValue": "01131130009720" "paymentReferenceType": "description",
}, "paymentReferenceValue": "success"
{ },
"paymentReferenceType": "billcompany", {
"paymentReferenceValue": "electricity_fesco.sp" "paymentReferenceType": "resultCode",
} "paymentReferenceValue": "00"
] }
} ]
}
6. Merchant Payment
Merchant Payment transactions enable customers to buy goods and pay through their Easypaisa accounts to
merchants. Transactions are initiated from merchant accounts where customer gets a USSD popup for mobile
account pin confirmation, upon successful verification amount is debited form customers account and crediting
into merchant account
This API uses a POST operation and URL is given below.
URL:
https://api.telenor.com.pk/debitma/v1.1/mm/transactions

Amount String Mandatory Amount for payment Enter the amount for
transaction
Type String Mandatory The harmonized “merchantpay”

Transaction Type
9
Integration Guide
Sub Type String Mandatory A non-harmonized sub- “debitMA”

classification of the type
of transaction.
Request Date Date Mandatory The creation date and Enter the date of initiation
Time time of the transaction.
Debit Party Ref Mandatory Debit party information MSISDN of debit party to be
Array passed in key/value pair
Credit Party Ref Mandatory Credit Party information Store ID of merchant to be
Sender KYC Ref Mandatory Sender KYC information Email address of subscriber to
information Array be passed for notification.
Requesting String Mandatory Order ID for the goods This order ID for each
Organization purchased from transaction must be unique for
Transaction merchant. each item.
Reference

Amount String Mandatory Amount for payment Amount paid by customer
Type String Mandatory The harmonized “merchantpay”

Transaction Type
Transaction Status String Mandatory Status for transactions Status of executed transaction
Request Date Date Mandatory The creation date and Date of executed transaction
Transaction String Mandatory Reference of transaction Transaction ID of transaction is
Reference executed returned
Debit Party Ref Mandatory Debit party information MSISDN of debit party is
Array returned in key/value pair
Credit Party Ref Mandatory Credit Party information Store ID of merchant is

Request Response
{ {
"amount": "10.00", "amount": "10.00",
"type": "merchantpay", "type": "merchantpay",
"subType": "debitMA", "transactionStatus": "Success",
"requestDate": "2017-08-16T11:32:03.449Z", "requestDate": "2017-08-16T11:32:03.449Z",
"debitParty": [ "transactionReference": "1122655",
{ "debitParty": [
"key": "msisdn", {
"value": "923458559561" "key": "msisdn",
} "value": "03458559561"
], }
"creditParty": [ ],
{ "creditParty": [
"key": "storeid", {
10
Integration Guide
"value": "641" "key": "storeid",

} "value": "641"
], }
"senderKyc": { ]
"emailAddress": "[email protected]" }
},
"requestingOrganisationTransactionReference": "1234567"
}
7. Deposit into Account

This transaction is used to deposit cash into customers account via merchant. Customers handovers the cash to
the merchants over the counter, merchant initiates’ cash deposit for the customer in his own or any other mobile
account.
URL:
https://api.telenor.com.pk/otctoma/v1.1/mm/transactions

transaction
Type String Mandatory The harmonized “transfer”

Transaction Type
Sub Type String Mandatory A non-harmonized sub- “otcToMa”
of transaction.
Credit Party Ref Mandatory Credit Party information MSISDN of credit party to be
Sender KYC Ref Mandatory Sender KYC information CNIC of sender to be passed in
information Array ID document parameter

Amount String Mandatory Amount for payment Amount deposited into
customer account

Transaction Type
11
Integration Guide
Credit Party Ref Mandatory Credit Party information MSISDN of credit party is
Metadata Ref Mandatory Extra information array Fee applied on transaction is

Request Response
{ {
"amount": "101.00", "amount": "101.00",
"type": "transfer", "type": "transfer",
"subType": "otcToMa", "transactionStatus": "Success",
{ "debitParty": [
"key": "msisdn", {
"value": "923458559561" "key": "msisdn",
} "value": "923458559561"
], }
"creditParty": [ ],
{ "creditParty": [
"key": "msisdn", {
"value": "923458509176" "key": "msisdn",
} "value": "923458509176"
], }
"senderKyc": { ],
"idDocument": [ "metadata": [
{ {
"idType": "nationalidcard", "key": "fee",
"idNumber": "3740566581693" "value": "15.00"
} }
] ]
} }
}
8. Money Transfer to Mobile Account

This transaction is used to transfer funds from one mobile account into another mobile account, transactions are
initiated from subscriber account by provided subscriber credentials in header.
URL:
https://api.telenor.com.pk/transferMA/v1.1/mm/transactions

transaction
12
Integration Guide

Transaction Type
Sub Type String Mandatory A non-harmonized sub- “MA”
of transaction.
Credit Party Ref Mandatory Credit Party information MSISDN of credit party to be
Sender KYC Ref Mandatory Sender KYC information Sender name to be passed in
information Array name tag
Receiver KYC Ref Mandatory Receiver KYC information Receiver name to be passed in

customer account

Transaction Type
Credit Party Ref Mandatory Credit Party information MSISDN of credit party is
Metadata Ref Mandatory Extra information array Fee and tax applied on
Array transaction is returned in
key/value pair

Request Response
{ {
"amount": "10.00", "amount": "10.00",
"subType": "MA", "transactionStatus": "Success",
{ "debitParty": [
"key": "msisdn", {
"value": "923458559561" "key": "msisdn",
} "value": "923458559561"
13
Integration Guide
], }
"creditParty": [ ],
{ "creditParty": [
"key": "msisdn", {
"value": "923455109903" "key": "msisdn",
} "value": "923455109903"
], }
"senderKyc": { ],
"Name": "adeel" "metadata": [
}, {
"recipientKyc": { "key": "fee",
"Name": "osama" "value": "0.00"
} },
} {
"key": "tax",
"value": "0"
}
]
}
9. Money Transfer to Bank Account

This transaction is used to transfer funds from customer’s mobile account into any bank account.
Transaction is initiated from customer account where funds are debited from mobile account and
transferred to provided bank account.
URL:
https://api.telenor.com.pk/transferBank/v1.1/mm/transactions

transaction

Transaction Type
Sub Type String Mandatory A non-harmonized sub- “Bank”
of transaction.
Credit Party Ref Mandatory Credit Party information Bank account number, account
Array title and bank name of credit
party to be passed in key/value
pair
Sender KYC Ref Mandatory Sender KYC information Sender name to be passed in

14
Integration Guide

customer account

Transaction Type
Credit Party Ref Mandatory Credit Party information Bank account number, account
Array title and bank name of credit
party is returned in key/value
pair
Metadata Ref Mandatory Extra information array Fee and tax applied on
Array transaction is returned in
key/value pair

Request Response
{ {
"amount": "100", "amount": "10.00",
"subType": "Bank", "transactionStatus": "Success",
{ "debitParty": [
"key": "msisdn", {
"value": "923458559561" "key": "sender_msisdn",
} "value": "923458559561"
], }
"creditParty": [ ],
{ "creditParty": [
"key": "bankaccountno", {
"value": "00020000011005325" "key": "bankname",
}, "value": "bankaccount_mod.sp"
{ },
"key": "bankaccounttitle", {
"value": " ONELINK ATM TEST CARD251" "key": "accountno",
}, "value": "00020000011005325"
{ },
"key": "bankname", {
"value": "bankaccount_mod.sp" "key": "accounttitle",
}, "value": "ONELINK ATM TEST CARD251"
{ }
"key": "msisdn", ],
"value": "923458508160" "metadata": [
} {
], "key": "fee",
"senderKyc": { "value": "0.0"
"Name": "usama" },
} {
} "key": "tax",
15
Integration Guide
"value": "0.0"
}
]
}
10. Error Handling

Error handling for all API’s is generic with below response where error category, error code and description are
changed.
Error Description Response

Code
{
00 Success "errorCategory": "COULD_NOT_PERFORM_OPERATION",
0001 System Error "errorCode": "500",
"errorDescription": "COULD_NOT_PERFORM_OPERATION",
0002 Required field is missing "errorDateTime": "Sat Sep 30 2017 03:24:09 GMT+0500 (PKT)",
0003 Invalid Order ID "errorParameters": [
{
0004 Merchant Account does not exist "key": "requestId",
"value": "11849-1904-4"
0005 Merchant Account is not active }
0006 Store does not exist ]
}
0007 Store is not active
01 Invalid Access Token
02 Bad Request: Qouta limit reached.
03 Invalid URL
04 Payload validation failed. {ErrorDetail}
11 Spike limit reached. Please try later.
10 Invalid account number
13 Invalid Request Payload
401 Invalid authentication
404 Invalid channel
500 Resource not found / invalid resource
504 Timeout
16

Api Document3

Uploaded by

Copyright:

Available Formats

Api Document3

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Api Document3

Uploaded by

Copyright:

Available Formats

Integration Guide

GSMA Hackathon – Easypaisa Integration Guide

3rd Oct 2017

Version # Date Prepared By Reviewed By Reason for change

V 1.0 23rd Sept Usama - -

V1.1 3rd Oct Usama - -

8.3 JSON Request/Response: ........................................................................................................ 13

1. Get Company List

1.1 Generate Token

• POST: Used to perform financial transactions.

2.3 HTTP Header Information

Header Value Optionality Notes

X-User- Used to pass end user Mandatory base64Encode(username:password)

2.4 User credentials and channel details

APIs Credentials X-User Credentials X-Channel

3. Get Company List

3.3 JSON Response

4.1 Request Parameters:

4.2 Response Parameters:

passed in Bill Payment API

Currency String Mandatory Currency of amount “PKR”

4.3 JSON Response:

5. Bill payments API

5.1 Request Parameters:

5.2 Response Parameters:

Currency String Mandatory Currency of amount “PKR”

Customer String Mandatory Transaction receipt for Transaction ID for executed

5.3 JSON Request/Response:

This API uses a POST operation and URL is given below.

6.1 Request Parameters:

Type String Mandatory The harmonized “merchantpay”

Sub Type String Mandatory A non-harmonized sub- “debitMA”

6.2 Response Parameters:

Currency String Mandatory Currency of amount “PKR”

Type String Mandatory The harmonized “merchantpay”

6.3 JSON Request/Response:

"value": "641" "key": "storeid",

7. Deposit into Account

This API uses a POST operation and URL is given below.

7.1 Request Parameters:

Type String Mandatory The harmonized “transfer”

7.2 Response Parameters:

Type String Mandatory The harmonized “transfer”

7.3 JSON Request/Response:

8. Money Transfer to Mobile Account

This API uses a POST operation and URL is given below.

8.1 Request Parameters:

Type String Mandatory The harmonized “transfer”

8.2 Response Parameters:

Type String Mandatory The harmonized “transfer”

8.3 JSON Request/Response:

9. Money Transfer to Bank Account

This API uses a POST operation and URL is given below.

9.1 Request Parameters:

Type String Mandatory The harmonized “transfer”

9.2 Response Parameters:

Amount String Mandatory Amount for payment Amount deposited into

Type String Mandatory The harmonized “transfer”