Initiating a Top-up

The Wallet Engine platform makes it simple for your customers to deposit money to the wallet.

Prior to this use case, your customers have to update their KYC level as described in KYC. Now one customer wants to top-up amount to their wallet.

There are many reasons why your customers want to top-up their wallets. Your customers want to transfer money to the other customer’s wallet. Your customers want to buy the items or pay for the services which they use in your application… Depending on the use case, the top-up amount can be entered by the customer or calculated by your application.

Use Case Overview

• Let’s consider the case of Alice who is your customer. Alice wants to buy the item on your application. Alice chooses to purchase an item, adds it to their cart, and begins to checkout and arrives at the payment page. The total price comes to $25 but her wallet is empty, your application says “You have to top-up $25 before continuing the checkout process.”. Your application initiating the top-up process with the amount is $25.

• Now, Alice wants to buy more items, she also wants to transfer money to her friends. Her wallet does not enough money. Alice goes to the wallet and clicks to the top-up button. Alice enters the amount she wants to top-up. Your application initiating the top-up process with the amount is entered by Alice.

Initiating Top-up Workflow

Highlights in your workflow and the basic stage.

• Stage 1:

  • Users are not allowed to top-up at level L0 or status in L1r, L1x, or Processing.

  • Encourages your customers to complete the KYC upgrade and return to the top-up process later.

• Stage 2:

  • Currently, Wallet Engine only supports SGD, if your store has multiple currencies, you must convert to SGD first, before proceeding with other steps.

  • The amount may be calculated by your application or entered by the customer but must meet the KYC Limit conditions. The amount cannot be exceeded balance_remainder_allowance.

• Stage 3:

  • Your customers select the top-up channel which they feel is most convenient and easy.

  • Each top-up channel contains the name, logo, delivery time, and applies a different fee.

Implementing the Workflow

How you'll use Wallet Engine’s API to implement the workflow.

Verify using API topup/query:

• This API helps you verify the current KYC level is qualified to top-up and the customer’s wallet already meets the maximum balance allowance.

• If everything is fine this API responds with the combination of kyc/query and topup/channels.

Properties	Description
kyc_status	KYC status maybe not OK, but your customers can continue the top-up process.
balance_remainder_allowance	Maximum deposit value, users cannot deposit an amount larger than this number.

Finding Available Payment Methods:

• On your top-up page, you let your customer specify payment methods. This API responds with available payment methods in any particular country: topup/channels.

• First, you need to query the payment methods according to the customer’s country. Second, you will decide which payment methods you’ll accept or support. Each channel contains different properties and statuses, which makes it easy to filter and display.

Properties	Description
fee	Each channel has applied a different fee. Your application has to calculate the top-up amount with fees and confirm with the customer.
channel	This is the unique id for each channel. Your application can rely on this to filter the channels that are supported.
method	The method describes the steps when integrating, which may require different steps or fields that the customer must fill in to complete the payment.
variables	Based on the channel method, this is the information that your application must show to the customer.
status	For some reason, the channel has status inactive. Ex: in maintenance mode.

Creating the Payment

When Alice checkouts out on your application, she selects the top-up channel, every information is confirmed. Your application ready to process her payment. For that, you will send the request to Create Payment with the following required parameters:

/topup/bank

POST https://sandbox.walletengine.io/api/topup/bank

Request Body

Name	Type	Description
app_id	string
amount	number	The amount that your customer wants to top-up.
channel_id	string	The unique id of the channel your customer has selected.

200

{
  "request_id": "5dee1542283a5",
  "amount": 25,
  "fee": 0.1,
  "total": 25.1
}

400

{
  "code": 400,
  "error": "invalid_topup_amount",
  "message": "The top-up amount exceeds the allowed values."
}

Example Request

{
  "app_id": "1db2a50be7626",
  "amount": 25,
  "channel_id": "credit_bank"
}

The data section of this response shows:

• request_id: This is a unique string generated and linked to the payment request, which you will need for a later step in this use case. Your application can store this request_id and use it to check the payment status later.

The different method responds with different information and structure, but it always includes the property request_id.

Completing the Payment

Each payment channel will have different payment completion steps, the next steps for completing payment will be described in the respective methods.