JazzCash Mobile Wallet

Disbursement API Reference

Document
Version-2.0

Prepared By: DFS Tech Team

 1 Introduction

1.1Overview
The JazzCash’s Disbursements services enable registered Program Participants (such as
government entities, banks, and digital players) to provide disbursement solutions that
enable businesses, governments, non-profit organizations and other entities to disburse
funds to individuals and businesses with ease. The funds can be disbursed such as salary
disbursement, government payments, loan disbursements and social benefits payments,
and pay individuals.

Acting as an Originating Institution or Transaction Initiator, the registered participant

uses the services to initiate a Payment Transaction via JazzCash’s platform to disburse
funds to the Recipients.
JazzCash’s Disbursement solution provides an instant and convenient bulk/individual
payment solution. The solution is designed to reduce time and cost associated with
traditional paper-based methods and provide a better user experience.

1.1.1 How it Works

Depending on the use cases and program requirements, the initiator can send funds to
JazzCash’s registered mobile money accounts.
 Figure 1: Disbursement Flow

2 Native API Integration

2.1Getting Started
Depending on requirement you may opt to establish connection Mobile Wallet APIs.
Before integrating and consuming API, ensure to establish network connectivity.
We use three-layer security layer measures to secure data by making it unreadable to
anyone without the required unique authentication/authorization keys, protecting it from
unauthorized access or tampering and to maintain confidentiality and integrity.

1. Authentication: We authenticate each API request and grant access to certain

resources or services by authenticate API key and Token.
2. Encryption: To protect the data during transmission we require data in encrypted
format and will pass responses in encrypted format as well to maintain privacy.
3. MPIN verification: Organization pool account registered MSISDN’s MPIN to be
verified by the system. This is typically saved in encrypted form in our database.

Registered MSISDN to be tagged with organization pool account and MPIN needs to be
created.
MPIN to be saved in our database as encrypted and will be passed to our core banking
and verified.

2.2Disburse Funds
JazzCash funds disbursement via API feature allows an organization to pay for individual
customers in bulk. Disbursement APIs are often used by government institutes,
businesses or other organizations to automate the process of making payments to their
employees, vendors, or other recipients.
Some common uses for disbursement APIs include the following:

● Payroll disbursements: A disbursement API can be used to automatically

disburse funds to employees on a regular basis, such as on a weekly or monthly
schedule. This can help to streamline the payroll process and reduce the
administrative burden on the business.

● Vendor payments: A disbursement API can be used to automatically pay

vendors for goods or services that have been received. This can help to ensure
 that vendors are paid promptly and accurately, and it can help to improve
relationships with vendors.

● Expense reimbursement: A disbursement API can be used to automatically

reimburse employees for expenses that have been incurred on behalf of the
business. This can help to simplify the expense reimbursement process and
reduce the time and effort required to process expense reports.

● Relief assistance Programs: These integrations allow Govt. and other

institutions to disburse funds for immediate assistance and social security
programmes.

Overall, the purpose of a disbursement API is to provide a way for businesses and other
organizations to automate the disbursement of funds to their employees, vendors, or
other recipients. By using a disbursement API, businesses can streamline their financial
processes and improve their ability to make timely and accurate payments.

2.3 High Level Process Overview

To disburse funds via API, you will need to go through some process. This will typically
involve the following steps:

1. Set up an account with a JazzCash for disbursement. This will typically involve
providing information about your business and verifying your identity.

2. Integrate the JazzCash disbursement API into your business's systems. This will
typically involve writing code to connect to the API and make requests to disburse
funds.

3. Use the JazzCash’s API to initiate a disbursement. This will typically involve
providing information about the recipient's mobile wallet and the amount of the
disbursement. You’ll also need to provide your unique security credentials in API
requests to prove identity and legitimacy.

4. JazzCash will then process the disbursement and transfer the funds to the
recipient's mobile wallet. This may involve sending a notification to the recipient's
mobile device to confirm the disbursement.

Overall, disbursing funds via JazzCash you may need to integrate the provided APIs into
your systems, and use the APIs to initiate the disbursement. This process can help to
automate the disbursement of funds and make it easier and more efficient to pay
employees, vendors, or other recipients using a mobile wallet.
2.4 Disburse Funds to Registered Mobile
Wallet
The Individual G2P to mobile wallet Payment feature allows an organization to pay
for individual customers one by one. The JazzCash Mobile Money system supports
the service of making individual disbursement payments that allows an organization
to pay for individual registered customers.

API consumers will pass API body as encrypted and will also expect response in
encrypted form. Encryption algorithm along with keys to be shared while integration
onboarding.

AES-128-CBC with HEX (BASE16) notation and no or pkcs7 padding to be applied

for encryption/decryption. API keys to be shared separately.

Staging/QA environment API Signature:

A staging API is a usually copy of the production API that is used for testing and
development purposes, and it is hosted on a separate server or environment.
Below is the generic API signature.

● Staging URL (Get API Token):

https://gateway-sandbox.jazzcash.com.pk /token

API cURL:

Following is the sample cURL for the APIs.

curl --location https://gateway-sandbox.jazzcash.com.pk /token' \
--header 'Authorization: Basic [Your Token] \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Token API Response:

Below is the sample Response which API consumer will receive against token
call. This token will be used for subsequent API calls.
 {
"access_token": "0dfa9cc1-953e-33d9-bfa6-746cd7192e8b", //
Your Access Token for API Calls
"scope": "am_application_scope default",
"token_type": "Bearer", // Type of Token
"expires_in": 2952 // Token Expiry Time in seconds
}

● Staging URL:
https://gateway-sandbox.jazzcash.com.pk/jazzcash/third-party-integration/srv6/
api/wso2/mw/payment

● API Header:

Following is the sample header for G2P APIs.

--header 'Accept: application/json' \

--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 4229509b-97f7-3627-9ffe-
4bf60b3e7642' \ Your access token obtained from get token API
● API Request Body Specification:

The unencrypted Body mobile wallet disbursement API is as below

{
"receiverCNIC": "1111111111111", // mandatory – 13 digits
without hyphen.
"receiverMSISDN": "03071556738", //mandatory - 11 or 12 chars.
"amount": "1.00", //mandatory – numeric string with 2 decimal
points
"referenceId": "moneyMW_1234556543321" //mandatory – String
Data Type
}
 Below is the sample expected body for disbursement API which needs to be
passed.

{
"data":
"86928EA8E1B0EFA3C42BB84AC4E3622966BF6C1E639585DF48CE1C1546A7
500FD4A801F662294F0BD8B9D5585BD729C83AEFE089D30D1CC67BE849A17
28D8A2E3B2910AB5BC142F7A731FAD500F2FB217D992118CCE8B29EFDA2A0
B6331CB98C1277C191355C7A661264577C04BD8620B1EDA5AE4F63731BE58
6E24D99CA4EF3050BE210899B405DB1CCFEDC784E062B"
}
● API Response:
Below is the sample unencrypted response for disbursement API

{ "responseCode": "G2P-T-0", "responseDescription": "The

service request is processed successfully.", "transactionID":
"010719140107", "referenceID": "moneyMW_1234556541100",
"amount": "1.00", "dateTime":"2024-04-16 11:23:05"}

Below is the encrypted response against mobile wallet API which consumer will get

{
"data":
"814c86e695359028d4cab4ba322d4ba9a6b8223472db346be14fbec118d4b
b8d8f17780e91e1c694a360ef9275f206bf3012b68981bde8b1a92bf8c80fe
039d1653bf889de124f8506be1922a325a23fc957fd1e77ae3c0e7a1e79889
12a186d9e4e5b32934decac09794252bb0688b920fecc1e26cfdead9f1032f
edd241fc8907f5e62e4a1a46be5f11e4f967968098b1efb6ba1a591b6e175d
79cb68753652f3969b501d9951b232facb4293dc9aed8384429361244f6117
d0deddf10f8676e88f7ae51015de1ea2329e0d3d4a640979b27fa8c36ce93c
949b5ec66fd4f809b22c630aabab23f12ad921852016ee0"
}
2.5 Transaction Status API

Transaction Status API allows clients to enquire about status of their transaction
based on OriginatorConversationID or referenceID.

● Staging URL:
https://gateway-sandbox.jazzcash.com.pk
/jazzcash/third-party-integration/srv1/api/wso2/transactionStatus

API cURL
Below is the sample cURL
curl --location ' https://gateway-sandbox.jazzcash.com.pk /jazzcash/third-
party-integration/srv1/api/wso2/transactionStatus' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 12299127-8317-31a5-a776-
7c863e49256a' \
--data
'{"data":"e49cc24c6dea0a3cc75a7a0f38721c4090b5961f230eb2d704a2
8c5b531deafe4f9c997adb5709f9cb56e74b254b0550f33d0b807cbd0eea0
2c2e159411925a7b22d62afc99ae09d46759d016a962a5111b6efb58bcb6
723d030a352ad6e38ed"}'

Sample Inquiry Request Packet (Decrypted):

{
"originalReferenceId":"OriID_OFT1202145719",
"referenceID":"4455AFD_OFT6357344644334350"
}

Sample Inquiry Response Packet (Decrypted):

{
"responseCode": "G2P-T-0",
"responseDescription": "Process service request
successfully.",
"transactionID": "010719095571",
"referenceID": "OriID_OFT12202145709",
"transactionStatus": "Successful",
"isReversed": "0"
 }

3 Best Practices & Miscellaneous

Information
We use HTTPs (Hypertext Transfer Protocol) over TCP (Transmission Control
Protocol) for transferring data with TLS (Transport Layer Security) to protect the
data being transmitted from being intercepted by malicious actors. We also
whitelist source IP(s) as an enhanced security measure for our partners however it’s
the sole responsibility of API consumers to protect its API resources.
API keys are unique strings of characters that are used to authenticate API requests
and grant access to certain resources or services. It is important to keep API keys
secure to prevent unauthorized access and protect sensitive data. Here are a few
ways to keep API keys safe along with other best practices:

1. Use a secure storage solution: API/Encryption keys should be stored in a

secure location, such as a password manager or a secure file on your
computer. Avoid storing keys in plaintext files or in hard coded scripts, as
these can be easily accessed by unauthorized parties.
2. Restrict access to AP/EncryptionI keys: If you are sharing your keys with other
developers or team members, it is a good idea to restrict access to only those
who need it. This can be done by using roles and permissions.
3. Contact JazzCash immediately if you think your keys have been compromised
internally/externally and get it updated.
4. You may use the following convention for OriginatorConversationID
parameter
“OrgABC-20222511-165501” Where OrgABC is the short name for your
organization following timestamp in yymmdd-hhmmss format.
5. You may also provide any Jazz/Non-Jazz MSISDN (depending on use case) for
test account creation and test possible flows.
4 Response Codes

Sr. No API Code API Description

01 G2P-T-400 Bad Request

02 G2P-T-205 There is an issue with your transactions,

kindly contact JazzCash before reprocessing
the transaction.

03 G2P-T-500 There is an issue with your transactions,

kindly contact JazzCash before reprocessing
the transaction.

04 G2P-T- -1 System internal error.

05 G2P-T-0 The service request is processed successfully.

06 G2P-T-1 System busy. Please try again later.

07 G2P-T-2 Original Transaction is expired.

08 G2P-T-10 Request Message Structure is invalid.

09 G2P-T-11 Request Message is invalid.

10 G2P-T-13 The OriginatorConversationID is duplicated.

11 G2P-T-17 The security credential is invalid.

12 G2P-T-2000 Initiator Authentication Error.

13 G2P-T-2001 Receiver is invalid.

14 G2P-T-2002 Transaction information is invalid.

15 G2P-T-2005 Cannot match the reason type.

16 G2P-T-2006 Limit is breached.

17 G2P-T-2008 Amount is invalid.

18 G2P-T-2009 Insufficient Balance.

19 G2P-T-2010 The MSISDN don’t match with the CNIC.

20 G2P-T-2015 Not able to process in the third party.

 21 G2P-T-2016 Transaction expired.

22 G2P-T-2017 Original Transaction is not complete.

23 G2P-T-2018 Original Transaction is not successful.

24 G2P-T-2024 Sender/Receiver MSISDN/CNIC Identical

25 G2P-T-30008 Invalid Bank Account

26 G2P-T-97 There was a problem with your request.

Please recheck the parameters/format and try
again.

27 G2P-T-98 Some Parameter is missing or invalid.

28 G2P-T-99 There is an issue with your transaction. Kindly

contact Jazzcash before reprocessing the
transaction.

5 Key Takeaways
Below points need to be remembered while doing testing.
 A dummy CNIC is created on staging environment that will be shared
with clients with credentials.
 Clients are supposed to use given CNIC and shared MSISDN
(consumer) for testing.
 Please make sure testing is being done via shared whitelisted IP(s).
 Credentials are shared only when testing is being done by Clients.
 Clients need to make sure their server is connected and cache is
cleared, otherwise they might face an error.
 Clients are required to do an extensive testing of all the scenarios
shared separately by JazzCash.
6 Go Live Checklist:
 Financial report from CPS will be shared daily with the designated
disbursement partner POC. Please perform financial reconciliations
with this daily and report in case of any issues.
 Please ensure that no re-attempt is made in case of failed scenario,
until reconciliation is done with the CPS report to avoid duplicate
transactions.
 In-case of any disputes, please share complete API request/response
logs within 5 working days of the disputed transaction so it can be
checked and troubleshooted in detail.
 Both parties will share escalation matrix before go-live for technical
support.
 Disclaimer
Copyright 2024@JazzCash. All rights reserved. The information contained in this API
documentation is proprietary and confidential. It is intended solely for the use of
JazzCash partners and developers who have been granted access to the API. Any
unauthorized use, reproduction, or distribution of this documentation or the API is
strictly prohibited. JazzCash reserves the right to change or modify the API and this
documentation at any time without notice.