Withdrawal Use Cases

A time will come when a customer wants to move money off the Eclipse ecosystem into a bank or cash. Eclipse facilitates this process through numerous integrations for withdrawing cash and electronically moving money into traditional bank accounts. The numerous integrations are consolidated into a single simple API for initiating a withdrawal. Strict rules are enforced based on the authenticated user doing the withdrawal and their relationship to the wallet being debited. This is based on who the wallet is owned by, or in the case of an organisation, what position the caller holds in that organisation. There are also rules based on the wallet type which determine if the tenant system API calls have authorisation to perform withdrawals on their customer's wallets

Please refer to this Miro Eclipse Withdrawal Flows Diagram for specific flows, funds and fee movements per withdrawal type.

The overall process depends on the type of withdrawal. This could return a token for withdrawal at a retail store (e.g. PnP) or kick off an EFT. Please refer to the individual withdrawal types below for the specifics of each use case.

South Africa Withdrawal Types

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

ZA_NEDBANK_EFT/ ZA_NEDBANK_EFT_IMMEDIATE

Withdraw the amount from your wallet to your Nedbank account using withdrawal types ZA_NEDBANK_EFT or ZA_NEDBANK_EFT_IMMEDIATE. The configuration is very similar for both types except for fees. Please refer to the Configuration section for more details on fees.

The main difference between ZA_NEDBANK_EFT and ZA_NEDBANK_EFT_IMMEDIATE is that ZA_NEDBANK_EFT_IMMEDIATE settles the amount in your Nedbank account within 05-60 minutes(If any technical problem occurs it may take longer). While ZA_NEDBANK_EFT takes one day to settle your amount in a Nedbank account.

ZA_NEDBANK_EFT_IMMEDIATE timings:

Monday to Friday: 12:00 AM to 13:00 PM (SAST)
Saturday: 12:00 AM to 09:00AM (SAST)
Sunday/Public holiday: Will be settled in the next working day.

ZA_NEDBANK_EFT timings:

Monday to Friday: 12:00 AM to 15:00 PM (SAST)
Saturday: 12:00 AM to 09:00AM (SAST)
Sunday/Public holiday: Will be settled in the next working day.

Below is an example request initiated using the wallet withdrawals endpoint:

POST: http://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
	"accountName":"My Account",
	"accountNumber":"1234567890",
	"amount":50,
	"bank":"Acme Bank",
	"bankCountry":"ZA",
	"branchCode":"1234456",
	"callbackUrl":"https://url.to.call.on.completion",
	"description":"Withdrawal EFT",
	"externalUniqueId":"55dca6b1-e789-4f14-8929-f3e44f15ef6c",
	"reference":"EFT withdrawal 1234566-ed89-4f44-8959-f3e",
	"type":"ZA_NEDBANK_EFT"
}

A typical response body is below. When the withdrawal is finalised (either successful or error) the EclipseWalletWithdrawal will be posted to the provided callbackURL:

{
	"withdrawalId":8491,
	"externalUniqueId":"55dca6b1-e789-4f14-8929-f3e44f15ef6c",
	"status":"PENDING",
	"expires":"2100-01-01T00:00:00.000Z",
	"amount":50.000000000,
	"currency":"ZAR",
	"gateway":"ZA_NEDBANK_EFT",
	"type":"EFT",
	"subType":"NORMAL",
	"walletId":12345,
	"fee":5.000000000,
	"created":"2023-05-04T11:07:59.000Z",
	"extraInfo":
	{
		"branchCode":"1234456",
		"accountNumber":"1234567890",
		"accountName":"My Account"
	}",
	"reference":"EFT withdrawal 1234566-ed89-4f44-8959-f3e",
	"description":"Withdrawal EFT",
	"deliverToPhone":"2773123456"
}

📘
Note
You can retrieve a list of South African valid banks and branch codes by retrieving publicly available global config public.bank.list using the global config API.

ZA_PAYCORP_ATM

This use case deals with facilitating cardless withdrawals from wallets managed by Ukheshe, via Paycorp Cash Express ATMs in South Africa.

Below is an example of the request:

POST /eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
"amount": "100"
"deliverToPhone":"xxxxxxxx"
"externalUniqueId": "dbe5e61c-d98a-403f-8bfe-34d084bafb7d"
"type": "ZA_PAYCORP_ATM"
}

Below is an example of the response:

{
"amount": "100"
"created": "2023-01-30T10:06:49.000Z"
"currency": "ZAR"
"deliverToPhone": "xxxxxxxxx"
"description": "Cash Express  ATM withdrawal"
"expires": "2023-01-31T10:06:48.720Z"
"externalUniqueId": "dbe5e61c-d98a-403f-8bfe-34d084bafb7d"
"fee": "10"
"gateway": "ZA_PAYCORP_ATM"
"status": "PENDING"
"subType": "NORMAL"
"token": "504041"
"type": "ATM"
"walletId": "xxxxxx"
"withdrawalId": "xxxx"
}

In additional an SMS can be sent to the user notifying them of the withdrawal request and including the withdrawal token. For the SMS to be sent the permission Notification.CREATE.Allowed needs to be enabled for the user that initiates the withdrawal request (typically this is the TENANT_SYSTEM user).

A custom SMS template that contains the token to be used at the ATM can be created by setting global property
mustache.sms.withdrawal.ZA_PAYCORP_ATM.{tenantId}.

Here is an example of an SMS template:

#UrlDataSource: user=/rest/v1/users/{{data.withdrawal.userId}}
#To: {{user.phone1}}
You've requested to withdraw R{{#round0}}{{data.withdrawal.amount}}{{/round0}} at a Cash Express ATM! You reference number {{data.withdrawal.token}} expires at {{#dateTime}}{{data.withdrawal.expires}}{{/dateTime}}.

Suggested Customer Prompts

To ensure a satisfactory customer experience we suggest that the following prompts be included in any Cash Express ATM cardless withdrawal customer journeys:

Display the token/OTP, amount and expiry date of the token/OTP
Highlight the associated fees and minimum/maximum withdrawal amounts

📘
Note
The minimum withdrawal amount for PayCorp Cash Express ATMs is R50. However this is dependent on ATMs and in some cases the ATMs only allow withdrawal increments of R100 so we suggest that a withdrawal minimum of R100 is indicated in the customer journey. The maximum withdrawal amount is R3000.

Provide a mechanism for users to locate their nearest Cash Express ATM. For retrieving the ATM locations the global property public.atm.list needs to be called:

GET /eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/global/config/public.atm.list

📘
Note
We also suggest including a Cash Express logo in the customer journey to aid with locating the ATMs:

Once at a supported ATM to do a cardless withdrawal follow these steps:
1. Select "cardless transactions"
2. Enter the phone number
3. Enter the provided token/OTP
4. Enter the amount

ZA_PNP_CASH

This withdrawal use case allows customers to withdraw cash from PicknPay retailer by requesting a withdrawal token/reference number. The customer can then present the reference number at a PicknPay retailer to receive the cash.

Prerequisites

A valid JWT for API calls
walletId

Initiate withdrawal using the withdrawal endpoint:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
  "amount": 55,
  "description": "Test PnP withdrawal",
  "type": "ZA_PNP_CASH",
  "externalUniqueId": "b8c7ccf0-f544-427b-8478-fe1dc6d50ffb"
}

Example response body:

{
  "withdrawalId": 2761462,
  "externalUniqueId": "b8c7ccf0-f544-427b-8478-fe1dc6d50ffb",
  "status": "PENDING",
  "token": "144745417",
  "expires": "2023-11-18T21:59:59.000Z",
  "amount": 55,
  "currency": "ZAR",
  "gateway": "ZA_PNP",
  "type": "CASH",
  "subType": "NORMAL",
  "walletId": 1371283,
  "fee": 10,
  "created": "2023-11-17T18:41:25.000Z",
  "description": "Test PnP withdrawal",
  "deliverToPhone": "27723812365",
  "lastModified": "2023-11-17T18:41:25.000Z"
}

The token returned in the token field can be displayed to the user in the application and/or sent via SMS. The customer then needs to present the token to a PicknPay teller to complete the wallet withdrawal 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.

Suggested prompts to guide customers for PicknPay Cash withdrawals

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

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

A custom SMS template that contains the token to be used at the Pnp cash can be created by setting global property
mustache.sms.withdrawal.ZA_PNP_CASH.{tenantId}

📘
Note
Only whole values are supported by PnP withdrawal. Decimal/Cent values are not accepted.


#UrlDataSource: user=/rest/v1/users/{{data.withdrawal.userId}}
#To: {{user.phone1}}
You've requested to withdraw R{{#round0}}{{data.withdrawal.amount}}{{/round0}} at a Pnp cash! You reference number {{data.withdrawal.token}} expires at {{#dateTime}}{{data.withdrawal.expires}}{{/dateTime}}.

ZA_PNP_TENDER

This use case deals with facilitating customers to any Pick n Pay till point and tell the cashier for a gift card. Bring the exact amount in cash and the reference number in your confirmation SMS. Get your receipt and wait for an SMS confirming that your money transfer was successful.

ZA_AFRICANBANK_EFT (Sandbox only)

Withdraw the amount from your wallet to your African account using withdrawal types ZA_AFRICANBANK_EFT. The configuration is very similar to nedbank eft. Please refer to the Configuration section for more details on fees.

ZA_AFRICANBANK_EFT timings:

Monday to Friday: 12:00 AM to 15:00 PM (SAST)
Saturday: 12:00 AM to 09:00AM (SAST)
Sunday/Public holiday: Will be settled in the next working day.

POST: http://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
	"accountName":"My Account",
	"accountNumber":"51010000005",
	"amount":50,
	"bank":"Acme Bank",
	"bankCountry":"ZA",
	"branchCode":"410105",
	"callbackUrl":"https://url.to.call.on.completion",
	"description":"Withdrawal EFT",
	"externalUniqueId":"55dca6b1-e789-4f14-8929-f3e44f15ef6c",
	"reference":"EFT withdrawal 1234566-ed89-4f44-8959-f3e",
	"type":"ZA_AFRICANBANK_EFT"
}

Note: If the beneficiary's account number falls within the range of the Eclipse AB account numbers, an internal transfer will be initiated. If the destination account number belongs to the same tenant, a simple transfer will be triggered. However, if the destination account number is associated with a different tenant, a cross-tenant transfer will be initiated.

Kenya Withdrawal Types

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

KE_DTB_EFT

EFT withdrawal used in case of withdrawing money from an Eclipse Wallet or from a DTB Bank ccount to a DTB bank account using the below API.

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to KE_DTB_EFT

Required tenant configuration:

fees.amount.config.Wdr.KE_DTB_EFT.EFT.NORMAL=0.1P | Fees logic
fees.wallet.config.Wdr.KE_DTB_EFT.EFT.NORMAL={WalletID} | Wallet ID to credit for fees charged
destination.wallet.config.KE_DTB_EFT.EFT.NORMAL={WalletID} | Wallet ID to credit when a customer withdraws funds

EFT withdrawal used in case of withdrawing money from an eclipse wallet to a DTB bank account using the below API.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
  
 {"accountName":"Ukheshe","accountNumber":"5113889006","reference":"2356kj","branchCode":"052","amount":106,"description":"testing for dtb eft-2","type":"KE_DTB_EFT","externalUniqueId":"uututu58484-448484-848484"}

📘
Note
For new integrations withdrawal type KE_DTB_IFT should be used

KE_DTB_MPESA

This use case deals with transferring money to MPesa mobile phone wallet with input of a mobile number and transferring money out of the customer eclipse wallet to calling MPesa and instant settlement with DTB Core banking GL at an individual transaction level. In case the MPesa transaction fails, eclipse will retry to make its success for a certain period of time(As Mpesa integration works with a pulling mechanism) but if it is still failing then it will call a reversal API to reverse the transaction.

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to KE_DTB_MPESA

Required tenant configuration:

fees.amount.config.Wdr.KE_DTB_MPESA.EFT.NORMAL=0.1P | Fees logic
fees.wallet.config.Wdr.KE_DTB_MPESA.EFT.NORMAL={WalletID} | Wallet ID to credit for fees charged
destination.wallet.config.KE_DTB_MPESA.EFT.NORMAL={WalletID} | Wallet ID to credit when a customer withdraws funds

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals

{"deliverToPhone":254715017691,"reference":"1425pk","amount":107,"description":"testing dtb Mpesa","type":"KE_DTB_MPESA","externalUniqueId":"hhr8584-48484-48848484"}

KE_DTB_IFT

EFT withdrawal used in case of withdrawing money from an Eclipse Wallet or from a DTB Bank ccount to a DTB bank account using the below API.

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to KE_DTB_IFT

Required tenant configuration:

fees.amount.config.Wdr.KE_DTB_IFT.EFT.NORMAL=0.1P | Fees logic
fees.wallet.config.Wdr.KE_DTB_IFT.EFT.NORMAL={WalletID} | Wallet ID to credit for fees charged
destination.wallet.config.KE_DTB_IFT.EFT.NORMAL={WalletID} | Wallet ID to credit when a customer withdraws funds

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

POST eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
    "amount": 10,
    "type": "KE_DTB_IFT",
    "externalUniqueId": "decce053-f7ce-47d6-9035-0ae579b351b7",
    "accountNumber": "5444298001",
    "branchCode": "001",
    "accountCurrency": "KES",
    "reference": "Beneficiary reference",
    "callbackUrl" : "www.google.com"
}

{
    "withdrawalId": 69692,
    "externalUniqueId": "decce053-f7ce-47d6-9035-0ae579b351b7",
    "status": "PENDING",
    "amount": 10,
    "currency": "KES",
    "gateway": "KE_DTB_IFT",
    "type": "EFT",
    "subType": "NORMAL",
    "walletId": 809294,
    "fee": 0,
    "created": "2023-09-12T12:16:41.000Z",
    "extraInfo": "{"dtbCallingCustomerCif":"1ac280c8-f7fc-4ecf-9d71-a42c8a3733fc","dtbCallingCustomerId":692425,"dtbCallingCustomerOrganisation":"","dtbSourceType":"DTB_WALLET","dtbSourceBankCode":"","dtbSourceCountryCode":"KE","dtbSourceCurrency":"KES","dtbSourceName":"sgAxZjXaKEWcwgU FkzaLcDTKxrHrXS","dtbSourcePhone":"254729294292","dtbDestinationAccountNumber":"5444298001","dtbDestinationBranchCode":"001","dtbDestinationCurrency":"KES"}",
    "reference": "Beneficiary reference",
    "deliverToPhone": "254729294292",
    "lastModified": "2023-09-12T12:16:41.000Z"
}

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_PESALINK

This withdrawal method is used to transfer an amount from an Eclipse Wallet to an external Pesalink Bank account, and settle with DTB Core banking GL at an individual transaction level. In case the PESALINK transaction fails, it needs manual intervention(As PESALINK integration works with a callback mechanism).

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals

If tenant config useGenericGateway is set to true this payment type will not include individual core banking GL. This method also allows transfer from an Eclipse Wallet or from a DTB Bank ccount to a DTB bank account using the below API.

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to KE_DTB_PESALINK

Required tenant configuration:

fees.amount.config.Wdr.KE_DTB_PESALINK.EFT.NORMAL=0.1P | Fees logic
fees.wallet.config.Wdr.KE_DTB_PESALINK.EFT.NORMAL={WalletID} | Wallet ID to credit for fees charged
destination.wallet.config.KE_DTB_PESALINK.EFT.NORMAL={WalletID} | Wallet ID to credit when a customer withdraws funds

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

POST eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
    "amount": 10,
    "type": "KE_DTB_PESALINK",
    "description": "test_KE_DTB_PESALINK_Digital to 0170197176640",
    "externalUniqueId": "22c9ec83-6787-48a1-9990-0d84e41cd831",
    "accountNumber": "0170197176640",
    "branchCode": "001",
    "accountCurrency": "KES",
    "bank": "0068",
    "reference": "Beneficiary reference"
}

{
    "withdrawalId": 69732,
    "externalUniqueId": "22c9ec83-6787-48a1-9990-0d84e41cd831",
    "status": "PENDING",
    "amount": 10,
    "currency": "KES",
    "gateway": "KE_DTB_PESALINK",
    "type": "EFT",
    "subType": "NORMAL",
    "walletId": 809562,
    "fee": 0.1,
    "created": "2023-09-12T12:28:06.000Z",
    "extraInfo": "{"dtbCallingCustomerCif":"908ed096-bde7-4a37-8ced-930d2161db18","dtbCallingCustomerId":692641,"dtbCallingCustomerOrganisation":"","dtbSourceType":"DTB_WALLET","dtbSourceBankCode":"","dtbSourceCountryCode":"KE","dtbSourceCurrency":"KES","dtbSourceName":"PalwNVamcSIgnnE CZzjTVlUDHGJcIx","dtbSourcePhone":"254729294292","dtbDestinationAccountNumber":"0100006325445","dtbDestinationBranchCode":"001","dtbDestinationBankCode":"0031","dtbDestinationCurrency":"KES"}",
    "reference": "Beneficiary reference",
    "description": "test_KE_DTB_PESALINK_Digital to 0170197176640",
    "deliverToPhone": "254729294292",
    "lastModified": "2023-09-12T12:28:06.000Z"
}

KE_DTB_RTGS

The Real Time Gross Settlement (RTGS) withdrawal method is an alternative to withdrawal type KE_DTB_PESALINK used to transfer an amount from an Eclipse Wallet to an external Bank account

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to KE_DTB_RTGS

Required tenant configuration:

fees.amount.config.Wdr.KE_DTB_RTGS.EFT.NORMAL=0.1P | Fees logic
fees.wallet.config.Wdr.KE_DTB_RTGS.EFT.NORMAL={WalletID} | Wallet ID to credit for fees charged
destination.wallet.config.KE_DTB_RTGS.EFT.NORMAL={WalletID} | Wallet ID to credit when a customer withdraws funds

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

POST eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
    "amount": 10,
    "type": "KE_DTB_RTGS",
    "description": "test_KE_DTB_RTGS_Digit to 0100006325445",
    "externalUniqueId": "3918082c-3023-44a9-96e5-c0e0e4bdbeed",
    "accountNumber": "0100006325445",
    "accountCurrency": "KES",
    "bank": "BARBKENA",
    "reference": "Beneficiary reference"
}

{
    "withdrawalId": 69776,
    "externalUniqueId": "3918082c-3023-44a9-96e5-c0e0e4bdbeed",
    "status": "PENDING",
    "amount": 10,
    "currency": "KES",
    "gateway": "KE_DTB_RTGS",
    "type": "EFT",
    "subType": "NORMAL",
    "walletId": 809839,
    "fee": 0,
    "created": "2023-09-12T12:47:09.000Z",
    "extraInfo": "{"dtbCallingCustomerCif":"3a00b367-484e-41be-abf8-3632461784b4","dtbCallingCustomerId":692853,"dtbCallingCustomerOrganisation":"","dtbSourceType":"DTB_WALLET","dtbSourceBankCode":"","dtbSourceCountryCode":"KE","dtbSourceCurrency":"KES","dtbSourceName":"ZbyRTFXCEULimvV QtDMmaRqRsiAlCs","dtbSourcePhone":"254729294292","dtbDestinationAccountNumber":"0100006325445","dtbDestinationBranchCode":"001","dtbDestinationBankCode":"BARBKENA","dtbDestinationCurrency":"KES"}",
    "reference": "Beneficiary reference",
    "description": "test_KE_DTB_RTGS_Digit to 0100006325445",
    "deliverToPhone": "254729294292",
    "lastModified": "2023-09-12T12:47:09.000Z"
}

KE_DTB_MPESA_SEND

This use case deals with transferring money to MPesa mobile phone wallet by using the recipients mobile phone and the selected wallet or wallet with an external source of value as the source. The service will request the withdrawal to take place. The results can either be an instant success or failure or result in a pending transaction. If the success is using a digital wallet, the funds will be moved from the wallet into a pool account or outgoing tracking wallet for MPESA and if returned a pending status, the service will wait for the call back response from the requested provider.

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to KE_DTB_MPESA_SEND

Required tenant configuration:

fees.amount.config.Wdr.KE_DTB_MPESA_SEND.EFT.NORMAL=0.1P | Fees logic
fees.wallet.config.Wdr.KE_DTB_MPESA_SEND.EFT.NORMAL={WalletID} | Wallet ID to credit for fees charged
destination.wallet.config.KE_DTB_MPESA_SEND.EFT.NORMAL={WalletID} | Wallet ID to credit when a customer withdraws funds

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
    "amount": 10,
    "type": "KE_DTB_MPESA_SEND",
    "description": "test_KE_DTB_MPESA_SEND_Digital to 254708374149",
    "externalUniqueId": "e56938bb-662a-42b2-b9e7-836e768ee2df",
    "deliverToPhone": "254708374149",
    "reference": "Beneficiary reference"
}

{
    "withdrawalId": 69736,
    "externalUniqueId": "e56938bb-662a-42b2-b9e7-836e768ee2df",
    "status": "PENDING",
    "amount": 10,
    "currency": "KES",
    "gateway": "KE_DTB_MPESA_SEND",
    "type": "EFT",
    "subType": "NORMAL",
    "walletId": 809562,
    "fee": 0,
    "created": "2023-09-12T12:28:08.000Z",
    "extraInfo": "{"dtbCallingCustomerCif":"908ed096-bde7-4a37-8ced-930d2161db18","dtbCallingCustomerId":692641,"dtbCallingCustomerOrganisation":"","dtbSourceType":"DTB_WALLET","dtbSourceBankCode":"","dtbSourceCountryCode":"KE","dtbSourceCurrency":"KES","dtbSourceName":"PalwNVamcSIgnnE CZzjTVlUDHGJcIx","dtbSourcePhone":"254729294292","dtbDestinationCurrency":"KES","dtbDestinationPhone":"254729294292"}",
    "reference": "Beneficiary reference",
    "description": "test_KE_DTB_MPESA_SEND_Digital to 254708374149",
    "deliverToPhone": "254708374149",
    "lastModified": "2023-09-12T12:28:08.000Z"
}

KE_DTB_AIRTEL_SEND

This use case deals with transferring money to an Airtel mobile phone wallet by using the recipients mobile phone and the selected wallet or wallet with an external source of value as the source. The service will request the withdrawal to take place. The results can either be an instant success or failure or result in a pending transaction. If the success is using a digital wallet, the funds will be moved from the wallet into a pool account or outgoing tracking wallet for AIRTEL and if returned a pending status, the service will wait for the call back response from the requested provider.

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to KE_DTB_AIRTEL_SEND

Required tenant configuration:

fees.amount.config.Wdr.KE_DTB_AIRTEL_SEND.EFT.NORMAL=0.1P | Fees logic
fees.wallet.config.Wdr.KE_DTB_AIRTEL_SEND.EFT.NORMAL={WalletID} | Wallet ID to credit for fees charged
destination.wallet.config.KE_DTB_AIRTEL_SEND.EFT.NORMAL={WalletID} | Wallet ID to credit when a customer withdraws funds

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals
{
    "amount": 10,
    "type": "KE_DTB_AIRTEL_SEND",
    "description": "test_KE_DTB_AIRTEL_SEND_Digital to 254780320654",
    "externalUniqueId": "99861de7-fa4e-4c0a-971f-9cc810173358",
    "deliverToPhone": "254780320654",
    "reference": "Beneficiary reference"
}

{
    "withdrawalId": 69738,
    "externalUniqueId": "99861de7-fa4e-4c0a-971f-9cc810173358",
    "status": "PENDING",
    "amount": 10,
    "currency": "KES",
    "gateway": "KE_DTB_AIRTEL_SEND",
    "type": "EFT",
    "subType": "NORMAL",
    "walletId": 809562,
    "fee": 0,
    "created": "2023-09-12T12:28:12.000Z",
    "extraInfo": "{"dtbCallingCustomerCif":"908ed096-bde7-4a37-8ced-930d2161db18","dtbCallingCustomerId":692641,"dtbCallingCustomerOrganisation":"","dtbSourceType":"DTB_WALLET","dtbSourceBankCode":"","dtbSourceCountryCode":"KE","dtbSourceCurrency":"KES","dtbSourceName":"PalwNVamcSIgnnE CZzjTVlUDHGJcIx","dtbSourcePhone":"254729294292","dtbDestinationCurrency":"KES","dtbDestinationPhone":"254729294292"}",
    "reference": "Beneficiary reference",
    "description": "test_KE_DTB_AIRTEL_SEND_Digital to 254729294292",
    "deliverToPhone": "254729294292",
    "lastModified": "2023-09-12T12:28:12.000Z"
}

UG Withdrawal Types

UG_DTB_IFT

EFT withdrawal is used in case of withdrawing money from an Eclipse Wallet or from a DTB Bank account to a DTB bank account using the below API.

Prerequisites

Valid JWT
Destination Account Details
Withdrawal gateway specified in the 'type' query parameter to UG_DTB_IFT

you will immediately receive a PENDING response. If the callback URL was populated a callback will be sent to that URL when the withdrawal is finalised (either successful or error).

/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals

{
    "accountName": "7115418418",
    "accountNumber": "7115418418",
    "amount": 1000,
    "bank": "23112312",
    "bankCountry": "UG",
    "accountCurrency": "UGX",
    "branchCode": "410506",
    "deliverToPhone": "23112312",
    "description": "Savings transaction",
    "externalUniqueId": "6287e670-39c0-4367-853e-72886bbf21bq9132",
    "location": "Ukheshe Offices",
    "reference": "Beneficiary reference",
    "type": "UG_DTB_IFT"
}

{
    "withdrawalId": 90996,
    "externalUniqueId": "6287e670-39c0-4367-853e-72886bbf21bq8132",
    "status": "PENDING",
    "errorDescription": "DTB-999: com.fasterxml.jackson.databind.exc.MismatchedInputException: Cannot deserialize value of...",
    "amount": 1000.000000000,
    "currency": "UGX",
    "gateway": "UG_DTB_IFT",
    "type": "EFT",
    "subType": "NORMAL",
    "walletId": 207016,
    "fee": 0E-9,
    "created": "2023-11-30T06:04:05.000Z",
    "extraInfo": "{\"dtbCallingCustomerCif\":\"a7cfe6d1-dc34-4e56-b537-0a0ac21b3bde\",\"dtbCallingCustomerId\":723689,\"dtbCallingCustomerOrganisation\":\"\",\"dtbSourceType\":\"DTB_BANK_ACCOUNT\",\"dtbSourceAccountNumber\":\"7053960002\",\"dtbSourceBranchCode\":\"001\",\"dtbSourceBankCode\":\"\",\"dtbSourceCountryCode\":\"UG\",\"dtbSourceCurrency\":\"UGX\",\"dtbSourceName\":\"James Madison\",\"dtbSourcePhone\":\"27987654321\",\"dtbDestinationAccountNumber\":\"7115418418\",\"dtbDestinationBranchCode\":\"410506\",\"dtbDestinationBankCode\":\"23112312\",\"dtbDestinationCountryCode\":\"UG\",\"dtbDestinationCurrency\":\"UGX\",\"dtbDestinationName\":\"7115418418\",\"dtbDestinationPhone\":\"23112312\"}",
    "reference": "Beneficiary reference",
    "description": "Savings transaction",
    "deliverToPhone": "23112312",
    "location": "Ukheshe Offices",
    "gatewayTransactionId": "Withdrawal-90996",
    "lastModified": "2023-11-30T06:04:05.000Z"
}

UG_DTB_MTN

This withdrawal type aims to transfer funds from an Eclipse/Astra Wallet to an MTN Mobile Money registered phone number.

Prerequisites

Valid JWT
Before initiating the withdrawal request, it's imperative to confirm that the specified configuration is in place within the tenant settings: mobilerecharge.providers=com.ukheshe.services.mobilerecharge.provider.DTBUGRechargeVasProvider. We used this config to validate the valid MTN mobile number (i.e Eclipse withdrawal processor will intiate this request /eclipse-conductor/rest/v1/tenants//vas/catalogs?catalogQuery=21_MTN_256779999703 before making the withdrawal request to validate the MTN phone number.
Destination mobile number(deliverToPhone)

/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals

{
  "amount": 10000,
  "type": "UG_DTB_MTN",
  "description": "Testing MTN withdrawal",
  "externalUniqueId": "6491bfa9-2122-4ffe-b5e1-7c2e1265",
  "deliverToPhone": "256779999703",
  "accountNumber": "7115418418",
  "branchCode": "001",
  "bankCountry": "UG",
  "accountCurrency": "UGX",
  "reference": "256779999703",
  "accountName": "Martha N"
}

{
  "withdrawalId": 171435,
  "externalUniqueId": "6491bfa9-2122-4ffe-b5e1-7c2e1265",
  "status": "PENDING",
  "errorDescription": ": ",
  "amount": 10000,
  "currency": "UGX",
  "gateway": "UG_DTB_MTN",
  "type": "EFT",
  "subType": "NORMAL",
  "walletId": 2487584,
  "fee": 0,
  "created": "2024-05-15T11:20:46.000Z",
  "extraInfo": "{\"dtbCallingCustomerCif\":\"f18f8912-58d8-4ab6-9051-32008db9114d\",\"dtbCallingCustomerId\":970528,\"dtbCallingCustomerOrganisation\":\"\",\"dtbSourceType\":\"DTB_WALLET\",\"dtbSourceAccountNumber\":\"8000020000040\",\"dtbSourceBranchCode\":\"001\",\"dtbSourceBankCode\":\"\",\"dtbSourceCountryCode\":\"UG\",\"dtbSourceCurrency\":\"UGX\",\"dtbSourceName\":\"Daphine Kajoina\",\"dtbSourcePhone\":\"256775555466\",\"dtbDestinationAccountNumber\":\"7115418418\",\"dtbDestinationBranchCode\":\"001\",\"dtbDestinationCountryCode\":\"UG\",\"dtbDestinationCurrency\":\"UGX\",\"dtbDestinationName\":\"Martha N\",\"dtbDestinationPhone\":\"256779999703\"}",
  "reference": "256779999703",
  "description": "Testing MTN withdrawal",
  "deliverToPhone": "256779999703",
  "lastModified": "2024-05-15T11:20:46.000Z"
}

Global Withdrawal Types

The following withdrawal types are not specific to any region.

GLOBAL_CRYPTO

Allow Crypto wallet to withdraw funds to another crypto address. This is implemented as an on-chain withdrawal on the underlying crypto exchange. Limit checks are as per normal cash withdrawals. Fees will be calculated in wallet currency if wallet currency is BTC then fees will be debited in btc currency.

Prerequisites

Valid JWT

Tenant level configuration

destination.wallet.config.GLOBAL_VALR.EFT=XXX
fees.wallet.config.Wdr.GLOBAL_VALR.EFT=XXX
fees.amount.config.Wdr.GLOBAL_VALR.EFT=0A

Note in the sandbox environment this should be configured as:

destination.wallet.config.GLOBAL_DUMMY_CRYPTO.EFT=XXX
fees.wallet.config.Wdr.GLOBAL_DUMMY_CRYPTO.EFT=XXX
fees.amount.config.Wdr.GLOBAL_DUMMY_CRYPTO.EFT=0A

Step 1 – Initiate withdrawal process

POST /eclipse-conductor/rest/v1/tenants/1/wallets/1/withdrawals
{ 
  "type": "GLOBAL_CRYPTO"
  "accountNumber": "<destination crypto wallet address>"
  "amount": "<positive number>"
}

Indicative initial response:

{
  "withdrawalId": 36820,
  "externalUniqueId": "123456789",
  "status": "PENDING",
  "amount": 0.00045,
  "currency": "BTC",
  "gateway": "GLOBAL_VALR",
  "type": "EFT",
  "subType": "NORMAL",
  "walletId": 14123025,
  "fee": 0.000037,
  "created": "2022-10-13T11:59:27.000Z",
  "extraInfo": "{\"accountNumber\":\"3J18ZA7zr3tJzML2LMaseN7i3Q2DKBFsyy\"}",
  "description": "BTC withdrawal",
  "deliverToPhone": "1234567890",
  "gatewayTransactionId": "e5a181cf-82f4-4a0e-b003-8fc14a0cac1e"
}

The withdrawal will be in status PENDING and will transition to SUCCESSFUL or ERROR_PERM depending on the result. The withdrawal status can be checked with:

GET eclipse-conductor/rest/v1/tenants/1/wallets/1400025/withdrawals

The response will include the transaction hash in the extraInfo field that can be used to verify the transaction on a blockchain explorer. Indicative response:

{
      "withdrawalId":36820,
      "externalUniqueId":"123456789",
      "status":"SUCCESSFUL",
      "amount":0.000450000,
      "currency":"BTC",
      "gateway":"GLOBAL_VALR",
      "type":"EFT",
      "subType":"NORMAL",
      "walletId":14123025,
      "fee":0.000037000,
      "created":"2022-10-13T11:59:27.000Z",
      "extraInfo":"{\"currency\":\"BTC\",\"address\":\"3J18ZA7zr3tJzML2LMaseN7i3Q2DKBFsyy\",\"amount\":4.5E-4,\"feeAmount\":3.7E-5,\"transactionHash\":\"8b927d16b09462682b2ed1064d2d860b6b4ed8bf91bf44abd1ce54a21aeb640c\",\"confirmations\":2,\"lastConfirmationAt\":\"2022-10-13T12:37:32.458Z\",\"uniqueId\":\"e5a181cf-82f4-4a0e-b003-8fc14a0cac1e\",\"createdAt\":\"2022-10-13T11:59:26.687Z\",\"verified\":true,\"status\":\"Complete\",\"accountNumber\":\"null\"}",
      "description":"BTC withdrawal",
      "deliverToPhone":"1234567890",
      "gatewayTransactionId":"e5a181cf-82f4-4a0e-b003-8fc14a0cac1e"
   }

📘
Note
In order for tenants to simulate minimum withdrawal amount errors, the sandbox environment is hardcoded to return a withdrawal error if the amount is less than 0.0002 BTC or less than 0.2 for any other crypto currency.

Zambia Withdrawal Types

The following withdrawal types are specific to tenants operating in Zambia.

ZM_MNO_WALLET

This withdrawal method is used to transfer an amount from an Eclipse Wallet to an external Zambia MNO wallet using the below API.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals

{"amount":1,"description":"Test MNO","type":"ZM_MNO_WALLET","externalUniqueId":"e4784d36-3d1d-4a8d-a73a-5a37b72a514c","accountNumber":"XHQ5F276","deliverToPhone":0760137434}

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals

{
    "deliverToPhone": 254722663855,
    "reference": "1425pk",
    "amount": 500,
    "description": "testing dtb Mpesa",
    "type": "KE_DTB_MPESA",
    "externalUniqueId": "{{$randomUUID}}"
}

Withdrawal Limits

It is possible to retrieve limits that are associated with a withdrawal gateway - specifically the wallet currency, the minimum withdrawal amount, the maximum withdrawal amount and any increments that might apply. Values will only be returned in the response if they have been configured for that withdawal gateway.

Prerequisites

Valid JWT
Wallet ID
Withdrawal gateway specified in the 'type' query parameter

GET eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals/limits?type=GLOBAL_CRYPTO

{
  "minimum": 7.3,
  "currency": "USDC"
}

you will immediately receive a PENDING response. If the callback URL was populated a callback will be sent to that URL when the withdrawal is finalised (either successful or error).

/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals

{
    "accountName": "7115418418",
    "accountNumber": "7115418418",
    "amount": 1000,
    "bank": "23112312",
    "bankCountry": "UG",
    "accountCurrency": "UGX",
    "branchCode": "410506",
    "deliverToPhone": "23112312",
    "description": "Savings transaction",
    "externalUniqueId": "6287e670-39c0-4367-853e-72886bbf21bq9132",
    "location": "Ukheshe Offices",
    "reference": "Beneficiary reference",
    "type": "UG_DTB_IFT"
}

{
    "withdrawalId": 90996,
    "externalUniqueId": "6287e670-39c0-4367-853e-72886bbf21bq8132",
    "status": "PENDING",
    "errorDescription": "DTB-999: com.fasterxml.jackson.databind.exc.MismatchedInputException: Cannot deserialize value of...",
    "amount": 1000.000000000,
    "currency": "UGX",
    "gateway": "UG_DTB_IFT",
    "type": "EFT",
    "subType": "NORMAL",
    "walletId": 207016,
    "fee": 0E-9,
    "created": "2023-11-30T06:04:05.000Z",
    "extraInfo": "{\"dtbCallingCustomerCif\":\"a7cfe6d1-dc34-4e56-b537-0a0ac21b3bde\",\"dtbCallingCustomerId\":723689,\"dtbCallingCustomerOrganisation\":\"\",\"dtbSourceType\":\"DTB_BANK_ACCOUNT\",\"dtbSourceAccountNumber\":\"7053960002\",\"dtbSourceBranchCode\":\"001\",\"dtbSourceBankCode\":\"\",\"dtbSourceCountryCode\":\"UG\",\"dtbSourceCurrency\":\"UGX\",\"dtbSourceName\":\"James Madison\",\"dtbSourcePhone\":\"27987654321\",\"dtbDestinationAccountNumber\":\"7115418418\",\"dtbDestinationBranchCode\":\"410506\",\"dtbDestinationBankCode\":\"23112312\",\"dtbDestinationCountryCode\":\"UG\",\"dtbDestinationCurrency\":\"UGX\",\"dtbDestinationName\":\"7115418418\",\"dtbDestinationPhone\":\"23112312\"}",
    "reference": "Beneficiary reference",
    "description": "Savings transaction",
    "deliverToPhone": "23112312",
    "location": "Ukheshe Offices",
    "gatewayTransactionId": "Withdrawal-90996",
    "lastModified": "2023-11-30T06:04:05.000Z"
}

Refer to the Withdrawal Limit API documentation for full details.

📘
Note
Withdrawal limits do not take into account wallet limits that might be applied. To retrieve the limits for a particular wallet refer to the Get Wallet Limits use case

Withdrawal Use Cases

South Africa Withdrawal Types

ZA_NEDBANK_EFT/ ZA_NEDBANK_EFT_IMMEDIATE

📘
Note

ZA_PAYCORP_ATM

Suggested Customer Prompts

📘
Note

📘
Note

ZA_PNP_CASH

Suggested prompts to guide customers for PicknPay Cash withdrawals

📘
Note

ZA_PNP_TENDER

ZA_AFRICANBANK_EFT (Sandbox only)

Kenya Withdrawal Types

KE_DTB_EFT

📘
Note

KE_DTB_MPESA

KE_DTB_IFT

📘
Note

KE_DTB_PESALINK

📘
Note

KE_DTB_RTGS

📘
Note

KE_DTB_MPESA_SEND

KE_DTB_AIRTEL_SEND

UG Withdrawal Types

UG_DTB_IFT

UG_DTB_MTN

Global Withdrawal Types

GLOBAL_CRYPTO

📘
Note

Zambia Withdrawal Types

ZM_MNO_WALLET

Withdrawal Limits

📘
Note

South Africa Withdrawal Types

ZA_NEDBANK_EFT/ ZA_NEDBANK_EFT_IMMEDIATE

📘Note

ZA_PAYCORP_ATM

Suggested Customer Prompts

📘Note

📘Note

ZA_PNP_CASH

Suggested prompts to guide customers for PicknPay Cash withdrawals

📘Note

ZA_PNP_TENDER

ZA_AFRICANBANK_EFT (Sandbox only)

Kenya Withdrawal Types

KE_DTB_EFT

📘Note

KE_DTB_MPESA

KE_DTB_IFT

📘Note

KE_DTB_PESALINK

📘Note

KE_DTB_RTGS

📘Note

KE_DTB_MPESA_SEND

KE_DTB_AIRTEL_SEND

UG Withdrawal Types

UG_DTB_IFT

UG_DTB_MTN

Global Withdrawal Types

GLOBAL_CRYPTO

📘Note

Zambia Withdrawal Types

ZM_MNO_WALLET

Withdrawal Limits

📘Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note