queryAccountAndBenefit

2022-07-04 05:45

POST /ams/api/v1/accounts/queryAccountAndBenefit

Use this API to check the wallet balance of the user and present it to them.

Note:
Before calling this API, users must activate their wallet's account.
In some regions (e.g., Europe), DWS needs to verify user's identity via SMS, PIN, or two-factor challenge (PIN is required first, then OTP for one request) due to local regulation. So, before calling the API to check the wallet's balance, you must use this API to initialize the check flow, and then use the triggerChallenge API to trigger authentication and complete verification by the verifyAuthentication API if the challenge is needed.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

If the data type of a field is Integer and its value is 20, set it as "20".
If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

Field	Data type	Required	Description	Examples
customerId	String	Yes	The unique ID that is used to identify a buyer. This field is composed of 16 digits and begins with 21. More information about this field: Maximum length: 64 characters	"2162878776333"
queryAccountConditions	List< QueryAccountCondition>	No	A list of the business scenarios that are available for different payment methods. See QueryAccountCondition for details. Note: This field is optional and, in most cases, you can just give a null value.	{ "accountType": "BALANCE_ACCOUNT" }
processId	String	No	Query process ID. More information about this field: Maximum length: 64 characters	"20220112110077000000190830201924924"
environment	Env	No	The environment information. Note: Detailed information about this field is shown below.	{ "appVersion": "6.84.2", "clientIp": "175.*..*", "deviceModel": "TECNO LD7", "deviceTokenId": "wiQ5Hlwx3QLMkRS3R3OMtOAnznRWKJ6lFPgs7GDgihiuimC9fQEAAA==", "language": "en-PH", "operateEntrance": "DWS", "osType": "Android", "osVersion": "10", "sessionId": "******************************", "terminalType": "APP", "umidTokenId": "DYQAEhpLPO4XcQN9vXk/RHl6C7oLX+41" },

Response parameters

Field	Data type	Required	Description	Examples
result	Result	Yes	The request result, which contains information such as status and error codes.	/
accounts	List<Account>	No	The list of accounts information. See Account for details.	{ "accountNo": "********************", "accountStatus": "available", "accountType": "BALANCE_ACCOUNT", "availableAmount": { "currency": "MYR", "value": "23" }, "createTime": "2020-01-13T01:16:44-08:00", "crossSiteCustomerId": "2162265049047338", "currency": "MYR", "customerTntInstId": "HLOPW3MY", "frozenAmount": { "currency": "MYR", "value": "0" }, "holderName": { "middleName": "" }, "totalAmount": { "currency": "MYR", "value": "23" } }
processId	String	No	Query process ID More information about this field: Maximum length: 64 characters	"20220112110077000000190830201924924"
actionForm	Map<String, Object>	No	The next action is provided when the processing result is not final, as a reference for the next action.	{ "actionFormType":"ChallengeActionForm", "challengeRenderValue":"57d8c5c03bf2403591e2eace1642fbc4_us_site", "challengeType":"SMS_OTP" }

Result processing logic

In the response, the result.resultStatus field indicates the result of the queryAccountAndBenefit request. The following table describes each result status:

Result status	Description
S	The queryAccountAndBenefit request is accepted successfully. The corresponding result.resultCode is `SUCCESS`, and result.resultMessage is `success`.
U	The status of the queryAccountAndBenefit request is unknown. The corresponding result.resultCode is `UNKNOWN_EXCEPTION`, and result.resultMessage is An API call failed, which is caused by unknown reasons. For details, see the Common error codes section.
F	The queryAccountAndBenefit request failed. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

Error codes

Result code	Result status	Result message	Further action
SUCCESS	S	Success	/
PROCESS_FAIL	F	A general business failure occurred. Don't retry.	Human intervention is usually needed. It is recommended that you contact the technical support team to troubleshoot the issue.
PARAM_ILLEGAL	F	Illegal parameters. For example, non-numeric input, invalid date.	Check and verify whether the request fields, including the header fields and body fields, are correct and valid. For details on the fields of each API, see the specific API Structure section.
UNKNOWN_EXCEPTION	U	API failed due to unknown reasons.	Call the interface again to resolve the issue. If the issue persists, contact Alipay Technical Support.
RISK_REJECT	F	Risk reject	Prompt the user that the request is rejected because the risk control failed.
USER_NOT_EXIST	F	The user does not exist.	Contact Alipay Technical Support for detailed reasons.
KEY_NOT_FOUND	F	Key is not found.	Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center.
INVALID_API	F	API is invalid (or not active).	Check whether the API name, HTTP method, or request format is correct when sending the request.
INVALID_CLIENT	F	Invalid client.	Check whether the client ID is correct, or contact Alipay Technical Support for detailed reasons.
INVALID_SIGNATURE	F	Signature is invalid.	Check whether the private key used to sign a request matches the public key of Alipay Developer Center.
REQUEST_TRAFFIC_EXCEED_LIMIT	U	Request traffic exceeds the limit.	Call the interface again to resolve the issue. If the issue persists, contact Alipay Technical Support.
ACCESS_DENIED	F	Access denied.	Contact Alipay Technical Support for detailed reasons.
PAY_PASSWORD_IN_MOBILE_NO	F	Password in mobile number	Check whether the password is in mobile number.
SEND_TIMES_EXCEED_LIMIT	F	The send times exceed the limit.	Contact Alipay technical support to know the specific limitation.
METHOD_NOT_SUPPORTED	F	The server does not implement the requested HTTP method.	Ensure the HTTP method is POST.
NO_PAY_PASSWORD	F	The user does not complete PIN setting.	Prompt user to set PIN.

Samples

Request:

The merchant sends a request to DWS.

Without inquiryProcessId：

copy

{
  "environment": {
    "clientIp": "",
    "deviceTokenId": "",
    "language": "",
    "sessionId": "",
    "termonalType": "APP",
    "umidTokenId": ""
  },
  "customerId": "2162265049047338",
  "queryAccountConditions": [{
    "accountType": "BALANCE_ACCOUNT"
  }]
}

With processId：

copy

{
    "environment":{
        "clientIp":"176.***.**.***",
        "deviceTokenId":"LD6WB1sraOEUjfoV6L5uhpa38KZFxicsDUQ5CykVZYY5jQ1NfgEAAA==",
        "language":"fr_FR",
        "sessionId":"**********************************************_al_b_I",
        "terminalType":"APP",
        "umidTokenId":"NUtL1LJLOuIEezV+TTZjXwYpDZOqg55T"
    },
    "customerId":"2188210291658265",
    "queryAccountConditions":[
        {
            "account****":"BALANCE_ACCOUNT"
        },
    ],
    "processId":"20220112110077000000190830201924924"
}

Response:

DWS returns the request result.

Response of PAYMENT_PASSWORD challenge：

copy

{
    "actionForm":{
        "challengeRenderValue":"",
        "challengeType":"PAYMENT_PASSWORD"
    },
    "processId":"20220112110077000000190830201924924",
    "result":{
        "resultCode":"SUCCESS",
        "resultMessage":"success.",
        "resultStatus":"S"
    }
}

Response of SMS challenge：

copy

{
    "actionForm":{
        "actionFormType":"ChallengeActionForm",
        "challengeRenderValue":"57d8c5c03bf2403591e2eace1642fbc4_us_site",
        "challengeType":"SMS_OTP"
    },
    "processId":"20220112110077000000190830201924924",
    "result":{
        "resultCode":"SUCCESS",
        "resultMessage":"success.",
        "resultStatus":"S"
    }
}

Normal response to show balance：

copy

{
  "accounts": {
    "accountNo": "********************",
    "accountStatus": "available",
    "accountType": "BALANCE_ACCOUNT",
    "availableAmount": {
      "currency": "MYR",
      "value": "23"
    },
    "createTime": "2020-01-13T01:16:44-08:00",
    "crossSiteCustomerId": "2162265049047338",
    "currency": "MYR",
    "customerTntInstId": "HLOPW3MY",
    "frozenAmount": {
      "currency": "MYR",
      "value": "0"
    },
    "holderName": {
      "middleName": ""
    },
    "totalAmount": {
      "currency": "MYR",
      "value": "23"
    }
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}