Tigo Online Payment Api Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 53
| Download | |
| Open PDF In Browser | View PDF |
Global Mobile Financial Services Partner Developer’s Guide Version 0.12 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 2 Global Mobile Financial Services Partner Developer’s Guide Table of Content Table of Contents 1. Introduction to Millicom ................................................................................. 5 2. About this guide ............................................................................................. 6 3. Application integration guidelines .................................................................. 7 4. API Specification............................................................................................19 A. Appendices ...................................................................................................41 2.1. Introduction ............................................................................................................................................6 2.2. Conventions ............................................................................................................................................6 2.2.1. Code and API references ............................................................................................................... 6 2.2.2. Sample data........................................................................................................................................ 6 2.2.3. Warning ............................................................................................................................................... 6 2.2.4. Note ........................................................................................................................................................ 6 2.3. Definitions ...............................................................................................................................................6 3.1. 3.2. 3.3. 3.4. 3.5. 3.6. 3.7. 3.7.1. 3.7.2. 3.8. Connectivity and communication ................................................................................................ 7 Integration steps ................................................................................................................................. 7 Partner Mobile Accounts ................................................................................................................. 8 Session Access Token ........................................................................................................................ 9 System Status heartbeat signal .....................................................................................................9 International Remittance Money Deposit................................................................................. 9 Payment Authorization ................................................................................................................. 11 Payment Authorization via SMS verification code........................................................ 11 Payment Authorization via USSD Push.............................................................................. 15 Reverse Transaction ....................................................................................................................... 17 4.2. Introduction ....................................................................................................................................... 19 4.3. Generate Access Token Service.................................................................................................. 19 4.3.1. Request .............................................................................................................................................. 19 4.3.2. Response............................................................................................................................................ 20 4.4. System Status Service .................................................................................................................... 21 4.4.1. Request .............................................................................................................................................. 21 4.4.2. Response............................................................................................................................................ 21 4.5. Payment Authorization service.................................................................................................. 22 4.5.1. Request .............................................................................................................................................. 22 4.5.2. Response............................................................................................................................................ 24 4.5.3. Payment status callback............................................................................................................ 25 4.6. Validate MFS Account Service .................................................................................................... 28 4.6.1. Request .............................................................................................................................................. 28 4.6.2. Response............................................................................................................................................ 29 4.7. Deposit Remittance Service ......................................................................................................... 30 4.7.1. Request .............................................................................................................................................. 30 4.7.2. Response............................................................................................................................................ 32 4.8. Reverse Transaction service ....................................................................................................... 33 4.8.1. Request .............................................................................................................................................. 33 4.8.2. Response............................................................................................................................................ 34 4.9. Payment Authorization Transaction Status service .......................................................... 35 4.9.1. Request .............................................................................................................................................. 35 4.9.2. Response............................................................................................................................................ 35 4.10. Deposit Remittance Transaction Status service.................................................................. 38 4.10.1. Request .............................................................................................................................................. 38 4.10.2. Response............................................................................................................................................ 38 i A.1. Currency Codes ................................................................................................................................. 41 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 3 Global Mobile Financial Services Partner Developer’s Guide A.2. Country Codes ................................................................................................................................... 42 A.3. Language Codes ................................................................................................................................ 43 A.4. Country Calling Codes .................................................................................................................... 44 A.5. Amount Format Convention ........................................................................................................ 45 A.6. Result and error codes................................................................................................................... 46 A.6.1. HTTP status codes ........................................................................................................................ 46 A.6.2. General error codes...................................................................................................................... 46 A.6.2.1. IP address not whitelisted............................................................................................................... 46 A.6.2.2. Invalid Request .................................................................................................................................... 46 A.6.2.3. Invalid Access Token ......................................................................................................................... 47 A.6.2.4. Access Token Expired ........................................................................................................................ 47 A.6.2.5. Transaction Reference ID already used ................................................................................... 47 A.6.3. API Permission error ................................................................................................................... 47 A.6.4. Service specific result and error codes................................................................................ 47 A.6.4.1. Payment Authorization Service result codes ......................................................................... 49 A.6.4.2. Validate MFS Account Service result codes ............................................................................ 49 A.6.4.3. Deposit Remittance Service result codes ................................................................................. 51 ii Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 4 Global Mobile Financial Services Partner Developer’s Guide Version Control iii Date/Time Version Changes 01/09/2014 16/09/2014 18/09/2014 22/09/2014 29/09/2014 0.1 0.2 0.3 0.4 0.5 6/10/2014 9/10/2014 0.6 0.7 15/10/2014 0.8 27/11/2014 0.9 28/11/2014 0.10 12/12/2014 0.11 13/04/2015 0.12 First Draft Added Payment Authorization flow Added section on MFS accounts/wallets Updated API fields after review Added Sections 3.4, 4.2 for the heartbeat signal, Updated Section 4.4.5 payment authorization callback Update after internal review Section 3.7: Updated Payment Authorization sequence diagram with customer redirect; Section 4: Addedto the URLs in the API specifications; Section 4.4: Added example System Status Service; Section 4.5.1: Updated Payment Authorization URL, added description on the fees in the Payment Auth request, Added currency code for Merchant fee; Section 4.5.2: Added Payment Authorization response with redirect URL; Section 4.5.3: Added section for Payment Status call back; Section 4.8.1: Updated Payment Authorization status response structure Section 3.7: Updated Payment Authorization screenshots to align with new UI design and updated description Section 4.7: Included Sender details in Remittance request Section 4.8: Added createdOn and completeOn fields Annex A.4.6.2: updated Deposit Remittance Error codes Included Payment Authorization error codes Minor typo updates and clarifications throughout the document; Section 3.6: updated description and flow for international remittance; Section 4.6: Changed the First name, last name fields in the Validate MFS account to be optional; Section 4.7: made the verificationRequest parameter optional and added explanation that this feature is not supported in current version, added an optional flag to send a text message; Section 4.8 and Section 4.9: Updated the transaction reference for looking up the Payment Authorization Transaction Status and Deposit Remittance Transaction Status to include the company name appended to the transaction reference ID. Added two warnings in Payment Authorization request Section 4.5.1 on the access token and transaction reference id; Added Reverse Transaction (Section 3.8 and 4.8 Revered change in OriginPayment (Section 4.5.1) Added Amount formatting (Annex) Add new error code with description for the Cancel Transaction scenario Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 5 Global Mobile Financial Services Partner Developer’s Guide 1. Introduction to Millicom Founded in 1990 and headquartered in Luxembourg with corporate offices in Stockholm, London and Miami, Millicom’s subsidiaries operate exclusively in emerging markets in Africa and Latin America. Millicom’s shares are listed on the Nasdaq OMX exchange in Stockholm and Millicom’s market capitalisation was SEK64 billion ($9.9 billion) at the end of 2013. Millicom is a leading international telecommunications and media company dedicated to emerging markets in Latin America and Africa. We set the pace by offering a range of digital lifestyle services which connect people to their world. Operating in 15 countries, with e-commerce partnerships in 22, Millicom offers innovative and customer-centric products. Millicom employs over 11,500 people and provides mobile, cable, broadband, TV and mobile financial services to over 50 million customers. Millicom has divided its business into four strategic pillars. An overview of our progress on the strategic pillars is given as follows: 1 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 6 Global Mobile Financial Services Partner Developer’s Guide 2. About this guide 2.1. Introduction This reference document is intended for Millicom partners to plan, build and deploy applications that wish to connect and use the Tigo Mobile Financial Services (MFS). The two services currently provided: Online payments International money transfers to Tigo mobile wallet. This document covers all the implementation details concerning network connectivity, security and API specification in order to successfully integrate with the International Tigo MFS services. The step by-step guide will guarantee successful and secure integration with the services. 2.2. Conventions 2.2.1. Code and API references Any code or API references are specified in the Courier font: for example see the GenerateAccessToken API 2.2.2. Sample data Sample data such as responses and requests are shown in a separate yellow colored text box 2.2.3. Warning Warning: is shown in a red colored text box with an icon to catch the attention. Most warnings are security related. 2.2.4. Note 2.3. Term API UAT JSON MFS OTP SSL URI 2 A note is shown to catch attention and provide useful information and extra explanation of the applicable section Definitions Definition Application Programming Interface User Acceptance Testing JavaScript Object Notation Mobile Financial Services One Time PIN Secure Sockets Layer Uniform Resource Identifier Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 7 Global Mobile Financial Services Partner Developer’s Guide 3. Application integration guidelines 3.1. Connectivity and communication The diagram below shows a high level view of the international integration for the MFS services with the Tigo Mobile Operators in Latin-America and Africa. Integration is done via a central Tigo Secure Server hosted on Apigee. This centralized server takes care of access control, routing, requests to the corresponding Tigo operation and most importantly the secure handling of data. All communication on all the interfaces is encrypted. Partner Operators Tigo Secure Server SSL IP Whitelisting Mutal SSL IP Whitelisting Figure 3-1: Architecture overview Millicom Tigo Secure is hosted on Apigee in a minimum of two datacenters. This mission critical platform has up to 99.99% availability. The cloud environment provides load-balancing and failover across the multiple server instances. All the provided services are exposed to use JSON. Two main URIs are provided for integration: https://securesandbox.tigo.com/ test environment https://secure.tigo.com/ production environment All communication with the Tigo Secure Server use HTTPS / SSL to exchange information. The Payment Authorization solution is established via one-way SSL. The international remittance deposit money service requires two-way SSL and IP whitelisting. 3.2. Integration steps The following steps have to be carried out in order to integrate successfully with the Millicom Tigo Secure environment and the Mobile Financial Services: 1. Register with Millicom Tigo 2. Acquire an Apigee API Key and secret 3. Exchange SSL certificates for 2-way SSL 4. Make sure that MFS Accounts have been created in the respective countries and that account numbers and pin codes are known 3 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 8 Global Mobile Financial Services Partner Developer’s Guide 5. Submit the IP address of the server(s) that will connect with Tigo Secure in order to whitelist 3.3. Partner Mobile Accounts For each Millicom Tigo operation with which a partner will integrate a separate MFS Account (also called mobile wallet) has to be opened. Each account is uniquely identified with either a MSISDN or username and a PIN code. For each service call interacting with the MFS Account the correct account details have to be provided in the request for the designated country. Opening an account the exact process depends on the country and in general involves the following steps: Signed NDA Company to provide KYC details o Differs from country to country but high level is: o Business Name o Business License o Tax Identification Number o Stated Capital o Contact person(s) details & ID Bank account details of account in local bank Depending on the use cases and the functionality/product launched these can be broadly classified into 2 kinds of accounts: 1. Pre-Funded Account 2. Collection Account 1. Pre-funded account– This type of account is provided in case of integrations where the partner is required to have virtual money (e-money/local MFS currency) in advance to make transfers into the end users wallets. The local process of procuring this MFS currency (e-money) differs per operation but it usually involves depositing actual money in the local currency into the bank account designated by the Tigo operation and getting a mirror value replicated in the MFS platform (as e-money or MFS currency). Typical products and functionalities using this type of account are Disbursements, Remittance transfers, Transfers. The settlement process is usually agreed between both entities that governs the management of the e-money and real money 2. Collection Account– This type of account is provided in cases where the partner is required to collect or accumulate transfers into their accounts. The end user that has a valid account would be able to transfer e-money/MFS currency into the partner account for the intention of making payments, transfers, purchases etc. 4 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 9 Global Mobile Financial Services Partner Developer’s Guide Typical products and functionalities using this type of account are: Merchant Payments, Bill payments, transfers, goods purchases. As confirmed before the settlement process defined governs the movements and transfer between the collection account and the partner’s bank account. 3.4. Session Access Token For each session a valid Access Token has to be requested via the GenerateAccessToken service (see section 4.3) using the API key and secret. This Access Token has a limited validity period. After completing a session (either successful or unsuccessful) the access token will be invalidated. The process is shown in the next sections. Warning: You should never authenticate using the API Key and Secret directly from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. [Source: Apigee] 3.5. System Status heartbeat signal 3.6. International Remittance Money Deposit The system status is monitored by sending a periodic request to the Tigo Secure server. In the response the status is reported of each of the Tigo operations. A lack of response will mean the service is down caused by a network error or other failure. These events should be logged and alerted on to Tigo in order to be restored to normal operation. The process to deposit money for international remittance is shown in Figure 3-2 below. (1,2) An Access token has to be requested for the Tigo Secure Server via the GenerateAccessToken service (section 4.3) using the Apigee API Key and secret. (3-6) The next optional step is to Validate the MFS Account via the ValidateMFSAccount service (section 4.6.1). In case no validation is done and the receiving Tigo subscriber does not have an MFS account then the next step to actually deposit the remittance will fail in which case an (optional) text message is sent suggesting the subscriber to sign up of an MFS account. 5 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 10 Global Mobile Financial Services Partner Developer’s Guide Figure 3-2: International Remittance flow (7-10) the Remittance Partner can deposit the amount in the local currency via the DepositRemittance service (section 4.7.1). (11) The receiving Tigo subscriber will receive a text message in case this is specified in the request. This text message will be generated in the following two scenarios: Successful deposit a text message informing the subscriber that an international remittance has been received with the amount, name of the remittance partner and optionally the name of the sender (if provided in the request) Unsuccessful remittance cause by the receiving subscriber not having a MFS wallet a text message informing the subscriber that an international remittance was missed with the amount, name of the remittance partner, optionally the name of the sender (if provided in the request) - and the advice to open a Tigo MFS account The Access Token is invalidated after the expiry time as specified in the Generate Access Token Response (section 4.3.2). 6 Global Mobile Financial Services Partner Developer’s Guide 3.7. Millicom International Cellular SA 11 Global Mobile Financial Services Partner Developer’s Guide Payment Authorization The Payment Authorization service is based on a URI redirect whereby the actual payment verification and authentication by subscriber is entirely handled on the Tigo Secure server. The next sections show the flows of the payment authorization where the verification is done via SMS in case of the Africa region and via USSD push for LATAM. The initial language of the Tigo Secure webpages shown is set via the language parameter in the request. It is preferable to keep the language the same as the page from which the customer is redirected. The customer has the option to select a different language on the webpage itself as well. 3.7.1. Payment Authorization via SMS verification code In the following countries the payment is authorization by sending a verification code via text message to the subscriber: Senegal Tanzania This verification code is only valid for a limit duration of 1 minute and has to be filled in by the Customer on the Tigo Secure webpage. Besides this verification code the customer also has to provide their MFS PIN code. The flow is shown below. 7 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 12 Global Mobile Financial Services Partner Developer’s Guide Figure 3-3: Payment Authorization flow SMS OTP (1) The subscriber/customer initiates a Tigo MFS payment via the Merchant. (4-8) The Payment Authorization Request is made with the necessary payment details (Section 4.5.1) this will return a re-direct URL to the Tigo Secure Payment Authorization page to which the customer has to be redirected. (2-3) 8 An Access token is requested for the Tigo Secure Server via the GenerateAccessToken service (Section 4.3.1) using the Apigee API Key and secret. Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 13 Global Mobile Financial Services Partner Developer’s Guide (9) In case the MSISDN is not yet specified in the Payment Authorization request or in case the MSISDN was incorrect (nonexistent) then the Customer is redirected to a page to enter the MSISDN. Figure 3-4: Enter verification code page (10-14) The MFS Account of the subscriber is validated after which the ‘Verify’ Page is shown. (see Figure 3-5) and a One-TimePin (Verification code) is sent via text message to the Tigo subscriber. Figure 3-5: Enter verification code page (15 - 16) The subscriber submits the verification code and after successful verification of the code the payment overview is shown to the customer requesting the Tigo MFS Account PIN (Figure 3-6). Figure 3-6: Payment overview page 9 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 14 Global Mobile Financial Services Partner Developer’s Guide (17-19) (20) The customer provides the MFS PIN and the purchase call to make the payment is sent. Upon receipt of a successful purchase response the access token is invalidated and a payment result page is shown for a limited duration (Figure 3-7). Figure 3-7:Payment result page (21) (22) An optional callback URI is called with the final transaction status. This callback URI can be used in case the front-end server does not allow processing the financial transaction status. The final redirect is done to the specified redirect URI. The non-nominal cases for the Payment Authorization using SMS verification are shown below Invalid Verification Code When the subscriber enters the incorrect verification code a warning is shown “Invalid Verification Code. Please re enter” with the possibility to try again. The number of attempts is limited by the expiry time of the verification code. Figure 3-8: Invalid Verification Code 10 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 15 Global Mobile Financial Services Partner Developer’s Guide Verification Code expired In case the verification code expires a warning is shown “The code has now expired. Please make sure you have the phone at hand and click below to resend the code.” with the option to resend a verification code. Resending the verification code is limited to 3 times. Figure 3-9: verification code expired Incorrect PIN code In case the subscriber enters an incorrect PIN code a warning is displayed “PIN was not valid. Please enter the PIN again.” The subscriber has three attempts to re-try. After that the subscriber account will get blocked. Figure 3-10: incorrect PIN code 3.7.2. Payment Authorization via USSD Push In the following countries the payment is authorization via a USSD menu Bolivia El Salvador Honduras Paraguay This USSD menu is pushed to the customer’s mobile phone and requests to validate the transaction by sending the Tigo MFS PIN code. The flow is shown below: 11 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 16 Global Mobile Financial Services Partner Developer’s Guide Figure 3-11: Payment Authorization flow USSD Push (1) The subscriber/customer initiates a Tigo MFS payment via the Merchant. (4-7) The Payment Authorization Request is made with the necessary payment details (Section 4.5.1) this will return a re-direct URL to the Tigo Secure Payment Authorization page to which the customer has to be redirected. The payment details page is shown in Figure 3-13. (2-3) An Access token is requested for the Tigo Secure Server via the GenerateAccessToken service (Section 4.3.1) using the Apigee API Key and secret. Figure 3-12: Payment details 12 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 17 Global Mobile Financial Services Partner Developer’s Guide (8-10) The Customer submits the MISISDN and presses ‘Confirm’ to continue the transaction. A Purchase request is made which initiates a USSD session in which the Subscriber has to authorize the payment. The maximum duration is 5 minutes. Figure 3-13: Pending Payment confirmation via USSD (11-13) The Customer authorizes the payment via USSD and the transaction status page is shown for limited duration. Figure 3-14:Payment result page (14) (15) 3.8. An optional callback URI is called with the final transaction status. This callback URI can be used in case the front-end server does not allow processing the financial transaction status. The final redirect is done to the specified redirect URI. Reverse Transaction The Reverse Transaction Service can be used to reverse or refund a successful transaction made via the Online Payment. 13 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 18 Global Mobile Financial Services Partner Developer’s Guide Figure 3-15: Reverse Transaction flow 14 Global Mobile Financial Services Partner Developer’s Guide 4. API Specification 4.2. Introduction This section covers the API specifications. Each service is divided in a Request and Response section containing the overview of the parameters and example requests and responses. The list of error codes is included in Annex A.6.4. The following third-level domains are available for the Tigo Secure services: https://securesandbox.tigo.com/ test environment https://secure.tigo.com/ production environment In the sections below the service URLs are relative to these two Tigo Secure domains. For example for a service called ‘service1’ the following URL is specified in the API specification: /v1/service1 To use service1 on the test environment use the URL: https://securesandbox.tigo.com/v1/service1 4.3. and on the production environment: https://secure.tigo.com/v1/service1 Generate Access Token Service The Generate Access Token service is used to get a valid access token. The Millicom partner can only use the assigned API services via this access token. The access token has to be specified in each request header as described in the sub paragraphs below. The validity of the access token is time limited and after each session the token is invalidated irrespective whether the service call resulted in a positive result or a failure. The expiry time is specified in the response. 4.3.1. Request Generate Access Token Request URL /v1/oauth/generate/accesstoken?grant_type=client_credentials Method POST Headers Content-Type: application/x-www-form-urlencoded Body client_id= &client_secret= with in the body: is the unique client identifier as assigned during the registration process with Millicom is the secret/password as provided during the registration process with Millicom 15 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 20 Global Mobile Financial Services Partner Developer’s Guide 4.3.2. Response Average response time: < 1 second Maximum response time: 5 seconds In case as valid client_id and client_secret are submitted the following response is returned: HTTP response code: 200 OK JSON response body: Parameter accessToken issuedAt expiresIn Type String Integer Integer Description unique access token Access Token issue Date and time as Unix time Expiry time in seconds Table 1: Generate Access Token Response parameters Example response: Response code: 200 OK Response body: { } "accessToken": " ABcdef123456ABcdef123456ABcd", "issuedAt": "1410268728383", "expiresIn": "599", In case incorrect client_id or client_secret are provided the following error is returned: HTTP response code: 401 Unauthorized JSON response body: Parameter ErrorCode Error Type String String Description Error code Error description Example response: Response code: 401 Unauthorized Response body: { } 4.4. "ErrorCode" : "invalid_client", "Error" :"Client credentials are invalid" System Status Service The System Status Service is provided to monitor the health of the service periodically (heartbeat signal). The service returns the status of both the network connectivity and the application status to the Tigo Secure server and from the Tigo Secure Server to the Tigo Operations. 16 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 21 Global Mobile Financial Services Partner Developer’s Guide 4.4.1. Request System Status Request URL /v1/tigo/systemstatus Method GET Header accessToken 4.4.2. Response Average response time: Maximum response time: < 1 second 5 seconds HTTP response code: 200 OK JSON Response body: Parameter # tigoSecureStatusCode 1 Type Integer statusDescription TigoOperationStatus country 1 0..n 1 String 1 String code description 1 String Integer Table 2: System Status Response parameters Example response: { } 4.5. Description Tigo Secure Server status code 0 = OK Any other number than 0 indicates a problem occurred Description Three letter country code (ISO 3166-1 Annex A.2) Tigo Secure Server status code 0 = OK Any other number than 0 indicates a problem occurred Description "tigoSecureStatusCode" : 0, "statusDescription" : "OK", "TigoOperationStatus" : { {"country":"TZA", "code":0, "description":"OK"} {"country":"SEN", "code":0, "description":"OK"} } Payment Authorization service 4.5.1. Request For the Tigo Secure Online Payment Authorization a redirect to the following URL has to be done including a JSON request with the required payment details: Payment Authorization Request URL /v1/tigo/payment-auth/authorize Method POST Header Content-Type application/json accessToken 17 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 22 Global Mobile Financial Services Partner Developer’s Guide JSON Request body: Parameter MasterMerchant account # 1 1 Merchant reference 0..1 1 pin id fee 1 1 0..1 Description String MFS Account number in the destination country (account to credit) MFS Account PIN code Identifier of master merchant (i.e. company name) as provided by Millicom [optional] Reference of the originating merchant (company name) in case the payment was made on behalf of another company Merchant fee for the transaction in the origin currency. This fee is charged from the merchant. Information about this fee will not be communicated to the subscriber. This information is confidential and is to be used for reconciliation Currency code of the Merchant fee (see Annex A.1) String String String Decimal currencyCode 0..1 Subscriber 1 account 1 String firstName lastName emailId redirectUri String String String String countryCode country callbackUri language terminalId originPayment amount 1 1 0..1 0..1 0..1 1 0..1 1 0..1 1 1 currencyCode 1 tax 1 fee 1 String String String String String String Decimal String Decimal Decimal exchangeRate 0..1 Decimal LocalPayment amount 1 1 Decimal transactionRefId 1 String currencyCode 1 18 Type String MFS Account number (msisdn) of the paying subscriber (account to debit) Country code dialing prefix (annex A.4) Three letter country code (ISO 3166-1 Annex A.2) First name of the subscriber Last name of the subscriber [optional] Email address Redirection URI to redirect after completing the payment [optional] Result callback URI Three letter code for the language (ISO 639-3 see Annex A.3) [optional] Terminal ID Total amount in the currency of the original merchant payment Currency code of the payment (see Annex A.1) Tax for the transaction in the origin currency Fee applied by the Master Merchant for the transaction in the origin currency. This fee is charged from the subscriber and will be shown to the subscriber. If no fee has been applied the field can be set to 0 [optional] Exchange rate between the origin currency (currency of the sending country) and local currency (currency of the receiving country) Total amount in the local currency of the paying subscriber Currency code of the MFS account of the paying subscriber (local currency)(see Annex A.1) Reference Identifier in order to uniquely identify the transaction. Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 23 Global Mobile Financial Services Partner Developer’s Guide Table 3: Payment Authorization Request parameters Sample Request: { } "MasterMerchant": { "account":"255321321321", "pin":"1234", "id":"CompanyName" }, "Merchant": { "reference":"Amazon", "fee":"23.45", "currencyCode":"EUR" }, "Subscriber": { "account":"255111111111", "countryCode": "255", "country":"tza", "firstName":"John", "lastName":"Doe", "emailId" : "johndoe@mail.com" }, "redirectUri":"https://someapp.com/payment/redirecturi", "callbackUri":"https://someapp.com/payment/statuscallback", "language":"eng", "terminalId":"", "originPayment": { "amount":"75.00", "currencyCode":"USD", "tax":"0.00", "fee":"25.00" } "exchangeRate":"2182.23", "LocalPayment": { "amount":"218223.00", "currencyCode":"TZS" }, "transactionRefId":"0a1e39ab" Make sure to use the Access Token only once to initiate a Payment Authorization. For each Payment Authorization request a new access token has to be generated. This is because the access token is invalidated after the transaction completed. Any other additional transaction initiated with the same access token will therefore fail. Per Payment Authorization make sure to use a unique transaction reference identifier (transactionRefId) to identify the transaction. This will guarantee that the transaction is logged and traced correctly. 19 Global Mobile Financial Services Millicom International Cellular SA s24Guide Partner Developer’ Global Mobile Financial Services Partner Developer’s Guide 4.5.2. Response Average response time: < 1 second Maximum response time: 5 seconds HTTP response code: 200 OK JSON Response body: Parameter transactionRefId redirectUrl # 1 1 Type String String authCode 1 String creationDateTime 1 String Description Unique reference Identifier of the transaction Tigo Secure redirect URL which has to be used to redirect the Customer to the correct Tigo Secure Payment Authorization webpage Unique code to authenticate the transaction for the customer when redirecting Transaction Creation Date and Time Table 4: Payment Authorization Response parameters Example response: { "transactionRefId":"0a1e39ab", "redirectUrl":" https://securesandbox.tigo.com/v1/payment_auth/transactions?… auth_code=123123123&transaction_ref_id=0a1e39ab&lang=eng", "authCode" : "123123123", "creationDateTime":"Fri, 10 Oct 2014 13:58:25 UTC" } 4.5.3. Payment status callback After the customer completes the payment via Tigo Secure the status is reported back. This is done via the optional callback URI or – in case this callback URI has not been specified – in the redirect URI as specified in the Payment Authorization Request. The optional callback URI will be called reporting back the transaction status with the following parameters: Payment status Callback Method POST Headers Content-Type: application/x-www-form-urlencoded Body trans_status= &… transaction_ref_Id= &... external_ref_id= &… mfs_id= &… verification_code= &… error_code= Parameter trans_status transaction_ref_id external_ref_id 20 Description Transaction status: success for a successful transaction fail in case of a failed transaction Transaction Reference Identifier as specified in the request [optional] Tigo transaction Id of the request and Global Mobile Financial Services Partner Developer’s Guide mfs_id verification_code error_code Millicom International Cellular SA 25 Global Mobile Financial Services Partner Developer’s Guide responses between the internal servers. This will only be sent back in case of a successful payment [optional] MFS Platform transaction id of the payment. This will only be sent back in case of a successful payment [optional] The verification code is the invalidated Access Token as generated at the start of the payment authorization flow. This code has to be used to uniquely identify that payment status is reported back by Tigo Secure. Note that this access token is invalided after the transaction failed/succeeded/expired so it can’t be reused. The verification code (Access Token) will be omitted in case the transaction failed. This is to prevent that a malicious callback can be done with a modified transaction status. [optional] The error code in case the transaction failed. The error codes are defined in Annex A.6.4.1. Table 5: Payment status callback parameters Successful payment callback example: POST HTTP/1.1 Host: Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache trans_status=success&transaction_ref_id=0a1e39ab &external_ref_id=38c1069f-2497-4f9c9&mfs_id=CO140924.1414.A00113&verification_code=pfCIHgyWWg6qsUIOVFS u2HR3F4jy&lang=eng 21 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 26 Global Mobile Financial Services Partner Developer’s Guide The verification code in the status callback is the invalidated Access Token as generated at the start of the payment transaction. In order to confirm that successful payment status has been reported back by Tigo Secure the following steps have to be performed: 1. Lookup the payment transaction using the transaction_ref_id 2. Compare the verification_code against the original access token as used during the transaction 3. Only when the verification_code is equal to the original access token can the payment be treated as successful. In case of a mismatch between the verification code and the access token the transaction should be treated as failed and reported back to Millicom. The external_ref_id and transaction_id can be used for traceability of the transaction within the Millicom Tigo Operation. Failed payment example: POST HTTP/1.1 Host: Content-Type: application/x-www-form-urlencoded Cache-Control: no-cache trans_status=fail&transaction_ref_id=0a1e39ab-d0ec-4f8b-9746b2c4122220b2123&error_code= purchase-3008-30434-E> For a failed transaction the verification code (access token) is not reported back. This is to prevent a malicious callback with a modified transaction status. After the payment status callback a HTTP redirect will be done to the URI as specified in the redirectUri parameter in the Payment Authorization Request without any extra parameters. Note that in case no callbackUri was specified in the original request the payment status is reported back in the redirectUri in the manner as for the callback URI explained above. 22 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 27 Global Mobile Financial Services Partner Developer’s Guide 4.6. Validate MFS Account Service The Validate MFS Account Service can be used to check whether the subscriber has a valid MFS account in the designated country. The request requires the subscriber MSISDN, first name and last name and country code as shown below. 4.6.1. Request Validate MFS Account Request URL /v1/tigo/mfs/validateMFSAccount Method POST Header Content-Type application/json accessToken JSON Request body: Parameter transactionRefId ReceivingSubscriber account countryCallingCode countryCode firstName lastName Cardinality Type 1 String 1 1 1 1 0..1 0..1 String Description Reference Identifier in order to uniquely identify the transaction MFS Account to validate of the receiving subscriber Integer County Calling code String Three letter country code (ISO 3166-1) String [optional] First name of the subscriber String [optional] Last name of the subscriber Table 6: Validate MFS Account Request parameters Example request: { } "transactionRefId" : "1300074238", "ReceivingSubscriber" : { "account" : "255658123964", "countryCallingCode" : "255", "countryCode" : "TZA", "firstName" : "John", "lastName" : "Doe" } 23 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 28 Global Mobile Financial Services Partner Developer’s Guide 4.6.2. Response Average response time: 3 seconds Maximum response time: 5 seconds HTTP response code: 200 OK JSON response body: Parameter Type ValidateMFSAccountResponse ResponseHeader GeneralResponse correlationID String status String description ResponseBody validMFSAccount String code String String Description The is the transaction id as sent in the request Status of executing the account validation request (OK, ERROR) Status code of the account validation (see Annex A.6.4) Technical and brief description of the result MFS account validation status true = account valid for provided details Table 7: Validate MFS Account Reponse parameters The following response is returned for a valid MFS account: HTTP response code: 200 OK JSON response body: { } "ValidateMFSAccountResponse": { "ResponseHeader": { "GeneralResponse": { "correlationID":1234, "status":"OK", "code":"Validatemfsaccount-3018-0000-S", "description":"Provided MSISDN is a valid MFSAccount." } }, "ResponseBody": { "validMFSAccount":"true" } } In case of an invalid (non-existent) MFS account the follow response is returned: 24 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 29 Global Mobile Financial Services Partner Developer’s Guide HTTP response code: 500 Internal Server Error JSON response body: { "Fault": { "faultcode": "env:Server", "faultstring": "Subscriber not found.", "detail": { "ValidateMFSAccountFault": { "ResponseHeader": { "GeneralResponse": { "correlationID": 1300074238, "status": "ERROR", "code": "Validatemfsaccount-3018-3001-E", "description": "Subscriber not found." } } } } 4.7. Deposit Remittance Service With the Deposit Remittance Service the money for the international remittance in deposited in the subscriber’s wallet. The partner wallet is debited and the subscriber wallet is credited for the amount in the local currency as specified in the request. The response will confirm success of failure of the money deposit which includes a unique Transaction ID from the MFS platform. 4.7.1. Request Deposit Remittance Request URL /v1/tigo/mfs/depositRemittance Method POST Header Content-Type application/json accessToken JSON request body: Parameter transactionRefId PaymentAggregator account # 1 1 1 Sender firstName 0..1 1 pin id lastName msisdn emailAddress 1 1 1 0..1 0..1 Type String String String String String String String String Description Unique Transaction Reference Identifier MFS Account number in the destination country MFS Account PIN code Identifier of the payment aggregator (i.e. company name as provided by Millicom [optional] First name of the Sender. This field can be left blank in case the information is not available. Last name of the Sender. This field can be left blank in case the information is not available. [optional] MSISDN of the Sender [optional] e-mail address of the Sender 25 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 30 Global Mobile Financial Services Partner Developer’s Guide Parameter ReceivingSubscriber account countryCallingCode countryCode firstName lastName OriginPayment amount currencyCode tax fee exchangeRate # 1 1 0..1 1 1 1 0..1 1 1 1 1 0..1 Type Description String Integer String MFS Account of the receiving subscriber [optional] Country Calling code Three letter country code (ISO 3166-1 Annex A.2) First name of the subscriber Last name of the subscriber [optional] Total amount in the currency of the sending country Currency code of the sending country (see Annex A.1) Tax for the transaction in the origin currency Fee for the transaction in the origin currency [optional] Exchange rate between the origin currency (currency of the sending country) and local currency (currency of the receiving country) [optional] Verification flag (true/false). This feature is currently not supported. Only set to false otherwise the transaction will fail [optional] Flag to indicate whether a text message has to be sent (sendTextMessage = true) to the receiving subscriber in the following cases: Successful deposit: informing the subscriber received an international remittance with the amount, remittance partner and optionally the name of the sender. Unsuccessful deposit cause by the subscriber not signed up for a MFS account: informing the subscriber an international remittance was missed with the amount, remittance partner and optionally the name of the sender and the suggestion to open an MFS account. String String Decimal String Decimal Decimal Decimal verificationRequest 0..1 Boolean sendTextMessage 0..1 Boolean LocalPayment amount 1 1 Decimal 1 String currencyCode Table 8: Deposit Remittance Request parameters 26 Total amount to payout in the local currency of the receiving subscriber (see Annex A.5 for formatting) Currency code of the receiving country (see Annex A.1) Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 31 Global Mobile Financial Services Partner Developer’s Guide Example Deposit Remittance Request { } } "transactionRefId" : "1300074238", "PaymentAggregator" : { "account" : "255123123123", "pin" : "1234", "id" : "Company Name" }, "Sender" : { "firstName" : "Jane", "lastName" : "Doe", "msisdn" : "2551234123423", "emailAddress" : "janedoe@mail.com"}, "ReceivingSubscriber" : { "account" : "255111111111", "countryCallingCode": "255", "countryCode" : "TZA", "firstName" : "John", "lastName" : "Doe" }, "OriginPayment" : { "amount" : "100.00", "currencyCode" : "EUR", "tax" : "10.00", "fee" : "25.00" }, "exchangeRate" : "2182.23", "verificationRequest" : "true", "sendTextMessage" : "true", "LocalPayment" : { "amount" : "200", "currencyCode" : "TZS" 4.7.2. Response Average response time: 3 seconds Maximum response time: 5 seconds HTTP response code: 200 OK JSON response body: Parameter DepositRemittanceResponse ResponseHeader GeneralResponse correlationID Type Description String code String The is the transaction id as sent in the request Status of executing the account validation request (OK, ERROR) Status code of the account validation (see codes below) Technical and brief description of the result status description ResponseBody transactionId String String String Transaction Identifier from the MFS Platform Table 9: Deposit Remittance Response parameters 27 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 32 Global Mobile Financial Services Partner Developer’s Guide Example Response { "DepositRemittanceResponse": { "ResponseHeader": { "GeneralResponse": { "correlationID":1300074238, "status":"OK", "code":"depositremittance-3017-0000-S", "description":"The Transaction is completed successfully." } }, "ResponseBody": { "transactionId":"CO140912.1700.A00059" } } } 4.8. Reverse Transaction service 4.8.1. Request Reverse Transaction Request URL /v1/tigo/mfs/reverseTransaction Method POST Header accessToken JSON request body: Parameter MasterAccount account pin id transactionRefId Type Description String 1 1 String String 1 String The MFS account of the Master Merchant / Payment Aggregator as used in the original request Payment Request or Deposit Remittance API request MFS Account PIN code for the Master Account Identifier of Master Merchant (i.e. company name) as provided by Millicom Transaction Reference Identifier as submitted in the request (transactionRefId) The MFS Transaction Identifier for the transaction this maps to the Payment Authorization status callback mfs_id value or the DepositRemittanceResponse mfsTransactionId 1 countryCode 1 subscriberAccount 28 # 1 1 0..1 String String String transactionId Three letter country code (ISO 3166-1 Annex A.2) MFS Account of the subscriber (MSISDN) either the paying Subscriber for the Payment Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 33 Global Mobile Financial Services Partner Developer’s Guide Parameter # Type LocalPayment amount 0..1 1 Decimal currencyCode 1 String Description Authorization or [optional] Total amount of the transaction in the local currency (see Annex A.5 for the formatting) Currency code of the Tigo country (see Annex A.1) Table 10: Reverse Transaction Request parameters Example request: { } "MasterAccount" : { "account" : "255321321321", "pin" : "1234", "id" : "CompanyName" }, "transactionRefId" : "0a1e39ab", "mfsTransactionId" : "CO140924.1414.A00113", "countryCode" : "tza", "subscriberAccount" : "255111111111", "LocalPayment" : { "amount" : " 218223.00", "currencyCode" :"TZS" } 4.8.2. Response 29 Global Mobile Financial Services Millicom International Cellular SA 34 Partner Developer’s Guide Global Mobile Financial Services Partner Developer’s Guide 4.9. Payment Authorization Transaction Status service 4.9.1. Request Get Transaction Status Request URL /v1/payment-auth/transactions/ < transactionRefId > Method GET Header accessToken with the MasterMerchant Identifier and transaction reference ID as specified in the Payment Authorization Request. For example when the below values were provided in the original Payment Authorization Request (Section 4.5.1): "MasterMerchant": { … "id":"Company Name" … "transactionRefId":"0a1e39ab" The example request to retrieve the payment authorization transaction status will be in that case: GET /v1/payment-auth/transactions/Company Name0a1e39ab HTTP/1.1 Host: accessToken: Cache-Control: no-cache 4.9.2. Response Average response time: < 1 second Maximum response time: 5 seconds HTTP response code: 200 OK JSON response body: Parameter Transaction refId # Type Description 1 String mfsId 0..1 String createdOn 1 String Unique Transaction Reference Identifier as provided in the initial request [optional] Tigo transaction Id of the request and responses between the internal servers. This will only be returned for successful transactions [optional] MFS Platform transaction id of the payment. This will only be returned for successful transactions Creation date and time of the transaction externalRefId 30 0..1 String Global Mobile Financial Services Partner Developer’s Guide Parameter Millicom International Cellular SA 35 Global Mobile Financial Services Partner Developer’s Guide # Type Status 1 String completedOn 1 MasterMerchant account 1 1 String Merchant reference 0..1 1 String id 1 String fee 1 Decimal Subscriber account 1 1 String currencyCode countryCode country firstName lastName emailId redirectUri callbackUri language terminalId OriginPayment Amount currencyCode tax fee exchangeRate LocalPayment amount 1 1 1 1 1 0..1 1 0..1 1 0..1 1 1 1 1 1 0..1 1 1 String String String String String String String String String String Decimal String Decimal Decimal Decimal Decimal Description in the following format: Fri, 10 Oct 2014 13:58:25 UTC Transaction status: Success Fail Completion date and time of the transaction in the following format: Fri, 10 Oct 2014 13:58:54 UTC MFS Account number in the destination country (account to credit) Identifier of master merchant (i.e. company name) [optional] Reference of the originating merchant (company name) in case the payment was made on behalf of another company Merchant fee for the transaction in the origin currency Currency code of the Merchant fee (see Annex A.1) MFS Account number (msisdn) of the paying subscriber (account to debit). Country code dialing prefix Three letter country code (ISO 3166-1 Annex A.2) First name of the subscriber Last name of the subscriber [optional] Email address Redirection URI to redirect after completing the payment [optional] Result callback URI Three letter code for the language (ISO 639-3 see Annex 0) [optional] Terminal ID Total amount in the currency of the sending country Currency code of the payment (see Annex A.1) Tax for the transaction in the origin currency Fee applied by the Master Merchant for the transaction in the origin currency [optional] Exchange rate between the origin currency (currency of the sending country) and local currency (currency of the receiving country) Total amount in the local currency of the paying subscriber 31 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 36 Global Mobile Financial Services Partner Developer’s Guide Parameter currencyCode # 1 Type String Description Currency code of the sending country (see Annex A.1) Table 11: Payment Authorization Transaction Status Response parameters Sample Payment Authorization Transaction Status response: { } 32 "Transaction" : { "refId":"0a1e39ab-d0ec-4f8b-9746-b2c4122220b2c120ww40", "externalRefId" : "38c1069f-2497-4f9c-9", "mfsId" : "CO140924.1414.A00113", "createdOn" : "Fri, 10 Oct 2014 13:58:25 UTC", "status" : "success", "completedOn" : "Fri, 10 Oct 2014 13:58:31 UTC", }, "MasterMerchant": { "account":"255321321321", "id":"Skrill Ltd" }, "Merchant": { "reference":"Acme,Inc", "fee":"23.45", "currencyCode":"TZS", } "Subscriber":{ "account":"255111111111", "countryCode": "255", "country":"tza", "firstName":"John", "lastName":"Doe", "emailId" : "johndoe@mail.com" }, "redirectUri":"https://someapp.com/payment/redirecturi", "callbackUri":" https://someapp.com/payment/statuscallback", "language":"eng", "terminalId":"", "originPayment": { "amount":"75.00", "currencyCode":"USD", "tax":"0.00", "fee":"25.00" }, "exchangeRate":"2182.23", "LocalPayment": { "amount":"218223.00", "currencyCode":"TZS" } Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 37 Global Mobile Financial Services Partner Developer’s Guide 4.10. Deposit Remittance Transaction Status service 4.10.1. Request Get Deposit Remittance Transaction Status Request URL /v1/tigo/mfs/depositRemittance/transactions/ Method GET Header accessToken with < PaymentAggregator ID>< Transaction ID> the Payment Aggregator Identifier and transaction reference ID as specified in the Deposit Remittance Request. For example when the below values were provided in the original Payment Authorization Request (Section 4.5.1): { … "transactionRefId" : "1300074", "PaymentAggregator" : { "id" : "Company Name" … Example request: GET /v1/tigo/mfs/depositRemittance/transactions/Company Name1300074 HTTP/1.1 Host: accessToken: Cache-Control: no-cache 4.10.2. Response Average response time: < 1 second Maximum response time: 3 seconds HTTP response code: 200 OK JSON response body: Parameter Transaction refId status mfsId errorCode PaymentAggregator account id # 1 1 1 0..1 1 1 1 Type Description String Unique Transaction Reference Identifier as provided in the initial request Transaction status success/ fail MFS Platform transaction id of the payment Error code in case of a failed transaction String String String String MFS Account number in the destination country Identifier of the payment aggregator (i.e. company name 33 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 38 Global Mobile Financial Services Partner Developer’s Guide Sender firstName lastName msisdn emailAddress ReceivingSubscriber account countryCallingCode countryCode 0..1 1 1 0..1 0..1 1 1 0..1 1 OriginPayment amount 0..1 1 firstName lastName currencyCode tax fee exchangeRate verificationRequest sendTextMessage localPayment amount currencyCode 1 1 1 1 1 0..1 0..1 0..1 1 1 1 String String String String String Integer String String String Decimal String Decimal Decimal Decimal Boolean Boolean Decimal String First name of the Sender Last name of the Sender [optional] MSISDN of the Sender [optional] e-mail address of the Sender MFS Account of the receiving subscriber [optional] Country Calling code Three letter country code (ISO 3166-1 Annex A.2) First name of the subscriber Last name of the subscriber [optional] Total amount in the currency of the sending country Currency code of the sending country (see Annex A.1) Tax for the transaction in the origin currency Fee for the transaction in the origin currency [optional] Exchange rate origin payment currency and local payment currency [optional] currently not used [optional] Flag to send text message after complete the transaction Total amount to payout in the local currency of the receiving subscriber Currency code of the receiving country (see Annex A.1) Table 12: Deposit Remittance Transaction Status Response parameters 34 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 39 Global Mobile Financial Services Partner Developer’s Guide Example Response: { } "Transaction": { "refId": "1300074239", "status": "success", "mfsId": "CI141127.2125.A03951" }, "PaymentAggregator" : { "account" : "255123123123", "id" : "CompanyName" }, "Sender" : { "firstName" : "Jane", "lastName" : "Doe", "msisdn" : "441512121212", "emailAddress" : "janedoe@mail.com" }, "ReceivingSubscriber" : { "account" : "255111111111", "countryCallingCode" : "255", "countryCode" : "TZA", "firstName" : "John", "lastName" : "Doe" }, "OriginPayment" : { "amount" : "100.00", "currencyCode" : "EUR", "tax" : "10.00", "fee" : "25.00" }, " exchangeRate" : "2182.23", "verificationRequest" : "false", "sendTextMessage" : "true", "localPayment" : { "amount" : "5555", "currencyCode" : "TZS" } 35 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 40 Global Mobile Financial Services Partner Developer’s Guide A. Appendices A.1. Currency Codes The Millicom supported currency codes are according to the ISO 4217 standard. Table 13: Currency codes Code BOB CDF COP EUR GHS GTQ PYG RWF TZS USD XAF XOF 36 Currency Boliviano Congolese franc Colombian peso Euro Ghanaian cedi Guatemalan quetzal Paraguayan guaraní Rwandan franc Tanzanian shilling United States dollar CFA franc BEAC CFA Franc Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 41 Global Mobile Financial Services Partner Developer’s Guide A.2. Country Codes The Millicom supported country codes are according to the ISO 3166-1 alpha-3 standard. Table 14: Country letter codes Code BOL COD COL GHA GTM HND PRY RWA SEN SLV TCD TZA Country Bolivia, Plurinational State of Congo, the Democratic Republic of the Colombia Ghana Guatemala Honduras Paraguay Rwanda Senegal El Salvador Chad Tanzania, United Republic of 37 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 42 Global Mobile Financial Services Partner Developer’s Guide A.3. Language Codes The Millicom supported language codes are according to the ISO 639-3 standard. Table 15: Language codes Code ara aym cab emk eng fra ful grn jod jud kfo kga kin lin lua miq mku msc mxx mzj que snk spa srr swa wol 38 Language Arabic Aymara Garifuna Eastern Maninkakan English French Fulah Guarani Wojenaka Worodougou Koro (Côte d'Ivoire) Koyaga Kinyarwanda Lingala Luba-Lulua Mískito Konyanka Maninka Sankaran Maninka Mahou Manya Quechua Soninke Spanish Serer Swahili (macrolanguage) Wolof Global Mobile Financial Services Partner Developer’s Guide A.4. Millicom International Cellular SA 43 Global Mobile Financial Services Partner Developer’s Guide Country Calling Codes Table 16: Country Calling Codes Country Bolivia, Plurinational State of Congo, the Democratic Republic of the Colombia Ghana Guatemala Honduras Paraguay Rwanda Senegal El Salvador Chad Tanzania, United Republic of Calling code 591 243 57 233 502 504 595 250 221 503 235 255 39 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 44 Global Mobile Financial Services Partner Developer’s Guide A.5. Amount Format Convention The amounts in the API requests are formatted according to the following standard: ######.## Whereby . (dot) will be used as the separator character for decimals (cents). No separator character is required (allowed) for thousands. 40 Global Mobile Financial Services Partner Developer’s Guide A.6. Millicom International Cellular SA 45 Global Mobile Financial Services Partner Developer’s Guide Result and error codes A.6.1. HTTP status codes The supported HTTP Status codes are shown in the table below. Code Message 200 OK 400 Invalid Request 401 403 405 406 500 505 Unauthorized Forbidden Method Not Allowed Not Acceptable Internal Server Error HTTP Version Not Supported Type Description Success Returned for all Successful Responses Error One or more of the input mandatory fields are missing. Display an Invalid Request screen. Error API Key is not valid Error API Key in not subscribed to service Error Served for Methods other than POST Error Accept Header does not comply with xwww-form-urlencoded Error Any Error that is returned from the backend systems (see next subparagraphs) or errors that are not covered by this list Error For Requests not on HTTP/1.1 protocol A.6.2. General error codes A.6.2.1. IP address not whitelisted The response below will be returned in case the IP address has not been whitelisted for the service called. Contact Millicom in order to add the correct IP address to the required services. Status code: HTTP/1.1 403 Forbidden { } "fault": { "faultstring":"Access Denied for client ip : ", "detail": { "errorcode":"accesscontrol.IPDeniedAccess" } } A.6.2.2. Invalid Request In case the header or JSON request body is incorrect the error as shown below will be returned. Please check the request is Status code: HTTP/1.1 400 Bad Request { } ErrorCode: "invalid_request" Error: "Missing required parameter transactionRefId" 41 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 46 Global Mobile Financial Services Partner Developer’s Guide A.6.2.3. Invalid Access Token The following error is returned in case an invalid Access Token is provided Status code: HTTP/1.1 401 Unauthorized Invalid accessToken. Please enter valid token. A.6.2.4. Access Token Expired The following error is returned in case an invalid Access Token is provided Status code: HTTP/1.1 401 Unauthorized Expired accessToken. Please enter valid token. A.6.2.5. Transaction Reference ID already used The error below is returned in case Transaction Reference ID has already been used for a previous transaction. Status code: HTTP/1.1 400 Invalid Request { } "ErrorCode": "invalid_request", "Error": "transactionRefId already exists" A.6.3. API Permission error The error below is returned in case the API has not been activated for the given Client_id and secret. Status code: HTTP/1.1 401 Invalid Request You don't have permission to access … API. Please contact Millicom admin A.6.4. Service specific result and error codes The subsections below list the Result and Error codes per service. The nominal (successful) cases are covered in Section 4. In case of an error a JSON response is returned with the following structure: 42 Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 47 Global Mobile Financial Services Partner Developer’s Guide { } "Fault": { "faultcode":"env:Server", "faultstring":” ”, "detail": { "ValidateMFSAccountFault": { "ResponseHeader": { "GeneralResponse": { "correlationID": , "status":"ERROR", "code":" ”, "description":" " } } } } } The error code provide in the “code” field has the following format: - - - , where API – Tigo API name APIID – unique numeric identifier of the API within Tigo Error code – based on the range and the fault type . Type of fault with: E – business fault – 3000 range F – fatal errors (such as network related faults) 2000 range V – validation fault –4000 range S – Success –0000 range W – warning (scenarios such as partial responses) – 6000 range 43 Millicom International Cellular SA 48 Global Mobile Financial Services Partner Developer’s Guide Global Mobile Financial Services Partner Developer’s Guide A.6.4.1. Payment Authorization Service result codes Code purchase-3008-0000-S Description Successful Payment Error code purchase-3008-2501-F purchase-3008-2502-F purchase-3008-3011-E Description Backend system error Transaction timed out Unable to complete transaction invalid amount purchase-3008-3043-E purchase-3008-3045-E Transaction not authorize Cancel Transaction Error Category Backend Error caused the transaction to fail. The transaction timed out causing it to fail. Unable to complete transaction as amount is invalid The customer did not authorize the payment and therefore the transaction failed. This could be caused by the customer not confirming payment, incorrect verification code or PIN code, insufficient balance etc. The customer doesn’t wish to complete the transaction and wants to cancel the transaction at its current state A.6.4.2. Validate MFS Account Service result codes 44 Code validatemfsaccount-3018-0000-S Description Provided MSISDN is a valid MFS Account. Error code Description Error Category Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 49 Global Mobile Financial Services Partner Developer’s Guide validatemfsaccount-3018-4501-V validatemfsaccount-3018-3001-E validatemfsaccount-3018-2501-F validatemfsaccount-3018-2502-F validatemfsaccount-3018-2505-F validatemfsaccount-3018-2506-F validatemfsaccount-3018-3603-E validatemfsaccount-3018-3999-E validatemfsaccount-3018-4502-V validatemfsaccount-3018-4503-V validatemfsaccount-3018-4504-V validatemfsaccount-3018-4505-V validatemfsaccount-3018-4506-V 45 Invalid Request. Please check the input and resubmit One or more back ends may be down. Please try again later. Service call has timed out. Please try again later. Service Authentication Failed. Consumer is not authorized to use this service. Internal service error has occurred. Unknown/Uncaught error has occurred. Invalid ISD code passed in the MSISDN Web Service Implementation is not available for this country Required additional parameters are not passed in the request. Duplicate additional parameters passed in the request. Invalid consumerId passed in the request. OSB Validation Error Backend Error Connection Error. Timeout error. OWSM Authentication Failure. OWSM Authentication Failure. Internal service error. Unknown/Uncaught error has occurred. Validation Error Validation Error When the required additional parameters are not passed When the required additional parameters are repeated When the consuming application does not send the Id , which helps middleware to identify the request originating request. Millicom International Cellular SA 50 Global Mobile Financial Services Partner Developer’s Guide Global Mobile Financial Services Partner Developer’s Guide A.6.4.3. Deposit Remittance Service result codes Code depositremittance-3017-0000-S Description The Transaction is completed successfully Error Code depositremittance-3017-2501-F Description One or more back ends may be down. Please try again later. Service call has timed out. Please try again later. Service Authentication Failed. depositremittance-3017-2502-F depositremittance-3017-2505-F depositremittance-3017-2506-F depositremittance-3017-3001-E depositremittance-3017-3002-E depositremittance-3017-3003-E depositremittance-3017-3004-E depositremittance-3017-3005-E depositremittance-3017-3006-E depositremittance-3017-3007-E 46 Consumer is not authorized to use this service. Authorization failed Password expired Sender account suspended Sender account does not exist Receiver Account suspended Receiver Account does not exist Error Category Connection Error. This is a Tigo internal error and should be treated as ‘Service not available’ Timeout error OWSM Authentication Failure. This is a Tigo internal error and should be treated as ‘Service not available’ OWSM Authentication Failure. This is a Tigo internal error and should be treated as ‘Service not available’ Uncaught error from the Tigo MFS Platform. This error should be treated as ‘Service not available’ The authorization for the transaction with the provided MFS Account details failed. Check the account details and send a new request. If the error persists contact Tigo to resolve The PIN/Password for the MFS account expired. Contact Tigo to reset the PIN The MFS Account has been suspended. Contact Tigo to resolve The provided MFS Account does not exist on the MFS platform in the country. Check the MFS Account details and send a new transaction. If the error persists contact Tigo to resolve The receiving MFS account has been suspended and therefore a remittance is not possible to this account. The receiving MFS account does not exist and therefore a Millicom International Cellular SA 51 Global Mobile Financial Services Partner Developer’s Guide depositremittance-3017-3008-E depositremittance-3017-3009-E depositremittance-3017-3010-E depositremittance-3017-3011-E depositremittance-3017-3012-E depositremittance-3017-3013-E depositremittance-3017-3014-E depositremittance-3017-3015-E depositremittance-3017-3016-E Maximum balance threshold for receiver exceeded Maximum number of transaction for receiver account reached Maximum number of transaction for sender account reached Transaction amount is less than the minimum transaction limit Maximum transaction limit exceeded Sender and receiver account are the same Service timeout Insufficient funds depositremittance-3017-3017-E Insufficient account permission depositremittance-3017-3018-E depositremittance-3017-3603-E User not found Internal service error has occurred. depositremittance-3017-3999-E depositremittance-3017-4002-V 47 Invalid amount specified Unknown/Uncaught error has occurred. Invalid amount passed in the request. Global Mobile Financial Services Partner Developer’s Guide remittance is not possible to this account. An invalid amount has been specified in the request. Send a new transaction with a correct amount. The balance of the receiving MFS account has been exceeded and therefore a remittance is not possible to this account. The maximum number of transactions of the receiving MFS account has been reached and therefore a remittance is not possible to this account. The maximum number of transactions of the sending MFS account has been reached and therefore a remittance is not possible to this account. The amount as passed in the request is less than the minimum transaction limit. The amount as passed in the request is more than the maximum transaction limit. Then sender and receiver accounts as specified in the request as the same. The request to deposit the remittance has timed out and therefore has not been completed. The account used for sending funds has insufficient funds. In case of the Payment aggregator account this should not occur. If it does occur Millicom has to be contacted. The account has insufficient permission to perform the deposit remittance. In case of the Payment aggregator account this should not occur and if it does Millicom has to be contacted. The account specified in the request cannot be found. Internal service error. This is a Tigo internal error and should be treated as ‘Service not available’ Unknown/Uncaught error has occurred. This is a Tigo internal error and should be treated as ‘Service not available’ When the amount is less than or equal to zero Global Mobile Financial Services Partner Developer’s Guide Millicom International Cellular SA 52 Global Mobile Financial Services Partner Developer’s Guide depositremittance-3017-4501-V depositremittance-3017-4502-V depositremittance-3017-4503-V depositremittance-3017-4504-V depositremittance-3017-4505-V depositremittance-3017-4506-V 48 Invalid Request. Please check the input and resubmit Invalid ISD code passed in the MSISDN Web Service Implementation is not available for this country Required additional parameters are not passed in the request. Duplicate additional parameters passed in the request. Invalid consumerId passed in the request. OSB Validation Error. This is a Tigo internal error and should be treated ‘Service not available’ Validation Error. An incorrect MSISDN was sent. Send a new request with a correct MSISDN Validation Error. The selected country does not implemented the web service This is a Tigo internal error and should be treated as ‘Service not available’ When the required additional parameters are repeated When the consuming application does not send the Id , which helps middleware to identify the request originating request Global Mobile Financial Services Partner Developer’s Guide Tigo Pesa 49
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No XMP Toolkit : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26 Create Date : 2017:02:02 10:23:41+03:00 Metadata Date : 2017:02:02 10:29:08+03:00 Modify Date : 2017:02:02 10:29:08+03:00 Creator Tool : Adobe InDesign CS6 (Macintosh) Instance ID : uuid:656a9039-28db-dc49-850e-eebd369dec86 Original Document ID : xmp.did:F77F117407206811A138FC20B7F0BD66 Document ID : xmp.id:9C2A6E86072068118083875EB8A9C8AD Rendition Class : proof:pdf History Action : converted History Parameters : from application/x-indesign to application/pdf History Software Agent : Adobe InDesign CS6 (Macintosh) History Changed : / History When : 2017:02:02 10:23:41+03:00 Derived From Instance ID : xmp.iid:9B2A6E86072068118083875EB8A9C8AD Derived From Document ID : xmp.did:F77F117407206811A138FC20B7F0BD66 Derived From Original Document ID: xmp.did:F77F117407206811A138FC20B7F0BD66 Derived From Rendition Class : default Format : application/pdf Producer : Adobe PDF Library 10.0.1 Trapped : False Page Count : 53 Creator : Adobe InDesign CS6 (Macintosh)EXIF Metadata provided by EXIF.tools