API Details
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'.
Request XML
A request to perform a function is sent using the COMMAND element.
POST
Content-‐type: text/xml
Connection: keep-‐alive
1 2 3 4 5 6 7 | |
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
1 2 3 4 5 6 7 | |
Partner Integration (A2W & W2A) API Details
Use Case 1: Wallet to Account / TIGO to Partner (Pay amount from Subscriber's TIGOPESA wallet to Partner Collection account through Payment Gateway) – Synchronous
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 valuewill 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 here.
1 2 3 4 5 6 7 8 9 10 | |
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(' |
Sample response message from the Partner Application to the Payment Gateway 'SYNC_BILLPAY_API' is
1 2 3 4 5 6 7 8 9 10 11 12 | |
| 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 |
Account to Wallet
Partner to TIGO (Transfer amount from Partner's TigoPesa Disbursement account to subscriber's TIGOPESA wallet through Payment Gateway) – Synchronous
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 tha 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 |
Sample request message from the Partner application to the Payment Gateway (MFI CashIn API) is here.
1 2 3 4 5 6 7 8 9 10 11 | |
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 here.
1 2 3 4 5 6 7 8 9 | |
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. |
| 410 | Unable to complete transaction as amount is more than the maximum limit. Error code: 00410. |
| 2117 | Unable to complete transaction as sender A/c is barred. Error code 02117. 200 or 0 Success |
| 60014 | Unable to complete transaction as maximum transaction value per day for payer reached. Error code 60014. |
| 60017 | Unable to complete transaction as transaction amount is less than the minimum txn value for sender. Error code 60017. |
| 60018 | Unable to complete transaction as amount is more than the maximum limit. Error code 60018. |
| 60019 | Unable to complete transaction as account would go below minimum balance. Error code 60019. |
| 60021 | Unable to complete transaction as maximum number of transactions per day for Payee was reached. Error code 60021. |
| 60024 | Unable to complete transaction as maximum transaction value per day reached. Error code 60024. |
| 60028 | Unable to complete transaction as transaction amount is more than the maximum txn value for recipient. Error code 60028. |
| 60030 | Unable to complete transaction as the Payee account would go above maximum balance. Error code: 60030. |
| 60074 | Payee Role Type Transfer Profile not defined This is generic error, which is returned if problem happen during transaction |
| 100 | processing. Partner should put transaction amount in HOLD state to avoid risk of rollback while amount was disbursed. This is the same case for any kind of timeout as well. Other Error |