Account Maintenance

User and account details can be accessed and managed via the following API’s which will be described in detail below.

/kyc/query

• Balance & Balance remainder allowance

• Debit remainder allowance & Debit cumulative

• KYC level

/profile/query

• Name

• Address

• Country of residence

• Nationality

• Date of birth

• Phone number (edit here will require OTP flow)

• Email address

/history/query

• Transaction history

/profile/update

• Provide updated profile information.

Terminology

Term	Explanation
KYC	Know Your Customer. We group users into several KYC levels according to the amount of information we have available and the amount of verifications we have performed. Users with different KYC levels will be able to access different services to different extents, and will have different usage limits applied to their accounts.
Limits	The limit value to which a user can operate within current KYC level. (For example if a user has a balance limit of $5 then their wallet cannot hold more than $5.)
Balance	The amount of money in a user’s wallet.
Balance remainder allowance	The value that can be credited to a user’s wallet. Calculated from balance limit minus balance.
Debit allowed	The value is allowed to be debited from an account. Calculated from balance and debit remainder allowance.
Debit remainder allowance	The value is allowed to be debited from an account. Calculated from debit limit and debit cumulative
Debit cumulative	A twelve-month rolling sum of debits is carried out.

/kyc/query

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

Use this API to query all the KYC related information pertaining to a specific user.

Headers

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

Request Body

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

200 Successfully.

{
  "kyc_level": 0,
  "kyc_status": "OK",
  "available_balance": 30,
  "total_balance": 100,
  "blocked_balance": 70,
  "debit_cumulative": 100,
  "debit_remainder_allowance": 2,
  "balance_remainder_allowance": 3,
  "kyc_verify_url": "https://verify-with.blockpass.org/?clientId=testing_efa45&serviceName=WalletEngine&env=prod",
  "kyc_limit": {
    "L0": {
      "SGD": {
        "max_wallet_balance": 5,
        "max_annual_withdrawal": 50
      }
    },
    "L1": {
      "SGD": {
        "max_wallet_balance": 1000,
        "max_annual_withdrawal": 30000
      }
    }
  }
}

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.

/profile/query

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

Use this API to query all the user details for a specific user.

Headers

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

Request Body

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

200 Successfully.

{
  "nickname": "FooB",
  "first_name": "Foo",
  "last_name": "Bar",
  "birth_date": "2000-01-02",
  "country_dial_code": "65",
  "phone_number": "909099999",
  "email_address": "[e-mail]",
  "address": {
    "country_res_code": "VN",
    "city": "string",
    "state": "string",
    "street": "string",
    "postal_code": "string"
  },
  "tos_accepted": "2020-01-20 10:50:59",
  "country_nat_code": "VN"
}

500 The method was called with invalid arguments.

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

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.

/history/query

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

This API will return the details of the transactions carried out on the user account. By default, it will return the most recent ten transactions, but the offset and limit fields can be used to enquire about transactions older than that.

Headers

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

Request Body

Name	Type	Description
app_id	string	This is the unique App ID assigned to you by Wallet Engine.
limit	number	Paging by limit offset. - Default: 10, maximum: 99 records. - Return the first 10 records by default.
offset	number	- Default: 0. - Start on record 0 by default.
date_from	string	Transaction created date.
date_to	string

200 Successfully.

{
  "total": 100,
  "transactions": [
    {
      "id": "1039",
      "creation_date": "2019-12-11 19:18:38",
      "type": "DEPOSIT",
      "amount": 1.0,
      "fee": 0,
      "channel_id": "credit_bank",
      "notes": "transfer transaction",
      "transfer_details": {
        "ref_account_id": "XPJE343",
        "ref_first_name": "First Name",
        "ref_last_name": "Last Name"
      }
    },
    {
      "id": "1038",
      "creation_date": "2019-12-11 19:17:05",
      "type": "WITHDRAWAL",
      "amount": -1.0,
      "fee": 0,
      "channel_id": "debit_bank",
      "notes": "withdrew via Bank"
    },
    {
      "id": "1037",
      "creation_date": "2019-12-11 19:16:12",
      "type": "DEPOSIT",
      "amount": 90.0,
      "state": "inprogress",
      "fee": 1,
      "channel_id": "cash",
      "notes": "deposited via Cash"
    }
  ]
}

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": "5db2a50be7626",
    "limit": 10,
    "offset": 0,
    "date_from": "2021-05-31",
    "date_to": "2021-09-10"
}

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.

/profile/update

POST https://sandbox.walletengine.io/api/profile/update

In the event that a user needs to update any of their profile information, use this API to makes the required changes.

Headers

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

Request Body

Name	Type	Description
app_id	string	This is the unique App ID assigned to you by Wallet Engine.
nickname	string
email_address	string
tos_accepted	string	The date that ToS was last accepted by the user.

200 Successfully.

{
  "valid": true
}

500 The method was called with invalid arguments.

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

Example Request

• Update full profile information:

{
    "app_id": "5db2a50be7626",
    "nickname": "FooB",
    "email_address": "[e-mail]",
    "tos_accepted": "2021-09-20 10:50:59"
}

• Update a part of profile information:

{
    "app_id": "5db2a50be7626",
    "tos_accepted": "2021-09-20 10:50:59"
}

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_user_authorize	WE Gateway can not authorize the user. Invalid App User Token.
fatal_error	The server could not complete your operation(s) without encountering a catastrophic error.

/profile/update - Edge Case: Update Phone Number

POST https://sandbox.walletengine.io/api/profile/update

In the case where the user needs to change their phone number a slightly different process must be followed. For security reasons, the user needs to verify a One Time Password (OTP) that is sent to their new phone number before their number can be updated. This is covered in more detail in the Authorization documentation. - Verify the new phone number by using the API /authorize/verify. - Send the passcode to the new phone number by using the API /authorize/otp/generate. - The user enter the passcode and selects the Confirm button on the App. At this point, the new phone number and the OTP are submitted via /profile/update.

Headers

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

Request Body

Name	Type	Description
app_id	string	The App ID is generated by the developer portal.
country_dial_code	number	The phone's country code.
phone_number	number	The user's new phone number.
passcode	number	One-time passcode using voice or SMS message.

200 Successfully.

{
    "valid": true
}

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": "5db2a50be7626",
    "country_dial_code": "65",
    "phone_number": "909099999",
    "passcode": "268471"
}

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_passcode	The passcode is expired or invalid.