Skip to content

Application integration guidelines for online payments

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 Tigo Secure Server Operators

SSL Mutal SSL
IP Whitelisting IP Whitelisting

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.

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

  5. Submit the IP address of the server(s) that will connect with Tigo Secure in order to whitelist

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

  • Differs from country to country but high level is:

    1. Business Name

    2. Business License

    3. Tax Identification Number

    4. Stated Capital

  • 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

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

Collection Account

This type of account is provided in cases where thepartner 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.

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.

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 Secretdirectly 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]

System Status heartbeat signal

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.

International Remittance Money Deposit

The process to deposit money for international remittance is shown in the Figure below.

(1,2) An Access token has to be requested for the Tigo Secure Server via the GenerateAccessToken service 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.

(7-10) the Remittance Partner can deposit the amount in the local currency via the DepositRemittance service

(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

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.

Payment Authorization via SMS verification code

In the following countries the payment is authorized 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.

  1. The subscriber/customer initiates a Tigo MFS payment via the Merchant.

2-3. An Access token is rquested for the Tigo Secre Server via the GenerateAccessToken service using the Apigee API Key

4-8. Th Payment Authorzato Request is made with the necssary paymnt details, this will return a rdirect URL to the Tigo Secure Payment Authorizaton page which the customter has to be redirected

  1. In case the MSISDN is not yet specified in the Payment Authorization request or in case the MSISDN was incorrect (non-existent) then the Customer is redirected to a page to enter the MSISDN.

(10-14) The MFS Account of the subscriber is validated after which the 'Verify' Page is shown. (see Figure 3-5) and a One-Time-Pin (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.

Payment Overview Page

(17-19) The customer provides the MFS PIN and the purchase call to make sure the payment is sent. (20) Upon receipt of a successful purchase response the access token is invalidated and a payment result page is shown for a limited duration

  1. 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.

  2. 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 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.

Payment Authorization via USSD Push

In the following countries the payment is authorized 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:

Figure: Payment Authorization flow USSD Push

  1. The subscriber/customer initiates a Tigo MFS payment via the Merchant.

(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.

(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.

Figure: Payment details

(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: 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: Payment result page

  1. 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.

  2. The final redirect is done to the specified redirect URI.

  3. Reverse Transaction

The Reverse Transaction Service can be used to reverse or refund a successful transaction made via the Online Payment.