VAS Use Cases

Eclipse has integrations to a number of VAS providers covering a wide range of services from airtime, electricity, bill payments, etc. Typically the process for purchasing VAS involves 4 steps:

Retrieve the VAS catalog
Get network partner ID for mobile number - this is optional and relevant only for airtime VAS. Here you retrieve the partner ID for the provided mobile number, this queries the relevant mobile number portability database
Prepare catalog query - this is optional and the entire catalog can be retrieved.
Initiate VAS payment - typically the payment data consistS of the partnerId and productId of a product in the VAS catalog separated with an _ e.g. 2_ABC123
Complete VAS Payment

Here are details for specific providers.

South Africa VAS providers

The following VAS providers are specific to tenants operating in South Africa.

Purchase VAS from Scan to Pay

Introduction

Scan to Pay is a QR code payment solution for seamless and contactless transactions. Scan to Pay revolutionizes the way merchants and consumers interact financially.

For merchants, Scan to Pay offers the flexibility to create and manage static or dynamic QR codes, enabling them to accept payments effortlessly. Whether you're a local store, restaurant, or an online business, our platform ensures a smooth payment experience for your customers.

Consumers benefit from the convenience, safety, and security of Scan to Pay. Consumers can simply scan the QR code, confirm the transaction, and they're done! No need to worry about carrying cash or cards.

One feature of Scan to Pay is to efficiently enable consumers to purchase VAS products of their choosing within the application.

Prerequisites

A valid JWT for API calls.
A valid Scan to Pay username and password.

It is recommended to search service code from catalogs within the tenant.
Below are the tenant configs to be configured for Scan to Pay

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.MasterpassRechargeProvider
oltio.config.username={username}
oltio.config.password={password}
destination.wallet.config.VAS.1={destination walletId}

Step 1 - Verify mobile number (MSISDN) network

GET /https://eclipse-conductor/rest/v1/tenants/{tenantId}/vas/{msisdn}

You can only get the names of the mobile networks of the vas partners associated with eclipse only.

Step 2 - Get the list of VAS partners & products

GET /https://eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs

The list of the partners and products per partner will be returned. Listed partners are country specific e.g tenant in RSA only gets the catalogs of RSA partners

Step 3 - Filter the catalog

Once the catalog is returned the channel filters the catalog based on the MSISDN provided in step 1.
Select productid from catalogs to further initiate the payment process (i.e., "productid": "VD11")
Below is a list from one of the providers.

{partnerId: 5, partnerName: "Vodacom", providerId: 1,…}
partnerId: 5
partnerName: "Vodacom"
products
[{partnerId: 5, productTypeName: "SMS", productId: "VS02", productName: "SMS20",…},…]
{partnerId: 5, productTypeName: "SMS", productId: "VS03", productName: "SMS50",…}
{partnerId: 5, productTypeName: "SMS", productId: "VS04", productName: "SMS100",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD11", productName: "DATA75MB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD12", productName: "DATA240MB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD13", productName: "DATA400MB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD14", productName: "DATA600MB",…}
{partnerId: 5, productTypeName: "AIRTIME", productId: "01", productName: "100 Minutes",…}
{partnerId: 5, productTypeName: "AIRTIME", productId: "03", productName: "500 Minutes",…}
{partnerId: 5, productTypeName: "AIRTIME", productId: "05", productName: "250 Minutes",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD50", productName: "DATA2.5GB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD15", productName: "50MB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD51", productName: "DATA4.5GB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD52", productName: "DATA7GB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD53", productName: "DATA12GB",…}
{partnerId: 5, productTypeName: "DATA", productId: "VD54", productName: "DATA18GB",…}]

Step 4 - Initiate Making a Payment by a Customer

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments
{
  "additionalFields": [
    {
      "id": "msisdn",
      "value": "value"
    }
  ],
  "landingUrl": "https://www.google.com/",
  "callbackUrl": "http://www.callback.com",
  "externalUniqueId": "abcd1234",
  "paymentData": "5_VD50",
  "type": "GLOBAL_VAS",
  "currency": "ZAR",
  "walletId": XXX
}

In this use case the paymentData could be thepartnerId and productId (i.e. 5_VD50)

PartnerId = 5

productId = VD50

In response the paymentId & amount along with all required extra information is provided.

Step 5 - Update Necessary Fields for Payment

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/payments/{paymentId}
Passed tenantId and paymentId for update payment along with below request payload.
{
  "amount": 155,
  "walletId":XXX,
  "landingUrl": "https://www.google.com/"
}

Scan to Pay returns a success response string once a payment outcome is successful.

Purchase VAS from ACS

Introduction

ACS services to integrate with Eclipse as an open feature platform. It has an extensive catalog of APIs available for tenants to manage airtime, data & electricity bundles.

Prerequisites

A valid JWT for API calls.
Eclipse provides global vas catalogs for tenants.

It is recommended to search service code from catalogs within the tenant.
Below are the tenant configs to be configured for ACS

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.AcsMobileRecharge
destination.wallet.config.VAS.1={destination walletId}

Step 1 - Prepare MSISDN

GET /https://eclipse-conductor/rest/v1/tenants/{tenantId}/vas/{msisdn}

You can only get the names of the mobile networks of the vas partners associated with eclipse only.

Step 2 - List of VAS partners & products

GET /https://eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs

The list of the partners and products per partner will be returned. Listed partners are country specific e.g tenant in RSA only gets the catalogs of RSA partners

Step 3 - Channel to filter the catalog

{partnerId: 4, partnerName: "MTN", providerId: 1,…}
partnerId: 4
partnerName: "MTN"
products
[{partnerId: 4, productTypeName: "SMS", productId: "M502", productName: "SMS30",…},…]
{partnerId: 4, productTypeName: "SMS", productId: "M502", productName: "SMS30",…}
{partnerId: 4, productTypeName: "SMS", productId: "M504", productName: "SMS100",…}
{partnerId: 4, productTypeName: "DATA", productId: "M511", productName: "DATA350MB",…}
{partnerId: 4, productTypeName: "DATA", productId: "M512", productName: "DATA500MB",…}
{partnerId: 4, productTypeName: "DATA", productId: "M513", productName: "DATA1GB",…}
{partnerId: 4, productTypeName: "DATA", productId: "M514", productName: "DATA2GB",…}
{partnerId: 4, productTypeName: "AIRTIME", productId: "01", productName: "MTN R30 Call",…}
{partnerId: 4, productTypeName: "AIRTIME", productId: "03", productName: "MTN R60 Call",…}
{partnerId: 4, productTypeName: "AIRTIME", productId: "05", productName: "MTN R180 Call",…}
{partnerId: 4, productTypeName: "AIRTIME", productId: "11", productName: "MTN R10 Recharge",…}
{partnerId: 4, productTypeName: "AIRTIME", productId: "12", productName: "MTN R15 Call",…}
{partnerId: 4, productTypeName: "AIRTIME", productId: "13", productName: "MTN R5 Call",…}
{partnerId: 4, productTypeName: "DATA", productId: "M550", productName: "DATA100MB",…}
{partnerId: 4, productTypeName: "AIRTIME", productId: "M500", productName: "MTN Pinless ",…}
{partnerId: 4, productTypeName: "DATA", productId: "M515", productName: "50MB",…}
{partnerId: 4, productTypeName: "DATA", productId: "M551", productName: "DATA3GB",…}
{partnerId: 4, productTypeName: "DATA", productId: "M552", productName: "DATA10GB",…}
{partnerId: 4, productTypeName: "DATA", productId: "M553", productName: "DATA20GB",…}
{partnerId: 4, productTypeName: "DATA", productId: "M554", productName: "DATA30GB",…}
providerId:1

Step 4 - Initiate Making a Payment by a Customer

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments
{
  "additionalFields": [
    {
      "id": "msisdn",
      "value": "xxxxxxxxxxxxx"
    }
  ],
  "landingUrl": "https://www.google.com/",
  "callbackUrl": "http://www.blankwebsite.com",
  "externalUniqueId": "abcd1234a",
  "paymentData": "4_M512",
  "type": "GLOBAL_VAS",
  "currency": "ZAR",
  "walletId": XXX
}

So here paymentData it could be (i.e. 4_M512)
4 - PartnerId
M512 - productId

In response getting paymentId & amount along with all required extra information.

Step 5 - Update Necessary Fields for Payment

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/payments/{paymentId}
Passed tenantId and paymentId for update payment along with below request payload.
{
  "amount": 49,
  "walletId":xxxxx,
  "landingUrl": "https://www.google.com/"
}

ACS returns a success response string once a successful payment.

Electricity VAS purchases via ACS

Important NOTE:

Once a user has purchased an electricity voucher via ACS a dummy code is visible to the user on Sandbox.
On production, this voucher code is known as an UnPin.
The UnPin is sent to the user via SMS & should appear on the successful electricity purchase screen on the channel.
This UnPin is useless until the user dials the number below.

The meter number would be on the user's prepaid meter.
After the number is dialled the user will receive another SMS & that pin is what will be inputted into the prepaid meter
The channel will need to include the UnPin & USSD number string above the successful electricity purchase screen.

Purchase VAS from Kganya

Introduction

Kganya services to integrate with Eclipse as an open feature platform. It has an extensive catalog of API’s available for tenants to manage the bills and data bundles.

Prerequisites

A valid JWT for API calls.
Eclipse provides global vas catalogs for tenants.

It is recommended to search service code from catalogs within the tenant.
Below are the properties which need to be configure for kganya:

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.KganyaMobileRecharge
tenant.config.

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.KganyaMobileRecharge
kganya.config.baseUrl={baseUrl}
kganya.config.apiKey={apiKey}
destination.wallet.config.VAS.16={destination walletId}

Step 1 - Prepare catalogQuery

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs?catalogQuery=16_0310564280_T089775335322

16 - PartnerId for Kganya
0310564280 - Mobile number, If not available then pass 0
T089775335322 - ID number

Based on catalogQuery they returned products. Select productid from catalogs to further initiate the payment process (i.e. "productId": "0310564280_T089775335322_1")

Step 2 - Initiate Making a Payment by a Customer

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments
{
  "additionalFields": [
    {
      "id": "msisdn",
      "value": "xxxxxxxxxxxxx"
    }
  ],
  "landingUrl": "https://www.google.com/",
  "callbackUrl": "http://www.blankwebsite.com",
  "externalUniqueId": "abcd1234a",
  "paymentData": "16_0310564280_T089775335322_3",
  "type": "GLOBAL_VAS",
  "currency": "ZAR",
  "walletId": XXX
}

So here paymentData it could be (i.e. 16_0310564280_T089775335322_3)
16 - PartnerId
0310564280_T089775335322_3 - productid

In response getting paymentId & amount along with all required extra information.

Step 3 - Update Necessary Fields for Payment

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/payments/{paymentId}

Passed tenantId and paymentId for update payment along with below request payload.

{
  "amount": xxx,
  "walletId": xxx,
  "landingUrl": "https://www.google.com/"
}

Kganya returns a success response string once successful payment.

Purchase VAS from Pay@

Pay@ services to integrate with Eclipse as an open feature platform. The Pay@ system facilitates the real-time transaction flow, reconciliation and funds settlement between networks/retailers and bill payments authorizers/issuers.t has an extensive catalog of API’s available for tenants to manage the Pay various bills.

Prerequisites

A valid JWT for API calls.
Eclipse provides global vas catalogs for tenants.
It is recommended to search service code from catalogs within the tenant

Below are the properties which need to be configure for Pay@:

tenant.config.

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.PayAtRecharge
destination.wallet.config.VAS.14=${destinationWalletId}

payat.config

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.PayAtRecharge
baseAuthURL=${baseURL}
client_id=${clientId}
client_secret=${clientSecretKey}
token_url=${clientTokenURL}
api_url=${paymentAPIURL}
scope=8bc2bdd8-84eb-409c-84b1-a20e63bc684d

mobilerecharge.config

payAtName=PayAt
payAtNetworkId=14
sd.external.services=REST,PayAtAPI,${baseURL},^/payat, , ,0,0, ,/payat

[email protected] = [{"networkId":"14","voucherTypeName":"Bill","voucherId":"1","voucherCategory":"Bill","voucherName":"Bill account number","voucherDescription":"Bill accountnumber that needs to be paid by PayAt","fixedPriceIncl":"0","minAmountIncl":"0","maxAmountIncl":"0","pinnedVoucher":false,"additionalFields":[{"id":"accountNumber","title":"Account Number","type":"NUMBER","regex":"^(0|[1-9][0-9]*)$","regexErrorMessage":"Invalid Account Number"}]}]

Step 1 – Fetch Catalog

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs

PartnerId for pay@

API Returned Multiple products with Partner Id 14. Select productId from catalogs to further initiate the payment process (i.e. "productId": "1"). In PayAt There was only One Product only in the Catalog.

Step 2- Initiate a Payment

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments  
{ 
      "additionalFields": [ 
        { 
          "id": "accountNumber", 
          "value": "xxxxxxxxxxxx" 
        } 
      ], 
      "callbackUrl": "http://www.blankwebsite.com", 
      "externalUniqueId": "9e60398d-6ddd-4f46-b6cd-2081c872b2ea", 
      "paymentData": "14_14577", 
      "type": "GLOBAL_VAS" 
}

So above paymentData it could be (i.e. 14_14577)
14 - PartnerId
14577- productid
which will get response paymentId & amount along with all required extra information.

Step 3- Update Fields for Payment

PUT/eclipse-conductor/rest/v1/tenants/{tenantId}/payments/{paymentId} 
Passed tenantId and paymentId for update payment along with below request payload. 
{ 
      "amount": 150, 
      "walletId": XXX, 
      "externalUniqueId":"9e60398d-6ddd-4f46-b6cd-2081c872b2ea" 
}

Pay@ returns a success response string once successful payment.

Purchase VAS from EasyPay

EasyPay services to integrate with Eclipse as an open feature platform. 

It has an extensive catalog of API’s available for tenants to manage the Pay various bills, Vend airtime, SMS Pack and data bundles.

Prerequisites

A valid JWT for API calls.
Eclipse provides global vas catalogs for tenants.
EasyPay requires VPN connection to connect to that Host and Port.
EasyPay internally supports SOAP API.
It is recommended to search service code from catalogs within the tenant.

Below are the properties which need to be configure for Easy Pay:

tenant.config.

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.EasyPayMobileRecharge
destination.wallet.config.VAS.15=${destinationWalletId}

easypay.config

host=${host}
cardAcceptor=7470
port=${port}
connectTimeoutMs=6000

mobilerecharge.config

easyPayNetworkName=EasyPay
easyPayNetworkId=15

[email protected] = [{"networkId":"15","voucherTypeName":"SMS BUNDLE","voucherId":"1725","voucherCategory":"VODACOM","voucherName":"Vodacom Topup","voucherDescription":"Vodacom 50 SMS bundle","fixedPriceIncl":"25","minAmountIncl":"0","maxAmountIncl":"0","pinnedVoucher":false}]

Step 1 – Fetch Catalog

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs

PartnerId for EasyPay is 15.

API Returned Multiple products with Partner Id 15. Select productid from catalogs to further initiate the payment process (i.e. "productId": "1")

Step 2 - Initiate a Payment

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments  

{ 
  "additionalFields": [ 
    { 
      "id": "msisdn", 
      "value": "xxxxxxxxxxxxx" 
    } 
  ], 
  "landingUrl": "https://www.google.com/", 
  "callbackUrl": "http://www.blankwebsite.com", 
  "externalUniqueId": "29agd6z317d519e87211", 
  "paymentData": "15_1764", 
  "type": "GLOBAL_VAS", 
  "phone": "xxxxxxxxxxxxx", 
  "walletId": XXX 
}

Here paymentData it could be (i.e. 15_1764)
15 - PartnerId
1764 - productid
In response getting paymentId & amount along with all required extra information.

Step 3 - Update Fields for Payment

PUT/eclipse-conductor/rest/v1/tenants/{tenantId}/payments/{paymentId} 

Passed tenantId and paymentId for update payment along with below request payload. 
{ 
      "amount": 150, 
      "walletId": XXX, 
      "externalUniqueId":"29agd6z317d519e87211" 
}

EasyPay returns a success response string once successful payment.

Kenya VAS providers

The following VAS providers are specific to tenants operating in Kenya.

Pay Tax through Diamond Trust Bank

DTB integrations allow the ability to forcustomer to query their Payment Registration Number (PRN) against the Kenya Revenue Authority (KRA) and then pay the tax amount.

Prerequisites

A valid JWT for API calls.

Below are the tenant configs that need to be configured when paying tax through Diamond Trust Bank:

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.DTBQueryUtilityRecharge
destination.wallet.config.VAS.19=${destinationWalletId}

Step 1 – Validate PRN and get amount owed

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs?19_ETAX_10202300000582380

The catalog query is partnerId_taxUtilitCode_prn. Partner ID for DTB Tax payments is 19 and the utility code is ETAX.

[
  {
    "partnerId": 19,
    "partnerName": "dtbQueryUtility",
    "providerId": 19,
    "products": [
      {
        "partnerId": 19,
        "productId": "ETAX_1020230000058238",
        "productName": "ETAX",
        "pinnedProduct": false,
        "additionalFields": [
          {
            "id": "SystemCode",
            "defaultValue": "PG"
          },
          {
            "id": "EslipNumber",
            "defaultValue": "1020230000058238"
          },
          {
            "id": "PaymentAdviceDate",
            "defaultValue": "2023-06-19T13:25:12"
          },
          {
            "id": "TaxpayerPin",
            "defaultValue": "P051094777L"
          },
          {
            "id": "TaxpayerFullName",
            "defaultValue": "Call Fast Services Limited"
          },
          {
            "id": "TotalAmount",
            "defaultValue": "52008620"
          },
          ......

Step 2 - Initiate a Payment

📘
Note
The wallet type of the walletId specified in the body determines if the source of the transaction is an Eclipse wallet or a DTB Bank Account.

paymentData field is {partnerId} {taxUtilitCode} {prn}. Partner ID for DTB Tax payments is 19 and the utility code is ETAX.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments	
{
    "externalUniqueId": "772021c2-bc1b-4a83-8c26-2ea2fe210836",
    "type": "GLOBAL_VAS",
    "paymentData": "19_ETAX_1020230000060915",
    "amount": 52008620,
    "currency": "KES",
    "additionalFields": [ ],
    "walletId": 830989,
    "customFraudChecks": false
}

{
    "paymentId": 453209,
    "externalUniqueId": "772021c2-bc1b-4a83-8c26-2ea2fe210836",
    "status": "PENDING",
    "amount": 52008620,
    "currency": "KES",
    "additionalFields": [ ],
    "acceptedCardSchemes": [ ],
    "cardPhone": "254729294292",
    "phone": "254729294292",
    "acceptedPaymentMechanisms": [ ],
    "paymentType": "EFT",
    "created": "2023-09-15T09:11:14.000Z",
    "extraInfo": "{"dtbCallingCustomerCif":"65594662-bc39-4c0d-8c7c-bc7cf6012fb9","dtbCallingCustomerId":709193,"dtbCallingCustomerOrganisation":"","dtbSourceBankCode":"","dtbSourceCountryCode":"KE","dtbSourceCurrency":"KES","dtbSourceName":"kuBQcxDilafNzey RQPgcyyEQNZdBLF","dtbSourcePhone":"254729294292","dtbSourceType":"DTB_WALLET","dtbDestinationCurrency":"KES"}",
    "paymentInstrumentInfo": {
        "cardPhone": "254729294292"
    },
    "fee": 0,
    "paymentReference": "1020230000060915",
    "walletId": 830989,
    "customerId": 709193
}

Typically you will immediately receive a PENDING response. If the callbackUrl was populated a callback will be sent to that URL when the payment is finalised (either successful or error). Alternatively a call can be made to the GET payment by paymentId endpoint.

Purchase VAS through Diamond Trust Bank

Eclipse has integrations to DTB to offer a wide range of VAS services where tenants can pay various bills, Vend airtime, SMS and data bundles.

Prerequisites

A valid JWT for API calls.

Below are the tenant configs that need to be configured when purchasing VAS through Diamond Trust Bank:

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.DTBQueryUtilityRecharge
destination.wallet.config.VAS.19=${destinationWalletId}

Step 1 – Fetch Catalog

The catalog query is {partnerId}_LOCAL-CATALOG. Partner ID for DTB VAS payments is 1.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs?catalogQuery=19_LOCAL-CATALOG

API Returned Multiple products with Partner Id 19. Select productid from catalogs to further initiate the payment process (i.e. "productId": "1")

Step 2 - Initiate a Payment

📘
Note
The wallet type of the walletId specified in the body determines if the source of the transaction is an Eclipse wallet or a DTB Bank Account.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments  	
{
    "externalUniqueId": "4490d40f-f2ef-4ee6-878c-2885fd4d990c",
    "type": "GLOBAL_VAS",
    "paymentData": "19_KE-STARTIMES_1234567890",
    "amount": 100,
    "currency": "KES",
    "additionalFields": [ ],
    "walletId": 836788,
    "description": "VAS KE-STARTIMES payment for 1234567890",
    "customFraudChecks": false
}

Here paymentData is partnerId_productId/utility_code_optional_reference

e.g. 19_KE-STARTIMES_1234567890

{
    "paymentId": 453215,
    "externalUniqueId": "019f240f-163f-43c2-a9b4-273b50e910a9",
    "status": "PENDING",
    "amount": 100,
    "description": "VAS KE-STARTIMES payment for 1234567890",
    "currency": "KES",
    "additionalFields": [ ],
    "acceptedCardSchemes": [ ],
    "cardPhone": "254729294292",
    "phone": "254729294292",
    "acceptedPaymentMechanisms": [ ],
    "paymentType": "EFT",
    "created": "2023-09-15T09:11:16.000Z",
    "extraInfo": "{"dtbCallingCustomerCif":"65594662-bc39-4c0d-8c7c-bc7cf6012fb9","dtbCallingCustomerId":709193,"dtbCallingCustomerOrganisation":"","dtbSourceBankCode":"","dtbSourceCountryCode":"KE","dtbSourceCurrency":"KES","dtbSourceName":"kuBQcxDilafNzey RQPgcyyEQNZdBLF","dtbSourcePhone":"254729294292","dtbSourceType":"DTB_WALLET","dtbDestinationAccountNumber":"KE-STARTIMES","dtbDestinationCurrency":"KES"}",
    "paymentInstrumentInfo": {
        "cardPhone": "254729294292"
    },
    "fee": 0,
    "paymentReference": "1234567890",
    "walletId": 830989,
    "customerId": 709193
}

Uganda VAS Providers

The following VAS providers are specific to tenants operating in Uganda.

Purchase VAS through Diamond Trust Bank

Below are the tenant configs that need to be configured for Diamond Trust Bank tenants so that Astra can make calls to DTB Uganda APIs:

dtb.config.oauthEndpoint = /dtbug/oauth/1.0/
dtb.config.clientId = VVICUoWyVpyscQdQdNdPFUjI
dtb.config.clientSecret = KAPmTTLoTGrw-zbmxBINtDgAQvzuoxGaVeKe

VAS Related Configs

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.DTBUGRechargeVasProvider
destination.wallet.config.VAS.21=${destinationWalletId}

List of VAS partners & products

Retrieve catalog items for DTB UG.

Prerequisites

A valid JWT for API calls.

GET /eclipse-conductor/rest/v1/tenants/6658/vas/catalogs?catalogQuery=21_LOCAL-CATALOG

• catalogQuery: 21_LOCAL-CATALOG

Example Response

[
    {
        "partnerId": 21,
        "partnerName": "DTBUGVasProvider",
        "providerId": 21,
        "products": [
            {
                "partnerId": 21,
                "productTypeName": "BILL",
                "productId": "NWSC",
                "productCategory": "BILL",
                "productDescription": "NWSC water payment",
                "pinnedProduct": false,
                "additionalFields": [
                    {
                        "id": "msisdn",
                        "title": "Phone number",
                        "type": "NUMERIC",
                        "regex": "^[0-9]{8,16}$"
                    }
                ]
            },
            {
                "partnerId": 21,
                "productTypeName": "BILL",
                "productId": "ETAX",
                "productCategory": "BILL",
                "productDescription": "URA Tax Returns payment",
                "pinnedProduct": false,
                "additionalFields": [
                    {
                        "id": "msisdn",
                        "title": "Phone number",
                        "type": "NUMERIC",
                        "regex": "^[0-9]{8,16}$"
                    }
                ]
            },
            {
                "partnerId": 21,
                "productTypeName": "BILL",
                "productId": "UMEME",
                "productCategory": "BILL",
                "productDescription": "Make UMEME Bill payments",
                "pinnedProduct": false,
                "additionalFields": [
                    {
                        "id": "msisdn",
                        "title": "Phone number",
                        "type": "NUMERIC",
                        "regex": "^[0-9]{8,16}$"
                    }
                ]
            }
        ]
    }
]

NWSC Bill Payment

This VAS integration is used to process water bill payments for DTB UG’s tenants. The integration will make calls to these two API’s i.e. the getCustomerDetails which provides customer details and paymentsAPI which handles the final payments processed through the Fiorano payments gateway.

Prerequisites

A valid JWT for API calls.
Valid customer reference number and area.

Step One: Query Account Details

Fetch Catalog

GET /eclipse-conductor/rest/v1/tenants/11666/vas/catalogs?catalogQuery=21_NWSC_21117391_Kampala

• catalogQuery: 21_NWSC_21117391_Kampala
• 21117391 represents the client’s reference number.
• Kampala represents the client’s area

Example Response

[
    {
        "partnerId": 21,
        "partnerName": "DTBUGVasProvider",
        "providerId": 21,
        "products": [
            {
                "partnerId": 21,
                "productId": "NWSC_21117391",
                "productName": "NWSC",
                "pinnedProduct": false,
                "additionalFields": [
                    {
                        "id": "CustRef",
                        "defaultValue": "21117391"
                    },
                    {
                        "id": "PropertyRef",
                        "defaultValue": "21/34/19/175"
                    },
                    {
                        "id": "CustName",
                        "defaultValue": "ROBERT MWESIGYE"
                    },
                    {
                        "id": "Area",
                        "defaultValue": "Kampala"
                    },
                    {
                        "id": "OutstandingBal",
                        "defaultValue": "71683"
                    },
                    {
                        "id": "CustomerError",
                        "defaultValue": "NONE"
                    },
                    {
                        "id": "msisdn",
                        "title": "Phone number",
                        "type": "NUMERIC",
                        "regex": "^[0-9]{8,16}$"
                    }
                ]
            }
        ]
    }
]

Step Two: Initiate Payment

📘
Note
The wallet type of the walletId specified in the body determines if the source of the transaction is an Eclipse wallet or a DTB Bank Account.

Initiate Payment

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments

Example Payload

{  
   "externalUniqueId":"{{$guid}}",  
   "type":"GLOBAL_VAS",  
   "paymentData":"21_NWSC_21117391",  
   "amount":71683,  
   "currency":"UGX",  
   "additionalFields":[  
      {  
         "id":"destinationBranchCode",  
         "value":"001"  
      },  
      {  
         "id":"destinationName",  
         "value":"ROBERT MWESIGYE"  
      }  
   ],  
   "walletId":206744,  
   "description":"21117391",  
   "customFraudChecks":false  
}

UMEME - Electricity Bill Payment

The purpose of this integration is to allow clients to query their UMEME account and make payments for electricity bills. This integration utilizes a single endpoint with two methods i.e. the GET method for fetching customer details and the POST method for posting the bill payment and notifying UMEME through Fiorano.

Step One: Query Account Details
Get Account Details

GET /eclipse-conductor/rest/v1/tenants/6658/vas/catalogs?catalogQuery=21_UMEME_200166426

• catalogQuery=21_UMEME_200166426
• 200166426 represents the client’s reference number.

Example Response

[
    {
        "partnerId": 21,
        "partnerName": "DTBUGVasProvider",
        "providerId": 21,
        "products": [
            {
                "partnerId": 21,
                "productId": "UMEME_200166426",
                "productName": "UMEME",
                "pinnedProduct": false,
                "additionalFields": [
                    {
                        "id": "customerRef",
                        "defaultValue": "200166426"
                    },
                    {
                        "id": "customerType",
                        "defaultValue": "POSTPAID"
                    },
                    {
                        "id": "customerName",
                        "defaultValue": "BAFUKAWA  RONALD"
                    },
                    {
                        "id": "statusDescription",
                        "defaultValue": "SUCCESS"
                    },
                    {
                        "id": "balance",
                        "defaultValue": "-21103"
                    },
                    {
                        "id": "statusCode",
                        "defaultValue": "0"
                    },
                    {
                        "id": "credit",
                        "defaultValue": "0"
                    },
                    {
                        "id": "msisdn",
                        "title": "Phone number",
                        "type": "NUMERIC",
                        "regex": "^[0-9]{8,16}$"
                    }
                ]
            }
        ]
    }
]

Step Two: Initiate Bill Payment
Initiate Payment

📘
Note
The wallet type of the walletId specified in the body determines if the source of the transaction is an Eclipse wallet or a DTB Bank Account.

POST /eclipse-conductor/rest/v1/tenants/6658/customers/184132/payments

Example Payload

{  
   "externalUniqueId":"{{$guid}}",  
   "type":"GLOBAL_VAS",  
   "paymentData":"21_UMEME_200166426",  
   "amount":29182,  
   "currency":"UGX",  
   "additionalFields":[  
      {  
         "id":"destinationBranchCode",  
         "value":"001"  
      },  
      {  
         "id":"destinationName",  
         "value":"BASEKANAKYO DEBULA"  
      },  
      {  
         "id":"destinationType",  
         "value":"UMEME_ACCOUNT"  
      },  
      {  
         "id":"destinationPhone",  
         "value":"704263087"  
      }  
   ],  
   "walletId":206744,  
   "description":"POSTPAID",  
   "customFraudChecks":false  
}

Example Response

{
    "paymentId": 142607,
    "externalUniqueId": "48d9b276-ad03-4ee9-9a4b-6377eb383502",
    "status": "PENDING",
    "amount": 29182.000000000,
    "description": "POSTPAID",
    "currency": "UGX",
    "additionalFields": [
        {
            "id": "destinationBranchCode",
            "value": "001"
        },
        {
            "id": "destinationName",
            "value": "BASEKANAKYO DEBULA"
        },
        {
            "id": "destinationType",
            "value": "UMEME_ACCOUNT"
        },
        {
            "id": "destinationPhone",
            "value": "704263087"
        }
    ],
    "acceptedCardSchemes": [],
    "acceptedPaymentMechanisms": [],
    "paymentType": "EFT",
    "created": "2024-01-26T15:14:53.000Z",
    "extraInfo": "{\"dtbCallingCustomerCif\":\"b74f7ecb-5730-4718-ab26-32cb31f9b19f\",\"dtbCallingCustomerId\":184132,\"dtbCallingCustomerOrganisation\":\"\",\"dtbSourceAccountNumber\":\"8000020000016\",\"dtbSourceBankCode\":\"\",\"dtbSourceCountryCode\":\"UG\",\"dtbSourceCurrency\":\"UGX\",\"dtbSourceName\":\"Daphine Kajoina\",\"dtbSourcePhone\":\"256775555466\",\"dtbSourceType\":\"DTB_WALLET\",\"dtbDestinationType\":\"UMEME_ACCOUNT\",\"dtbDestinationAccountNumber\":\"UMEME\",\"dtbDestinationBankCode\":\"001\",\"dtbDestinationCountryCode\":\"KE\",\"dtbDestinationCurrency\":\"UGX\",\"dtbDestinationName\":\"BASEKANAKYO DEBULA\",\"dtbDestinationPhone\":\"704263087\"}",
    "paymentInstrumentInfo": {},
    "fee": 0E-9,
    "paymentReference": "200166426",
    "walletId": 206744,
    "customerId": 184132,
    "gatewayTransactionId": "fa5acd83-9d3f-4571-b290-7f0f29c2fc8e"
}

URA Tax Payments

Step 1 – Validate PRN and get the amount owed

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs?21_ETAX_2240000621955

The catalog query is partnerId_taxUtilitCode_prn. The partner ID for DTB UG Tax payments is 21 and the utility code is ETAX.

[
    {
        "partnerId": 21,
        "partnerName": "DTBUGVasProvider",
        "providerId": 21,
        "products": [
            {
                "partnerId": 21,
                "productId": "ETAX_2240000621955",
                "productName": "ETAX",
                "pinnedProduct": false,
                "additionalFields": [
                    {
                        "id": "Prn",
                        "defaultValue": "2240000621955"
                    },
                    {
                        "id": "Tin",
                        "defaultValue": "1001307092"
                    },
                    {
                        "id": "TaxpayerName",
                        "defaultValue": "DAMBAK ENTERPRISES LIMITED"
                    },
                    {
                        "id": "Amount",
                        "defaultValue": "25000"
                    },
                    {
                        "id": "ExpiryDt",
                        "defaultValue": "08-FEB-24"
                    },
                    {
                        "id": "StatusCode",
                        "defaultValue": "T"
                    },
                    {
                        "id": "StatusDesc",
                        "defaultValue": "RECEIVED AND CREDITED"
                    },
                    {
                        "id": "Currency"
                    },
                    {
                        "id": "PaymentRegDt",
                        "defaultValue": "20-NOV-23"
                    },
                    {
                        "id": "IsSentToBank",
                        "defaultValue": "Y"
                    },
                    {
                        "id": "msisdn",
                        "title": "Phone number",
                        "type": "NUMERIC",
                        "regex": "^[0-9]{8,16}$"
                    }
                ]
            }
        ]
    }
]

Step 2 - Initiate a Payment

📘
Note
The wallet type of the walletId specified in the body determines if the source of the transaction is an Eclipse wallet or a DTB Bank Account.

paymentData field is {partnerId} {taxUtilitCode} {prn}. The partner ID for DTB UG Tax payments is 21 and the utility code is ETAX.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments	
{
   "externalUniqueId":"{{$guid}}",
   "type":"GLOBAL_VAS",
   "paymentData":"21_ETAX_1001307092",//append with TIN
   "amount":25000,
   "currency":"UGX",
   "additionalFields":[
      {
         "id":"destinationBranchCode",
         "value":"001"
      },
      {
         "id":"destinationName",
         "value":"DAMBAK ENTERPRISES LIMITED"
      }
   ],
   "walletId":207016,
   "description":"2240000621955",
   "customFraudChecks":false

}

{
    "paymentId": 150417,
    "externalUniqueId": "6797d402-1734-46f3-8066-73a3a2bc3860",
    "status": "PENDING",
    "amount": 25000.000000000,
    "description": "2240000621955",
    "currency": "UGX",
    "additionalFields": [
        {
            "id": "destinationBranchCode",
            "value": "001"
        },
        {
            "id": "destinationName",
            "value": "DAMBAK ENTERPRISES LIMITED"
        }
    ],
    "acceptedCardSchemes": [],
    "acceptedPaymentMechanisms": [],
    "paymentType": "EFT",
    "errorDescription": ": ",
    "created": "2024-02-02T13:00:16.000Z",
    "extraInfo": "{\"dtbCallingCustomerCif\":\"a7cfe6d1-dc34-4e56-b537-0a0ac21b3bde\",\"dtbCallingCustomerId\":723689,\"dtbCallingCustomerOrganisation\":\"\",\"dtbSourceAccountNumber\":\"7053960002\",\"dtbSourceBranchCode\":\"001\",\"dtbSourceBankCode\":\"\",\"dtbSourceCountryCode\":\"UG\",\"dtbSourceCurrency\":\"UGX\",\"dtbSourceName\":\"James Madison\",\"dtbSourcePhone\":\"27987654321\",\"dtbSourceType\":\"DTB_BANK_ACCOUNT\",\"dtbDestinationBankCode\":\"001\",\"dtbDestinationCountryCode\":\"UG\",\"dtbDestinationCurrency\":\"UGX\",\"dtbDestinationName\":\"DAMBAK ENTERPRISES LIMITED\"}",
    "paymentInstrumentInfo": {},
    "fee": 0E-9,
    "paymentReference": "1001307092",
    "walletId": 207016,
    "customerId": 723689
}

Typically you will immediately receive a PENDING response. If the callback URL was populated a callback will be sent to that URL when the payment is finalised (either successful or error). Alternatively, a call can be made to the GET payment by paymentId endpoint.

Fund your MTN wallet through DTB Uganda

Prerequisites

A valid JWT for API calls.

Property
Below are the tenant configs that need to be configured for transferring funds to an MTM Mobile Money Wallet through Diamond Trust Bank:

mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.DTBUGRechargeVasProvider
destination.wallet.config.VAS.XX=${destinationWalletId}

Step1 Validate the MTN number

	GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs?21_MTN_256779999703

The catalog query is partnerId_taxUtilitCode_customerRef. Partner ID for DTB MTN wallet topup is 21 and the utility code is MTN. 21_MTN_256779999703

Step2 Initiate a Payment

POST: /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments
{
  "externalUniqueId": "9c04cede-e105-488b-9211-ab21bf3e1db9",
  "type": "GLOBAL_VAS",
  "paymentData": "21_MTN_256779999703",
  "amount": 29182,
  "currency": "UGX",
  "additionalFields": [
    {
      "id": "destinationBranchCode",
      "value": "001"
    },
    {
      "id": "destinationName",
      "value": "Martha N"
    },
    {
      "id": "destinationType",
      "value": "MTN_WALLET"
    },
    {
      "id": "destinationPhone",
      "value": "256779999703"
    }
  ],
  "walletId": 204142,
  "description": "Transfer from bank to wallet",
  "customFraudChecks": false
}

{
    "paymentId": 172565,
    "externalUniqueId": "2b204a21-d686-489e-980c-9c1ff3c1ca1a",
    "status": "PENDING",
    "amount": 29182.000000000,
    "description": "Transfer from bank to wallet",
    "currency": "UGX",
    "additionalFields": [
        {
            "id": "destinationBranchCode",
            "value": "001"
        },
        {
            "id": "destinationName",
            "value": "Martha N"
        },
        {
            "id": "destinationType",
            "value": "MTN_WALLET"
        },
        {
            "id": "destinationPhone",
            "value": "256779999703"
        }
    ],
    "acceptedCardSchemes": [],
    "acceptedPaymentMechanisms": [],
    "paymentType": "EFT",
    "errorDescription": ": ",
    "created": "2024-02-21T07:31:33.000Z",
    "extraInfo": "{\"dtbCallingCustomerCif\":\"a7cfe6d1-dc34-4e56-b537-0a0ac21b3bde\",\"dtbCallingCustomerId\":723689,\"dtbCallingCustomerOrganisation\":\"\",\"dtbSourceAccountNumber\":\"7115418418\",\"dtbSourceBranchCode\":\"001\",\"dtbSourceBankCode\":\"\",\"dtbSourceCountryCode\":\"UG\",\"dtbSourceCurrency\":\"UGX\",\"dtbSourceName\":\"James Madison\",\"dtbSourcePhone\":\"27987654321\",\"dtbSourceType\":\"DTB_WALLET\",\"dtbDestinationType\":\"MTN_WALLET\",\"dtbDestinationAccountNumber\":\"MTN\",\"dtbDestinationBankCode\":\"001\",\"dtbDestinationCountryCode\":\"UG\",\"dtbDestinationCurrency\":\"UGX\",\"dtbDestinationName\":\"Martha N\",\"dtbDestinationPhone\":\"256779999703\"}",
    "paymentInstrumentInfo": {},
    "fee": 0E-9,
    "paymentReference": "256779999703",
    "walletId": 204142,
    "customerId": 723689,
    "paymentTerminalData": {}
}

Global VAS providers

The following VAS providers are not specific to any region.

Purchase VAS from Cellulant

Introduction

Cellulant services to integrate with Eclipse as an open feature platform. It has an extensive catalog of API’s available for tenants to manage the Transfer money, Refunds, Pay various bills, Vend airtime and data bundles. Cellulant supported multiple services in many countries/regions.

Prerequisites

A valid JWT for API calls.
Eclipse provides global vas catalogs for tenants.

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

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs.

Step 1 – Create Json
First create a json file based on provided service codes for a particular country. Added those json data in the property table against mobilerecharge.cellulant.bundles.{tenantId} key. Defined country code for selected tenant. (i.e. cellulant.config.countryCode={countryCode})

Step 2 - Fetch vas Catalogs

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/vas/catalogs.

Based on tenantId return all the service codes as a catalogs from configured json data. Choose a voucher from catalogs list and prepare one catalog query for selected services.

Step 3 - Prepare CatalogQuery

GET /eclipse-conductor/rest/v1/tenants/242/vas/catalogs?catalogQuery=17_254707720002_042381176772_KE-DSTV

17 - partnerId for cellulant
254707720002 - Mobile number, If not available then pass 0
042381176772 - Account number
KE-DSTV - Service code

Based on catalogQuery they returned products for defined service. Select productid from catalogs to further initiate the payment process (i.e., "productid": "254707720002_042381176772_KE-DSTV_DSTVTESTKE")

Step 4 - Initiate Making a Payment by a Customer

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments
{
  "additionalFields": [
    {
      "id": "msisdn",
      "value": "xxxxxxxxxxxxx"
    }
  ],
  "landingUrl": "https://www.google.com/",
  "callbackUrl": "http://www.blankwebsite.com",
  "externalUniqueId": "abcd1234a",
  "paymentData": "17_254707720002_042381176772_KE-DSTV_DSTVTESTKE",
  "type": "GLOBAL_VAS",
  "currency": "ZAR",
  "walletId": XXX
}

So here paymentData it could be (i.e. 17_254707720002_042381176772_KE-DSTV_DSTVTESTKE)
17 - PartnerId
254707720002_042381176772_KE-DSTV_DSTVTESTKE - productId

In response getting paymentId & amount along with all required extra information.

Step 5 - Update Necessary Fields for Payment

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/payments/{paymentId}
Passed tenantId and paymentId for update payment along with below request payload.
{
  "amount": 517,
  "walletId":476,
  "landingUrl": "https://www.google.com/"
}

Cellulant returns a success response string once successful payment.

VAS Use Cases

South Africa VAS providers

Purchase VAS from Scan to Pay

Purchase VAS from ACS

Electricity VAS purchases via ACS

Purchase VAS from Kganya

Purchase VAS from Pay@

Purchase VAS from EasyPay

Kenya VAS providers

Pay Tax through Diamond Trust Bank

📘
Note

Purchase VAS through Diamond Trust Bank

📘
Note

Uganda VAS Providers

Purchase VAS through Diamond Trust Bank

List of VAS partners & products

NWSC Bill Payment

📘
Note

UMEME - Electricity Bill Payment

📘
Note

URA Tax Payments

📘
Note

Fund your MTN wallet through DTB Uganda

Global VAS providers

Purchase VAS from Cellulant

South Africa VAS providers

Purchase VAS from Scan to Pay

Purchase VAS from ACS

Electricity VAS purchases via ACS

Purchase VAS from Kganya

Purchase VAS from Pay@

Purchase VAS from EasyPay

Kenya VAS providers

Pay Tax through Diamond Trust Bank

📘Note

Purchase VAS through Diamond Trust Bank

📘Note

Uganda VAS Providers

Purchase VAS through Diamond Trust Bank

List of VAS partners & products

NWSC Bill Payment

📘Note

UMEME - Electricity Bill Payment

📘Note

URA Tax Payments

📘Note

Fund your MTN wallet through DTB Uganda

Global VAS providers

Purchase VAS from Cellulant

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note