Integration Guides

Remittance Use Cases

Suggest Edits

Remittance Type: CSN

This use case deals with transferring money to mobile phone, EFT, Cash Out option with input of a mobile number and transferring money out of the customer eclipse wallet to calling CSN and instant settlement with CSN financial services at an individual transaction level .

Customer registration process with CSN

  1. New customer should register through CSN
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/remittances/enroll-customers
  1. Eclipse updates CSN customer profile with any changes with API 
PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/remittances/enroll-customers

3 ) Eclipse checks if CSN customer exists for KYC status with API 

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/remittances/enroll-customers

CSN Customer Verification Using Iproov

When the iProov SDK is used by the tenant to do a liveness check, the tenant channel needs to store the iProov result on the customer profile.

A generic way to do this is to add an attachment onto the customer with a special label like ‘iProovResult’.
Then whenever a ratify is run on a customer, check if the customer has an iProov attachment and does not have a facial photo, then fetch the facial photo from iProov and store it as the facial photo as a document. Then continue with ratify as normal.

If eclipse update can profile is completed then use for Iproov call for customer KYC verification base on Iproove Check {KYC status = Pending,KYC state = iProov,KYC level = Non-verified Status=Active}

  1. Check Kyc Status with GET/eclipse-conductor/rest/v1/tenants/{tenantId}/remittances/enroll-customers

  2. Get IProove token with API

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/integrations/{integrationIdentifier}

Customer gets a quick quote/indicative quote

  1. Customer we can check exchange rates without login with API 
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/remittances/quick-quotes

Below payload can be use to see exchange rates from ZAR to foreign currency

{
  "destinationCountry": "ZW",
  "destinationCurrency": "USD",
  "provider": "CSN",
  "sourceAmount": 10,
  "sourceCountry": "ZA",
  "sourceCurrency": "ZAR"
}

Below payload can be use to see exchange rates from foreign currency to ZAR

{
  "destinationAmount": 10,
  "destinationCountry": "ZA",
  "destinationCurrency": "ZAR",
  "provider": "CSN",
  "sourceAmount": 0,
  "sourceCountry": "ZW",
  "sourceCurrency": "USD"
}

Create New Beneficiary using CSN

When integrating to a remittance provider (CSN) we need to create beneficiaries on the remittance provider before initiating remittance.

We need to be able to distinguish between normal beneficiaries and beneficiaries that need to be created on the remittance provider as well.

Channel adds beneficiary and provides remittance provider, beneficiary is added on Eclipse and CSN - all new fields populated.

Eclipse Provides Remittance Catalogues for Tenants

It is recommended to search service code from catalogues within the tenant.

Below are the properties which need to be configure for remittance:

remittance.catalog.providers=com.ukheshe.services.remittance.catalog.CSNCatalog.
GET/eclipse-conductor/rest/v1/tenants/{tenantId}/remittances/catalogues?catalogQuery=limit_currency=ZAR
  • limit_currency =ZAR
  • CSN - Provider
  • Based on catalogQuery they returned products along with minimum and maximum amount in ZAR. if we don't pass catalogQuery param then it will revert minimum and maximum amount in foreign currency

Select catalogId from catalogues to further initiate the remittance process.

Step 1 –Initiate Remittance Process
The overall process depends on the type of remittance.

Customer we can check exchange rates in remittance with API 

POST
/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/remittances
{
  "amount": 10,
  "callbackUrl": "htttps://www.google.com",
  "destinationCurrency": "USD",
  "externalUniqueId": "string",
  "provider": "CSN",
  "saveDestinationAsBeneficiary": true

Step 2 - Initiate temporary quote for remittance process
Passed tenantId,wallet id and remittance id for update remittance along with below request payload. This below request in additionFields for serviceId,purposeOfTransaction and sourceOfFunds based on country support value used to remittance catalogue API response.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/remittances
{
  "amount": 10,
  "callbackUrl": "htttps://www.google.com",
  "destinationCurrency": "USD",
  "externalUniqueId": "string",
  "provider": "CSN",
  "saveDestinationAsBeneficiary": true}

Below Request is for additionFields for serviceId,purposeOfTransaction and sourceOfFunds based on country support value used to remittance catalogue API response.

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/remittances/{remittanceId}
{
  "additionalFields": [
    {
      "id": "serviceId",
      "value": “clicksendnow_zw"
    },
    {
      "id": "purposeOfTransaction",
      "value": "Gift"
    },
    {
      "id": "sourceOfFunds",
      "value": "<>"
    }
  ],
  "beneficiaryId": 239,
  "submit":false
}

If senderExternalSourceType = PAYAT is enable 

PUT/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/remittances/{remittanceId}
{
  "additionalFields": [
    {
      "id": "serviceId",
      "value": "test_cooperative_ke"
    },
    {
      "id": "purposeOfTransaction",
      "value": "Gift"
    },
    {
      "id": "sourceOfFunds",
      "value": "Pension"
    },
    {
      "id": "senderExternalSourceType",
      "value": "PAYAT"
    }
  ],
  "amount": 1200,
  "beneficiaryId":328,
   "submit":false
}

{
  "additionalFields": [
    {
      "id": "serviceId",
      "value": "test_cooperative_ke"
    },
    {
      "id": "purposeOfTransaction",
      "value": "Gift"
    },
    {
      "id": "sourceOfFunds",
      "value": "Pension"
    },
    {
      "id": "senderExternalSourceType",
      "value": "PAYAT"
    },
    {
      "id": "providde_beneficiary_id",
      "value": "71004abe-9f21-45e0-8b8c-159847fb5a29"
    }
  ],
  "remittanceId": 2723,
  "status": "PENDING",
  "created": "2023-03-28T05:35:57.000Z",
  "destinationAmount": 7898.9,
  "fee": 0,
  "amount": 1200,
  "currency": "ZAR",
  "destinationCurrency": "KES",
  "exchangeRate": 0.15192,
  "quoteExpires": "2023-03-28T05:55:58.000Z",
  "externalUniqueId": "strinsgsksssfsfsfs",
  "walletId": 1999,
  "extraInfo": "{\"senderExternalSource\":\"{\\\"customerData\\\":{\\\"firstName\\\":\\\"ZALAK\\\",\\\"lastName\\\":\\\"GOOD\\\",\\\"idNumber\\\":\\\"PV5989530\\\",\\\"contactNumber\\\":\\\"0605989530\\\"},\\\"type\\\":\\\"PAYAT\\\"}\",\"referenceId\":\"[{\\\"id\\\":\\\"MFS_AFRICA_TRANSACTION_ID\\\",\\\"value\\\":\\\"1157343101438\\\"}]\"}",
  "destinationCountry": "KE",
  "totalSourceAmount": 1200
}

ExtraInfo Field has senderExternalSource and referenceId information from PAYAT

Step 3 - Final Book Deal for Remittance Process

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/remittances/{remittanceId}

{
  "additionalFields": [
    {
      "id": "serviceId",
      "value": "clicksendnow_zw"
    },
    {
      "id": "purposeOfTransaction",
      "value": "Gift"
    },
    {
      "id": "sourceOfFunds",
      "value": "Pension"
    }
  ],

  "beneficiaryId": 239,
  "submit":true
}

The Remittance will be in status PENDING and will transition to SUCCESSFUL or ERROR_PERM depending on the result.

Catalog Refresh.

The remittance catalog can be frequently refreshed at a configurable period. The config can be maintained on the global property csn.config by adding a line item catalogRefreshIntervalInMinutes = 30 by calling the endpoint below:

https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantID}/remittances/catalogs?catalogQuery=Refresh

If the config catalogRefreshIntervalInMinutes is not maintained, the default refresh frequency will be 60 minutes.

📘

Note

The catalog can be refreshed manually by calling the retrieve catalog endpoint with catalogQuery set to Refresh

Corridor Management (Notification Management for Corridor Activation)

Required Configurations:
  1. schedule.notification.allow - value can be true/false, the default value is false)
  2. notification.expiry - an integer value that determines the expiration of notifications pending to be broadcasted.
Enhancements to the Notification Endpoint

The POST Notification API has been enhanced to support schedule notifications.


https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/docs/#/b)%20Tenant%20Configuration%20%26%20Onboarding/post_eclipse_conductor_rest_v1_tenants__tenantId__notifications
Integration Steps for Notification API

To register a notification, ensure the following conditions are met:

Configuration Must Be Enabled
RuleMatch and EventType Must Not Be Null: Both rulematch and eventtype attributes must have valid values.

If any of these attributes (configuration, rulematch, or eventtype) are null, the system will send the notification immediately.

Request Payload Example:

{  
  "data": "{\"phone\":\"919737700802\"}",  
  "ruleMatch": "TZ_Tanzania_ACTIVE",  
  "templateId": "auth",  
  "type": "SMS",  
  "eventType": "remittance"  
}

Required Fields:

  1. data: Contains data (primarily in JSON format) that will be used to replace dynamic values in the notification.
  2. ruleMatch: A regular expression used to determine when a notification should be sent based on a match.
  3. templateId: The ID of the notification template that will be used.
  4. type: The type of notification, such as "SMS" or "email". In this example, the type is "SMS".
  5. eventType: The event that triggers the notification. Currently, the only supported event is "remittance".

Example Workflow
For instance, if you register a notification with the ruleMatch set to TZ_Tanzania_ACTIVE and the eventType as remittance, the notification will be sent out when the status of Tanzania changes to ACTIVE.

Updated about 1 month ago