Loyalty Points - Refer and Earn

This integration involves the following parts :

• Middleware Configuration
• MTMS Configuration

Middleware Configuration

From the Middleware the steps are as follows:

Middleware Setup

Terrapay API Base URL

UAT: https://uat-connect.terrapay.com:21211/ 

Production: https://connect.terrapay.com:21211/

Please make sure to update .env.local file in the hydra system as below for production URL update. This is a ONE time setup only.

//ssh into Hydra production 

ssh hydra@rayyanuk.remitone.com
cd public_hydra/current
vi .env.local

###> Application ###
TERRAPAY_BASE_API_URL=https://connect.terrapay.com:21211/
###< Application ###

1.1. Create a client connected to the MTMS system

To create a new client, you have to log into the middleware, go to the Clients menu from the sidebar, click on "Add Client" and fill the fields in. The URL is the URL of the MTMS system to pull the transactions from.

1.2. Create an association between the client and the integration, and set the correct values for the configuration parameters

Go to the Client Integrations menu from the sidebar then click on Add Client Integrations.

On the next screen, select the Client and Integration.

Create a super bank in any of the countries that the client wants for Terrapay.

Create a web service user for this super bank and add it to the next step.To do so, connect as admin in ARM, go to Admin menu → Web Service Users and click on Add Web Service User. Give all the permissions. Make sure to make a note of the username and password we need this in the next step.

Afterward, set the right values in the textareas:

(Client Auth Configs will host the information relative to the web service user that will connect to the MTMS system, Integration Configs will have the parameters to export the transactions to Terrapay.)

Client Configs - MTMS Web Service User configs

{
  "ws_auth": {
    "pin": 12345,
    "password": "XXX",
    "username": "XXX",
    "super_bank": true
  },
  "two_step_cancellation": {
    "enabled": false,
    "transition_state": "DELETED"
  }
}

Integration Configs - Terrapay Configs

{
  "headers": {
    "X-PASSWORD": "XXX",
    "X-USERNAME": "XXX",
    "X-ORIGINCOUNTRY": "XXX"
  },
  "organisation_prefix": "XXX",
  "settlement_currency": "XXX"
}

The X-PASSWORD and X-USERNAME fields will be provided by Terrapay.

X-ORIGINCOUNTRY corresponds to the ISO code of the source country, which in this case is GN (Guinea).

organisation_prefix corresponds to the client's name prefix for Terrapay in this integration. You can call it WelyWely

As for settlement_currency, it refers to the source currency code, which will default to "EUR" for this integration.

Tick the enabled checkbox to activate the association.

To finish, click the Create button on the top right corner.

1.3 Create an Middleware API user to connect from MTMS to Middleware

Go to the API Users menu from the sidebase then click on Add API User.

On the screen, select the Client Integration created from Step 1.2 above.

Then provide a desired username and password. Please make sure provide a strong password. And finally click Enabled tick box to enable the API user. Keep these details handy as you will need them.

Please make sure ROLE_API_USER is selected.

To finish, click the Create button on the top right corner.

MTMS Configuration

2.1. Configuring entities

Supported Transfer Types

• Account transfer
• Mobile Transfer

To configure the MTMS for the Terrapay integration, you need to import entities from Middleware system. The middleware system will import entities from Terrapay and send to MTMS system to create necessary delivery entities.

NOTE: Terrapay operates on different corridors and before you setup the integration please check with client and get a list of supporter destination countries required for this integration, if you have not done so already.

// Supported countries - BF, CM, SN, CI, FR, ES, CA, US, TN, EG, MA

To run entity import configure the Terrapay config under MTMS custom/config/config_3rdparty.json. Sample config as follows

"CONFIG_TERRAPAY": {
        "enabled": true,
        "processing_bank_prefix": "TERRAPAY-",
        "entity_import_countries": ["SN"],
        "hydra_credentials": {
          "base_url": "https://hydra.remitone.com/api/",
          "username": "XXX",
          "password": "XXX"
        }
    }

Please update the config as necessary. The entity_import_countries are the supported countries mentioned above. You can set array of countries here.

The hydra credentials are the API user credentials for the middleware. You need to setup the integration and create an API user and use those configs to update here in MTMS. (step 1.3)

Enable following UI settings. CONFIG_FORMS_BASE

Test: https://hydratest.remitone.com/api/

Production: https://hydra.remitone.com/api/

To import the entities, please type the following command on terminal : 

php bin/integration terrapay:import-entities

Once you import the entities please make sure to check entities are imported correctly and have data as follows.

The entity import command will automatically create Proc banks and necessary delivery entities based on the results of Terrapay API results. You can see the logs in logs/terrapay_import_entities.log

2.2. Link the new proc banks to the super bank

The new proc banks that were imported will need to be linked to the super bank we created in step 1.2.

For all the countries that we imported entities for we will need to edit the proc bank and add the super bank as their parent bank.

2.3. Update state machine configurations

To update all the Terrapay transactions to HQ_OK, add a record to custom/config/config_state_machine.json under modify_state_machine

{
    "CONFIG_NOTIFICATION":{
       // real-time subscriptions :
       "realtime_subscriptions":{
          "ABORTED_TRANSACTION": [
            "remitone\\integration\\Terrapay\\TerrapayRealtimeDeleteTransactionSubscriber"
          ]
            }
       }
}

2.5. Update System settings

Please make sure following options to be enabled/true.

If the cron jobs are running automatically, transactions pulled from the MTMS will be visible in the Transactions menu.