Integration Guides

Top-Up Use Cases

Suggest Edits

Wallets are most useful when they have money in them. This money can come from incoming payments, or the customer topping them up directly with their own money - be it cash, card or EFT. Eclipse has multiple integrations with partners to simplify and provide numerous top up mechanisms for a tenants customers. Eclipse integrates into multiple payment gateways and retailers and provides a single API to tenants. As a Tenant or Organisation, if you use your own internal Top up methods, then a Wallet to Wallet transfer should be used.

Please refer to this Miro Topup Flow Diagram for specific flows, funds and fee movements per top-up type.

The overall process depends on the type of top up. This could result in an iframe being presented to the customer to enter card details for topping up, or could return a token for topping up at a retail store (e.g. PnP). Please refer to the indivdual topup types below for the specifics of each use case.

Handling top-up for wallets

Customer doing top-up for any wallet with any top-up type either from eft and from any other wallet at that time if specific wallet is in BARRED/CANCELLED/LOCKED/PENDING STATUS then the top-up is not going be successful and there will be a upfront validation display as:

The Top-up wallet is not currently in an active state. Current state of wallet is-- 2

South Africa Topup Types

The following topup types are specific to tenants operating in South Africa.

Topup Type: EFT into Pool account

A customer can get funds directly into their wallets by way of doing a standard EFT into the tenant Pool bank account with the wallet’s Unique Reference(‘friendlyId’) as the EFT reference.

Managing Unallocated EFT/ATM Deposits at Tenant Level

To efficiently manage unallocated EFT and ATM deposits within tenant, follow these steps to set up and configure the process. These steps enable you to control the allocation of funds and handle specific scenarios where you might need to exclude certain deposits from being allocated to the unallocated deposits wallet.

  1. Create an Unallocated Deposits Wallet
    Initiate the process by establishing a dedicated destination wallet at the tenant level. This wallet (example wallet name "unallocatedDepositsWallet") will serve as a repository for unallocated funds. Ensure that you retain the associated walletId for future reference and configuration adjustments.
  2. Configure Tenant Pool Account Number
    Set the pool account number by setting the "poolAccountNumber" tenant config. format: poolAccountNumber = <pool_account_number_of_tenant>. This account number is pivotal for the overall allocation process.
    i.e. tenant.config.1=poolAccountNumber=123456789
  3. Configure Unallocated Deposits Wallet ID
    Within the same tenant configuration, define the "unallocatedDepositsWalletId" parameter. This parameter will hold the wallet ID from Step 1. Utilize the following format: unallocatedDepositsWalletId = <wallet_id_of_unallocatedDepositsWallet_created_in_step1>. This connection facilitates the proper allocation of funds.
    i.e. unallocatedDepositsWalletId=5

An important consideration is the automated transfer of funds. If the last four digits of the tenant's pool account number align with the deposit bank account number, the system will seamlessly route funds into the designated "unallocatedDepositsWallet." This feature streamlines the allocation process, ensuring efficient fund management.

Configurable Payment Reference Exclusions:
In scenarios where specific funds should not be allocated to the unallocated deposits wallet, tenants have the flexibility to tailor their preferences. By utilizing the configuration parameter "unallocated.deposit.reference.exclusion.regex," tenants can define exclusion references based on a regular expression pattern. For instance, references such as "NEDLNK," "PNP," "Topups," and "UT - Current" can be marked for exclusion, ensuring these funds are not directed to the unallocated wallet.

Global level config.
i.e. unallocated.deposit.reference.exclusion.regex=(?i)(NEDLNK|PNP|Topups|UT - Current)

ZA_OZOW

Introduction
The Ozow Top-Up API allows you to build Ozow's real-time EFT functionality directly into Eclipse. This integration method gives you more flexibility but would require more effort than using the Ozow hosted method.

Ozow API Endpoints
Staging
Production

Prerequisites

  • A valid JWT for API calls
  • walletId

Required configuration before getting started:

  • sd.external.services=REST,OzowAPI,https://stagingapi.ozow.com,^/ozow-api, , ,0,0, ,/ozow-api
  • tenant.config.
  • ozow.payment.config.siteCode=TSTSTE0001
  • ozow.payment.config.countryCode=ZA
  • ozow.payment.config.privateKey=215114531AFF7134A94C88CEEA48E
  • ozow.payment.config.apiKey=EB5758F2C3B4DF3FF4F2669D5FF5B
  • ozow.payment.config.generateShortUrl=true
  • ozow.payment.config.enableTestEnvironment=falseconfig.Pay
  • fees.amount.config.Pay.ZA_OZOW=0.1P | Fees for doing an ozow
  • fees.wallet.config.ZA_OZOW={WalletID} | Wallet ID to credit for fees charged for ozow
  • source.wallet.config.ZA_OZOW={WalletID} | Wallet ID to debit when a customer receives funds via ozow
  • fees.wallet.config.Pay.ZA_OZOW={WalletID} | Wallet ID to credit for fees charged for Ozow cash deposits

Test Data:
Select Demo Bank
Username: [email protected]
Bank password: T3mpP@ssw0rd
OTP:12345

📘

Note

The above credentials are for the staging/test Ozow environment.

For production credentials a contract and account must be setup between the tenant and Ozow directly. Please get in touch with [email protected] to initiate this process.

Initiate Top-Up Process
The overall process depends on the type of top up. This could result in an iframe being presented to the customer to enter card details for topping up. For Ozow we added a type as a ZA_OZOW.

POST/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups
Request:
{
  "amount": 10.00,
  "callbackUrl": "https://www.google.com/",
  "externalUniqueId": "P8dN242testdsa",
  "landingUrl": "https://www.google.com/",
  "type": "ZA_OZOW"
}
Response:
{
  "topupId": xxxx,
  "completionUrl": "https://stagingpay.ozow.io/p/53S954Ie90d",
  "status": "PENDING"
}

The returned completionUrl field should be used to complete the payment process through Ozow - this includes:

  • Selecting the bank you wish to pay with your bank account.
  • Logging in with your selected bank account profile. I.e., username and password.
  • Entering an OTP to finalise your payment.

Once the Ozow payment process is completed the user will be redirected back to the URL specified in the landingUrl parameter.

ZA_MASTERPASS_CARD

This option allows customers to fund their wallets through card rail payments in South Africa. There are 3 ways in which the card details can be provided:

  1. If the tenant backend system is PCI compliant then the card details can be passed directly in the request in the topupCardData field
  2. The card details can be stored as a card on file and the cardOnFileId field populated with the identifier of the card on file - please see Card On File Management for details on adding cards on file. The tenant does not need to be PCI compliant.
  3. The request can be made without a topupCardData or cardOnFileId - in this case a completionUrl will be returned in the response. The completionUrl can be served in an iFrame and will take the user to a captive portal within the Ukheshe PCI environment where customers can enter in their card details. Please see Customisation of the Captive Portal UI for details on customising this page. The tenant does not need to be PCI compliant.

Prerequisites

  • A valid JWT for API calls
  • walletId

Top ups are initiated using the Wallet Topups endpoint with type set to ZA_MASTERPASS_CARD:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups
{
"externalUniqueId": "d5901f6d-e0f8-42b7-9e24-cf348933dc77",
"amount": 55,
"landingUrl": "https://eclipse-portal-admin-sandbox.ukheshe.rocks/admin-portal/tenants/wallets/topup-detail",
"topupData": "",
"type": "ZA_MASTERPASS_CARD"
}

Below is an example response body:

{
	"topupId": 59635,
	"completionUrl": "https://eclipse-java-sandbox.ukheshe.rocks/t/c4gr9",
	"status": "PENDING"
}

ZA_PNP_CASH

This option allows customers to fund their wallets by initiating a wallet top-up on the PWA or any supported touch point. The customer will have to pick the top-up type as ZA_PNP_CASH, specify the preferred top-up amount, and then request for a token.

Prerequisites

  • A valid JWT for API calls
  • walletId

Initiate topup using the topup endpoint:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups 
{
  "amount": 55,
  "externalUniqueId": "1c969f7e-9bb2-40d8-ba6c-0ddacc616d6b",
  "landingUrl": "https://eclipse-portal-admin-sandbox.ukheshe.rocks/admin-portal/tenants/wallets/topup-detail",
  "topupData": "",
  "type": "ZA_PNP_CASH"
}

Example response body:

{
  "topupId": 74012,
  "completionToken": "152050197",
  "status": "PENDING"
}

📘

Note

When the customer deposits at PnP, the top-up will be successful immediately, however should potential fraud be detected, a reservation is applied to the wallet for the deposit amount valid for 24 hours as a fraud prevention measure; meaning the funds can only be used after 24 hours.

The token returned in the completionToken field can be displayed to the user in the application and/or sent via SMS. The customer then needs to present the completionToken and the topup cash amount to a PicknPay teller to complete the wallet top-up process.

By default, PicknPay tokens are set to expire at the end of the day after the token was generated. When generating a token the expiry can also be explicitly specified by setting the expires field. However, if the expiry is specified, that expiry must be lower than the default to expire at the end of the day after it was issued.

To simulate a successful topup on the sandbox environment (as there is no PnP sandbox where tokens can be submitted as paid), use an amount of 101. This will tell the system to pretend the customer has paid the PnP token 10s after it was requested. This way, one would get the callbacks and the topup would change to SUCCESSFUL. E.g. use "amount":101

Similarly, if the amount is 102 then the PnP topup will be simulated as an expiry 10s after creation so that one would not wait for 1-2 days for an expiry simulation event.

Any other amounts will expire at the end of the next day.

Suggested prompts to guide customers for PicknPay Cash Top-ups

To ensure a satisfactory customer experience we suggest that the following or similar prompts be included in any PicknPay cash topup customer journeys:

  1. Highlight the associated fees and minimum/maximum top-up amounts - the minimum/maximum topup amount at PicknPay is R50 and R3000 respectively.
  2. Include these steps to deposit money at any Pick n Pay teller:
    1. From the menu select "Value Added Services"
    2. Select "Mobile"
    3. Select "Topup"
    4. Select "Ukheshe"
    5. Provide the amount and topup token/reference number.

📘

Note

Only whole values are supported by PnP top-ups. Decimal/Cent values are not accepted.

Kenya Topup Types

The following topup types are specific to tenants operating in Kenya.

KE_DTB_STK_PUSH

This top mechanism can be used on DTB Kenya tenants to top up via a request for payment to the customer's MPESA mobile number (phone1 on their profile) using the USSD Sim tool kit. The customer's phone will receive a USSD push message asking for confirmation to make the payment. If accepted, the amount would be debited off the customer's MPESA wallet and credited to the wallet they are topping up.

The transaction would start as PENDING and then transition to either SUCCESSFUL or ERROR_PERM when done. This can take up to 10s depending on how quickly the request is processed on the phone.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups
Request:
{
  "amount": 10.00,
  "externalUniqueId": "P8dN242testdsa",
  "type": "KE_DTB_STK_PUSH"
}
Response:
{
  "topupId": xxxx,
  "status": "PENDING"
}

KE_DTB_MPESA_PROMPT

This topup can be used by Kenya tenants to request and receive a payment from an MPESA mobile number using USSD Sim tool kit. This payment type allows payments to an Eclipse Wallet or to a DTB Bank ccount to a DTB bank account using the below API.

Prerequisites

  • Valid JWT
  • Destination Account Details
  • Gateway specified in the 'type' query parameter to KE_DTB_MPESA_PROMPT

📘

Note

The wallet type of the walletId specified in the URL path determines if the destination for the top up is an Eclipse wallet or a DTB Bank Account.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups
{
    "amount": 100,
    "type": "KE_DTB_MPESA_PROMPT",
    "externalUniqueId": "efe5c6e3-4877-47eb-931e-ee22fb08ed11"
}

	
{
    "topupId": 443224,
    "status": "PENDING"
}

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

KE_DTB_AIRTEL_PROMPT

This topup can be used by Kenya tenants to request and receive a payment from an Airtel mobile number using USSD Sim tool kit. This payment type allows payments to an Eclipse Wallet or to a DTB Bank ccount to a DTB bank account using the below API.

Prerequisites

  • Valid JWT
  • Destination Account Details
  • Gateway specified in the 'type' query parameter to KE_DTB_AIRTEL_PROMPT

📘

Note

The wallet type of the walletId specified in the URL path determines if the destination for the top up is an Eclipse wallet or a DTB Bank Account.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups
{
    "amount": 100,
    "type": "KE_DTB_AIRTEL_PROMPT",
    "externalUniqueId": "32664ca3-bf41-4181-8440-331d6e53be9f"
}

	
{
    "topupId": 443226,
    "status": "PENDING"
}

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

Updated 23 days ago