Integration Guides

Top-Up Use Cases

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.

📘

Note

When a customer attempts to top up any wallet—regardless of top-up type, whether via EFT or from another wallet—an upfront validation occurs if the target wallet is in a BARRED, CANCELLED, LOCKED, or PENDING state.

South Africa Topup Types

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

EFT into Pool account

A customer can add funds directly to their wallet by performing a standard EFT into the tenant’s pool bank account, using 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: [[demo@ozow.com](demo@ozow.com)](mailto:dev@i-pay.co.za)
Bank password: T]+&{.t,ywH8
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 onboarding@eftcorp.com 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 EFT Corporation 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 "EFT Corporation"
    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).

Ghana Topup Types

The following top-up types are specific to tenants operating in Ghana.

GH_CBG_TELLER_CASHIN

The Teller Cashin Top-Up functionality will allow CBG's bank tellers to initiate card wallet top-ups on behalf of customers via the Eclipse Admin Portal. This feature ensures a secure and controlled transaction flow by integrating with CBG’s Enterprise Service Bus (ESB), where the teller's credentials are authenticated before processing the deposit.

Prerequisites

  • Valid JWT
  • Destination Account Details (A static account to be used for tracking top-ups on the core banking system.)
  • Valid teller credentials must be provided, where the identity on Eclipse matches the username maintained in the Core Banking System.
  • Gateway specified in the 'type' query parameter to GH_CBG_TELLER_CASHIN
POST {baseurl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups

{
    "additionalFields": [
        {
            "id": "currencyDenominations",
            "value": "DENOM10:1|DENOM5:1"
        }
    ],
    "amount": 15,
    "externalUniqueId": "{{$guid}}",
    "type": "GH_CBG_TELLER_CASHIN"
}
{
    "topupId": 3429816,
    "status": "SUCCESSFUL",
    "additionalFields": [
        {
            "id": "currencyDenominations",
            "value": "DENOM10:1|DENOM5:1"
        },
        {
            "id": "accountNumber",
            "value": "1369995600001"
        }
    ]
}

The final status is returned from CBG's core banking system in near real-time. If a successful response is returned, funds will be transferred from the designated source wallet to the client's card-enabled digital wallet on Eclipse.

GH_CBG_MOMO

GH_CBG_MOMO allows a customer to top up their Eclipse wallet by initiating a pull from their Ghana mobile money account via the Central Bank of Ghana (CBG) Mobile Money Bridge Service. The customer's registered mobile money number and network operator are used to debit the mobile money account and credit the linked Eclipse wallet.

Supported mobile network operators: MTN, Vodafone, AirtelTigo.

The wallet's account number and the customer's registered phone number are retrieved automatically from the wallet and customer record — they do not need to be supplied in the request.

Prerequisites

  • Valid JWT
  • Customer must have a registered phone1 on their Eclipse profile — this is used as the mobile money source number
  • Mobile network operator specified in additionalFields as provider
  • Gateway specified in the type field as GH_CBG_MOMO

Required tenant configuration:

  • cbg.momo.config.apiKey={key} — CBG API key
  • cbg.momo.config.TCsServiceURL={url} — CBG Bridge Service URL
POST {baseurl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/topups
Content-Type: application/json
Authorization: Bearer {jwt}

{
    "amount": 50.00,
    "externalUniqueId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "type": "GH_CBG_MOMO",
    "additionalFields": [
        {
            "id": "provider",
            "value": "MTN"
        }
    ]
}
{
    "topupId": 394828,
    "status": "PENDING"
}

You will receive a PENDING response immediately. The top-up is processed asynchronously. If a callbackUrl was provided, a callback will be sent when the top-up is finalised (SUCCESSFUL or ERROR_PERM). Alternatively, poll the top-up by ID to check the final status.

The provider value in additionalFields maps to the mobile network operator that holds the customer's mobile money wallet. This must match the network of the phone number registered on the customer's Eclipse profile.

Updated 4 months ago

Did this page help you?