Add Funds

Topping up is the process of adding funds to a wallet.

KYC Level 0 users are not allowed to Top Up. Different Top Up channels are available in different countries. Users can only add funds which do not cause them to go over their balance limit.

/topup/query

• Your app calls /topup/query for a particular user and the Wallet Engine returns a list of the Top Up channels available for the country the user lives in. It also returns the costs and timelines involved in those Top Up channels, and the maximum amount which that user can Top Up according to their balance limit.

/topup/channels

• Lists the Top Up channels available in any specified country.

The user selects which Top Up channel they want to use, how much they want to Top Up by, and follow the appropriate steps according to what kind of transaction is involved.

/topup/bank

• Top Up via traditional bank transfer.

/topup/rapyd/checkout

• Top Up via Wallet Engine partner company ‘Rapyd’. Currently, transfers from PayNow and GrabPay are supported. More coming online all the time.

/topup/query

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

Call this API to find out how much the user is allowed to Top Up by, which Top Up channels are available to the user (depending on their country of residence), as well as the charges and the expected timescale for those Top Up channels.

Headers

Name	Type	Description
Content-Type	string	application/json
Authorization	string	Bearer {{token}}

Request Body

Name	Type	Description
app_id	string	This is the unique App ID assigned to you by Wallet Engine.

200 Successfully.

{
  "kyc": {
    "kyc_level": 1,
    "kyc_status": "OK",
    "balance": 0,
    "debit_cumulative": 0,
    "debit_remainder_allowance": 5000,
    "balance_remainder_allowance": 1000
  },
  "channels_available": [
    // refer to: topup/channels
  ]
}

500 The method was called with invalid arguments.

{
    "code": 500,
    "error": "invalid_arguments",
    "message": "The method was called with invalid arguments."
}

Example Request

{
  "app_id": "86509b0699ae"
}

Errors This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Error	Description
invalid_arguments	The method was called with invalid arguments.
invalid_arg_name	The method was passed an argument whose name falls outside the bounds of accepted or expected values.
kyc_level_unqualified	The current KYC Level is L0, and the user can not top-up.
credit_remainder_empty	The balance remainder allowance is empty.

/topup/channels

POST /api/topup/channels

Call /topup/channels to get a list of the available Top Up channels in any particular country. As an app developer you could offer the user a choice of which country details to display, or perhaps begin with their country of residence, or even use geolocation to understand which country they are currently in and submit that country code. If no country is provided, the channels available in the users country of residence are returned by default by /topup/query, but /topup/channels is useful particularly if the user is travelling abroad. The fees involved and the delivery times of each Top Up channel are listed in the responses.

Headers

Name	Type	Description
Content-Type	string	application/json
Authorization	string	Bearer {{token}}

Request Body

Name	Type	Description
app_id	string	This is the unique App ID assigned to you by Wallet Engine.
country_loc_code	string	The country for which the Top-Up channels are requested. It should be provided as a two characters ISO code. If a country_loc_code is not provided then the results for the country of residence (country_res_code) are returned. https://countrycode.org

200 Successfully.

{
    "channels": [
        {
            "title": "Bank",
            "logo_url": "Logo-Bank.png",
            "fee": 0.1,
            "channel": "credit_bank",
            "delivery_time": "1 day",
            "method": "topup/bank",
            "status": "active",
            "variables": {
                "bank_name": "HSBC",
                "bank_code": "7171",
                "bank_branch_code": "001",
                "account_name": "WE Bank Account",
                "account_number": "0052312891",
                "iban_code": "DE89 3704 0044 0532 0130 00",
                "swift_code": "DBSSSGSGXXX"
            }
        },
        {
            "title": "HSBC",
            "logo_url": "Logo-HSBC.png",
            "fee": 0.3,
            "channel": "credit_bank_hsbc",
            "delivery_time": "1 day",
            "method": "topup/bank",
            "status": "active",
            "variables": {
                "bank_branch_code": "001",
                "account_name": "WE Bank Account",
                "account_number": "0052312891",
                "iban_code": "DE89 3704 0044 0532 0130 00",
                "swift_code": "DBSSSGSGXXX"
            }
        },
        {
            "title": "Rapyd PayNow",
            "logo_url": "Logo-PayNow.png",
            "fee": 0.1,
            "channel": "credit_rapyd_paynow",
            "delivery_time": "10 minutes",
            "method": "topup/rapyd/checkout",
            "status": "active"
        },
        {
            "title": "Rapyd eNETS",
            "logo_url": "Logo-eNETS.png",
            "fee": 0.6,
            "channel": "credit_rapyd_enets",
            "delivery_time": "10 minutes",
            "method": "topup/rapyd/checkout",
            "status": "active"
        }
    ]
}

500 The method was called with invalid arguments.

{
    "code": 500,
    "error": "invalid_arguments",
    "message": "The method was called with invalid arguments."
}

Example Request

{
  "app_id": "86509b0699ae"
}

Errors This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Error	Description
invalid_arguments	The method was called with invalid arguments.
invalid_arg_name	The method was passed an argument whose name falls outside the bounds of accepted or expected values.

/topup/bank

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

Use this API to Top Up a wallet with a bank transfer. The user will be asked how much they want to top up, they will be advised of the charges involved and they will be asked to effect a bank transfer with a particular reference used when effecting the transaction with their bank. When the funds are received in the Wallet Engine bank account the users wallet will be Topped Up with the appropriate amount.

Headers

Name	Type	Description
Content-Type	string	application/json
Authorization	string	Bearer {{token}}

Request Body

Name	Type	Description
app_id	string	This is the unique App ID assigned to you by Wallet Engine.
amount	number	Top-up amount.
channel_id	string	Channel Id.

200 Successfully.

{
  "request_id": "5dee1542283a5",
  "amount": 100,
  "fee": 1,
  "total": 101
}

500 The method was called with invalid arguments.

{
    "code": 500,
    "error": "invalid_arguments",
    "message": "The method was called with invalid arguments."
}

Example Request

{
  "app_id": "86509b0699ae",
  "amount": 100,
  "channel_id": "credit_bank"
}

Errors This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Error	Description
invalid_arguments	The method was called with invalid arguments.
invalid_arg_name	The method was passed an argument whose name falls outside the bounds of accepted or expected values.
invalid_topup_amount	The top-up amount exceeds the allowed values.
invalid_channel_id	Channel not available.

/topup/rapyd/checkout

POST https://sandbox.walletengine.io/api/topup/rapyd/checkout

Use this API to carry out a Top Up using Rapyd channels. After confirming the amount to be Topped Up , and the charges involved, a browser window displays the relevant pages required for processing the transaction. Once a payment has been made to effect the Top Up, the users wallet will be credited with the appropriate amount straight away.

Headers

Name	Type	Description
Content-Type	string	application/json
Authorization	string	Bearer {{token}}

Request Body

Name	Type	Description
app_id	string	This is the unique App ID assigned to you by Wallet Engine.
amount	number	Top-up amount.
channel_id	string	Channel Id.

200 Successfully.

{
  "request_id": "5dee1542283a5",
  "browser_url": "https://sandboxcheckout.rapyd.net/?token=checkout_d8ae07edc2821b12adfe3365ee49dd06"
}

500 The method was called with invalid arguments.

{
    "code": 500,
    "error": "invalid_arguments",
    "message": "The method was called with invalid arguments."
}

Example Request

{
  "app_id": "86509b0699ae",
  "amount": 100,
  "channel_id": "credit_rapyd_paynow"
}

Errors This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Error	Description
invalid_arguments	The method was called with invalid arguments.
invalid_arg_name	The method was passed an argument whose name falls outside the bounds of accepted or expected values.
invalid_topup_amount	The top-up amount exceeds the allowed values.
invalid_channel_id	Channel not available.