Tigo Partner Integration API Details
Uploaded by
ujingasTigo Partner Integration API Details
Uploaded by
ujingasPartner Integration
API Details
Document Version 1.2
1
Partner Integration (A2W & W2A) API Details
TIGOPESA – Partner Integration (A2W & W2A) API Details
Table of Content
Table of Contents
1.1 Communication Protocol ...................................................................................................................................................................1
1.2 Request XML ............................................................................................................................................................................................... 1
1.3 Response XML ............................................................................................................................................................................................ 1
2.1 Use Case 1: Wallet to Account / TIGO to Partner (Pay amount from Subscriber’s TIGOPESA wallet to
Partner Collection account through Payment Gateway) – Synchronous ................................................................................ 2
2.1.1 Input to the Partner Application ........................................................................................................................................2
2.1.2 from the Payment Gateway – SYNC_BILLPAY_API Request ............................................................................. 2
2.1.2 Output from the Partner Application to the Payment Gateway System – SYNC_BILLPAY_API
Response 3
2.2 Use Case 2: Account to Wallet / Partner to TIGO (Transfer amount from Partner’s TigoPesa
Disbursement account to subscriber’s TIGOPESA wallet through Payment Gateway) – Synchronous................. 5
2.2.1 Input to the Payment Gateway System from the Partner Application – ‘MFI CashIn’ API
Request 5
2.2.2 Output from the Payment Gateway System to the Partner Application – ‘MFI CashIn’ API
Response 6
2i PAGE 1 DOCUMENT VERSION 1.0
Partner Integration (A2W & W2A) API Details
DOCUMENT CONTROL
Document Location
TIGO Tanzania
DOCUMENT DESCRIPTION
Document Name: TIGOPESA – Partner Integration API (A2W &
W2A) Document
Owner while current: TIGO
Type of Document: TIGOPESA – Partner Integration API Document
REVISION HISTORY
Version Date Change Description
1.0 25/06/2014 Baseline Initial version created.
1.2 04/05/2016 More clarity of request formats and error codes
as per new platform
Approvals
Approval refers to the approver’s acceptance of the content and overall intention of this
document, including acceptance of any commitments described in order to successfully
deliver the initiative. The approver, where relevant, also confirms that this document
complies with relevant strategies, policies and regulatory requirements.
Name Role Approved Date
1
Partner Integration (A2W & W2A) API Details
TIGOPESA
–
Partner
Integration
(A2W
&
W2A)
API
Details
1.1 Communication Protocol
The transport protocol of this interface is XML over HTTP.
The expected HTTP method is always POST.
The expected headers in the request & response are ‘Content-‐type’ & ‘Connection’.
1.2 Request XML
A request to perform a function is sent using the COMMAND element.
POST <URL> HTTP
Content-‐type: text/xml
Connection: keep-‐alive
<?xml version="1.0"?>
<COMMAND>
-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐
-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐
-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐
</COMMAND>
1.3 Response XML
The response to a request to perform a function uses the COMMAND element.
HTTP/1.1 200 OK
Content-‐type: text/xml
Connection: close
<?xml version="1.0"?>
<COMMAND>
-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐
-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐
-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐
</COMMAND>
PAGE 1 DOCUMENT VERSION 1.0
2
Partner Integration (A2W & W2A) API Details
TIGOPESA – Partner Integration (A2W & W2A) API Details
2.1 Use Case 1: Wallet to Account / TIGO to Partner (Pay amount
from Subscriber’s TIGOPESA wallet to Partner Collection account
through Payment Gateway) – Synchronous
2.1.1 Input to the Partner Application from the Payment Gateway –
SYNC_BILLPAY_API Request
Field name Max-‐length Description
TYPE
NA
The
request
type
of
the
transaction.
The
value
will
be
constant
in
all
the
request.
Ex
-‐
SYNC_BILLPAY_REQUEST
TXNID
20
Alphanumeric-‐This
field
will
be
Tigo
transaction
ID.
It
will
be
unique
for
all
transactions.
Ex
-‐
BP140218.1240.B01530
MSISDN
10/12
Payer
MSISDN
should
be
without
country
code.
Ex
–
0721777777
or
255721777777
AMOUNT
NA
Numeric,
Ex
-‐
1000
COMPANYNAME
6
Numeric.
This
is
the
business
number,
or
biller
code
Ex
–
12345
CUSTOMERREFERENCEID
50
Bill
pay
reference
number,
normally
generated/shared
by
partner
application.
This
is
used
by
partner
application
to
validate
payments.
Alphanumeric
characters.
Ex
–
T1234ABC
Sample
request
message
from
the
Payment
Gateway
to
Partner
Application
‘SYNC_BILLPAY_API’
is
attached
here.
<?xml
version="1.0"?>
<COMMAND>
<TYPE>SYNC_BILLPAY_REQUEST</TYPE>
<TXNID>tigo_txnID</TXNID>
PAGE 2 DOCUMENT VERSION 1.0
3
Partner Integration (A2W & W2A) API Details
TIGOPESA – Partner Integration (A2W & W2A) API Details
<MSISDN>user
_msisdn</MSISDN>
<AMOUNT>amount</AMOUNT>
<COMPANYNAME>copny_ID</COMPANYNAME>
<CUSTOMERREFERENCEID>Partner_reference_number</CUSTOMERREFERENCEID>
</COMMAND>
1.1.1 Output from the Partner Application to the Payment Gateway System
– SYNC_BILLPAY_API Response
Field name Max-‐length Description
TYPE
NA
The
response
type
of
the
transaction.
The
value
will
be
constant
in
all
the
response.
Ex
–
SYNC_BILLPAY_RESPONSE
TXNID
20
Tigo
Transaction
ID
sent
in
the
request.
Ex
-‐
BP140218.1240.B01530
REFID
50
Partner
Application
generated
Transaction
ID.
It
should
be
unique
for
all
transaction.
Ex
-‐
000217605331
RESULT
2
Status
of
the
transaction.
String
value.
Ex
–
Either
TS
or
TF
ERRORCODE
20
Particular
Error
Code
returned
in
the
transaction.
Will
be
Alphanumeric.
Ex
-‐
error000
for
success
ERRORDESCRIPTION
NA
Error
Description
(String).
Ex-‐
Transaction
Successful
MSISDN
10
Numeric
-‐
Subscriber
(Payer)
phone
number
Ex
–
0656856028
FLAG
1
String
value.
Ex
–
Either
Y
or
N
CONTENT
NA
Alphanumeric
field
may
be
present
under
this
field.
Maximum
140
characters
No
special
characters
like
pipe(‘|’)
Ex
-‐
Dear
Subscriber
your
Transaction
has
been
submitted
successfully.
Sample
response
message
from
the
Partner
Application
to
the
Payment
Gateway
‘SYNC_BILLPAY_API’
is
attached
here.
PAGE 3 DOCUMENT VERSION 1.0
4
Partner Integration (A2W & W2A) API Details
TIGOPESA – Partner Integration (A2W & W2A) API Details
<?xml
version="1.0"?>
<COMMAND>
<TYPE>SYNC_BILLPAY_RESPONSE</TYPE>
<TXNID>BP140218.1240.B01530</TXNID>
<REFID>000217605331</REFID>
<RESULT>TS</RESULT>
<ERRORCODE>error000</ERRORCODE>
<ERRORDESC/>
<MSISDN>0714405395</MSISDN>
<FLAG>Y</FLAG>
<CONTENT>message_content.</CONTENT>
</COMMAND>
The following are the list of expected ERRORCODE and its description from Partner Application:
Error Code Description
error000 Successful transaction
error001 Service not available
error010 Invalid Customer Reference Number
error011 Customer Reference Account locked
error012 Invalid Amount
error013 Amount insufficient
error014 Amount too high. Try a smaller amount
error015 Amount too low. Try a larger amount
error016 Invalid payment
error100 General Error
error111 Retry condition. No response
Other Error As per agreement with partner, during integration
PAGE 4 DOCUMENT VERSION 1.0
5
Partner Integration (A2W & W2A) API Details
TIGOPESA – Partner Integration (A2W & W2A) API Details
1.2 Use Case 2: Account to Wallet / Partner to TIGO (Transfer
amount from Partner’s TigoPesa Disbursement account to
subscriber’s TIGOPESA wallet through Payment Gateway) –
Synchronous
1.2.1 Input to the Payment Gateway System from the Partner Application –
‘MFI CashIn’ API Request
Field name Max-‐length Description
TYPE
10
The
request
type
of
the
transaction.
The
value
will
be
constant
in
all
the
request.
Ex
-‐
REQMFICI
REFERENCEID
20
A
value
consisting
of
combination
of
alphanumeric
characters
that
uniquely
identifies
each
request
made
by
the
MFI
Server.
This
value
has
to
be
provided
by
the
MFI
Server
and
a
combination
of
the
TYPE
and
REFERENCEID
field
has
to
be
unique.
Ex
-‐
CI000000000000000001
Note:
Maximum
allowed
length
for
this
element
is
restricted
to
‘20’.
MSISDN
12
Payer
MSISDN.
This
can
should
be
with
country
code.
Ex
–
255721777777
Note:
The
MSISDN
of
Partner
disbursement
account
in
TIGOPESA
has
to
be
passed
in
the
request.
PIN
4
Numeric
or
alphanumeric.
Ex
–
1456
Note:
The
PIN
of
the
Partner
disbursement
account
in
TIGOPESA
has
to
be
passed
in
the
request.
MSISDN1
10/12
Payee
MSISDN
should
be
with/without
country
code.
Ex
–
0721151515
Note:
The
MSISDN
of
the
subscriber’s
account
in
TIGOPESA
has
to
be
passed
in
the
request.
AMOUNT
10
Numeric
Only.
Should
not
accept
amount
in
decimal
points
because
there
is
no
support
for
cents.
Ex
-‐
1000
LANGUAGE1
2
Payer
Language
Ex
-‐
en
PAGE 5 DOCUMENT VERSION 1.0
6
Partner Integration (A2W & W2A) API Details
TIGOPESA – Partner Integration (A2W & W2A) API Details
Sample
request
message
from
the
Partner
application
to
the
Payment
Gateway
(MFI
CashIn
API)
is
attached
here.
<?xml
version="1.0"?>
<COMMAND>
<TYPE>REQMFICI</TYPE>
<REFERENCEID>REFERENCEID</REFERENCEID>
<MSISDN>MFI-‐MSISDN</MSISDN>
<PIN>MFI-‐PIN</PIN>
<MSISDN1>SUBS-‐MSISDN</MSISDN1>
<AMOUNT>AMOUNT</AMOUNT>
<LANGUAGE1>LANGUAGE-‐CODE</LANGUAGE1>
</COMMAND>
1.2.2 Output from the Payment Gateway System to the Partner Application
– ‘MFI CashIn’ API Response
Field name Max-‐length Description
TYPE
10
Response
Type.
The
value
will
be
constant
in
all
the
response.
Ex
-‐
RESMFICI
REFERENCEID
20
The
same
value
that
is
contained
in
the
REFERENCEID
tag
of
the
Request
XML.
Partner
Application
generated
Transaction
ID.
Ex
-‐
CI000000000000000001
Note:
Maximum
allowed
length
for
this
element
is
restricted
to
‘20’.
TXNID
20
Tigo
Pesa
Transaction
ID
for
the
Cash-‐In
Transaction.
Ex
-‐
42326232
TXNSTATUS
5
Various
transaction
status
Failed,
Success
etc.
Ex
–
200
or
0
for
success
MESSAGE
NA
Response
message.
Ex
-‐
Success
Sample
response
message
from
the
Payment
Gateway
System
to
Partner
Application
‘MFI
CashIn’
API
is
attached
here.
<?xml
version="1.0"?>
<COMMAND>
<TYPE>RESMFICI</TYPE>
<REFERENCEID>REFERENCEID</REFERENCEID>
<TXNID>42326232</TXNID>
<TXNSTATUS>200</TXNSTATUS>
<MESSAGE>Success</MESSAGE>
</COMMAND>
PAGE 6 DOCUMENT VERSION 1.0
7
Partner Integration (A2W & W2A) API Details
TIGOPESA – Partner Integration (A2W & W2A) API Details
Note:
1. In
case
of
Fail
response
from
Tigo
Pesa,
TXNID
(Tigo
Transaction
ID)
element
in
the
response
will
be
empty.
The following are the list of possible TXNSTATUS codes and description:
TXNSTATUS MESSAGE
00026 PIN expired. Please change your PIN.
00031 Requested amount more then allowed in the network
00042 Requested amount not in multiple of allowed value
317 Unable to complete transaction as recipient A/c is barred. Error code 00317.
Unable to complete transaction as amount is more than the maximum limit. Error
410
code: 00410.
2117 Unable to complete transaction as sender A/c is barred. Error code 02117.
200 or 0 Success
Unable to complete transaction as maximum transaction value per day for payer
60014
reached. Error code 60014.
Unable to complete transaction as transaction amount is less than the minimum
60017
txn value for sender. Error code 60017.
Unable to complete transaction as amount is more than the maximum limit. Error
60018
code 60018.
Unable to complete transaction as account would go below minimum balance.
60019
Error code 60019.
Unable to complete transaction as maximum number of transactions per day for
60021
Payee was reached. Error code 60021.
Unable to complete transaction as maximum transaction value per day reached.
60024
Error code 60024.
Unable to complete transaction as transaction amount is more than the
60028
maximum txn value for recipient. Error code 60028.
Unable to complete transaction as the Payee account would go above maximum
60030
balance. Error code: 60030.
60074 Payee Role Type Transfer Profile not defined
This is generic error, which is returned if problem happen during transaction
processing. Partner should put transaction amount in HOLD state to avoid risk of
100
rollback while amount was disbursed. This is the same case for any kind of
timeout as well.
Other Error As may be added & agreed during integration
PAGE 7 DOCUMENT VERSION 1.0
8
Global Mobile Financial Services
Tigo Pesa
Partner Developer’s Guide
You might also like
- KCB Mpesa STK Push Api Specification DocumentNo ratings yetKCB Mpesa STK Push Api Specification Document4 pages
- Myob V19.12 - A Practical Guide To Computer Accounting: Accountright PlusNo ratings yetMyob V19.12 - A Practical Guide To Computer Accounting: Accountright Plus4 pages
- Introduction To Basic Process Documents: by Jaswant TawdeNo ratings yetIntroduction To Basic Process Documents: by Jaswant Tawde37 pages
- Tigo Pesa Ni Zaidi Ya Pesa!: Account StatementNo ratings yetTigo Pesa Ni Zaidi Ya Pesa!: Account Statement5 pages
- Tigo Pesa Ni Zaidi Ya Pesa!: Account Statement100% (1)Tigo Pesa Ni Zaidi Ya Pesa!: Account Statement7 pages
- Microsoft Dynamics - AX Installation Guide PDFNo ratings yetMicrosoft Dynamics - AX Installation Guide PDF330 pages
- Chapter 1: Working With Projects: ObjectivesNo ratings yetChapter 1: Working With Projects: Objectives28 pages
- Softnet Technologies Limited Company ProfileNo ratings yetSoftnet Technologies Limited Company Profile12 pages
- Microsoft Partner Network Agreement Page 1 of 9No ratings yetMicrosoft Partner Network Agreement Page 1 of 913 pages
- Avaya CTI Adapter - Salesforce - Com Integration Installation and Configuration GuideNo ratings yetAvaya CTI Adapter - Salesforce - Com Integration Installation and Configuration Guide42 pages
- Upi Based Digital Prepaid Voucher 17082023No ratings yetUpi Based Digital Prepaid Voucher 1708202350 pages
- Network Merchants (NMI) Integration Resources: Direct Post API DocumentationNo ratings yetNetwork Merchants (NMI) Integration Resources: Direct Post API Documentation11 pages
- Napas - TechSpec For QR Payment - API - Bank - v0.8No ratings yetNapas - TechSpec For QR Payment - API - Bank - v0.8102 pages
- WL-IPG-Merchant Integration Kit - Standard - V1.2 - PHPNo ratings yetWL-IPG-Merchant Integration Kit - Standard - V1.2 - PHP16 pages
- JCB QR Cross Border Payments_Sample Code Guide_v2.1No ratings yetJCB QR Cross Border Payments_Sample Code Guide_v2.124 pages
- 11 - CT071!3!3-DDAC - Serverless Solutions in Cloud (Part 2)No ratings yet11 - CT071!3!3-DDAC - Serverless Solutions in Cloud (Part 2)99 pages
- 7-1-1 Guaranteed Delivery Developers GuideNo ratings yet7-1-1 Guaranteed Delivery Developers Guide26 pages
- JCB QR Cross Border Payments_C# Sample Code Guide_v2.1No ratings yetJCB QR Cross Border Payments_C# Sample Code Guide_v2.120 pages
- Mining With Windows Part 5 - Solo Mining With More PCs That Point To One PC With WalletNo ratings yetMining With Windows Part 5 - Solo Mining With More PCs That Point To One PC With Wallet3 pages
- DM00039672 - AN3990 - Upgrading STM32F4DISCOVERY Board Firmware Using A USB KeyNo ratings yetDM00039672 - AN3990 - Upgrading STM32F4DISCOVERY Board Firmware Using A USB Key14 pages
- AVG-HD300SR-A: Downloaded From Manuals Search EngineNo ratings yetAVG-HD300SR-A: Downloaded From Manuals Search Engine12 pages
- Guide For Cleaning SLA Outcome Specification Performance Based Contract (No ratings yetGuide For Cleaning SLA Outcome Specification Performance Based Contract (36 pages
- Proforma Invoice: Wagtech Projetcs LTD Wagtech Court Thatcham, Berks United Kingdom, RG19 4HZ 30No ratings yetProforma Invoice: Wagtech Projetcs LTD Wagtech Court Thatcham, Berks United Kingdom, RG19 4HZ 305 pages
