queryPaymentMethod
POST /ams/api/v1/paymentMethods/queryPaymentMethod
Use this API to view the payment method the user has bound, and have the merchant present the result to the user.. The merchant can also use this API to query the status of the binding payment method.
Note:
- When this API is used to query bound payment methods, the user needs to choose at least one payment method type to query.
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 |
requestId | String | No | The unique ID that is assigned by a merchant to identify a payment method inquiry request. DWS uses this field for idempotence control. More information about this field:
Note: This field is an API idempotency field and will be used only when polling. | "345678982765436728376527" |
customerId | String | No | 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:
| "21623423232" |
referenceCustomerId | String | No | Customer ID in the merchant system. More information about this field:
| "1232343242" |
cardToken | String | No | The card token. | "ALIPAYnMegKUM09Qu6cM0CxEvNm4/sEX0+lprK6rEg/SaQSak3dMATEwxZQKlw/myujdYSyWCloE4MwfmN48sP1+rSPQ==" |
paymentMethodDetailTypes | List< | No | List of payment method types that are queried. Although this field is optional, it is better to have at least one payment method type. | ["bankAccount", "card"] |
Response parameters
Field | Data type | Required | Description | Examples |
result | Yes | The request result, which contains information such as status and error codes. | / | |
customerId | String | No | 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:
| "21623423232" |
paymentMethodDetails | List<PaymentMethodDetail> | No | A list of the payment methods. | [{ "card": { "billingAddress": {}, "brand": "MASTERCARD", "cardIssuer": "CIMB BANK BERHAD", "cardToken": "ALIPAYnMegKUM09Qu6cM0CxEvNm4/sEX0+lprK6rEg/SaQSak3dMATEwxZQKlw/myujdYSyWCloE4MwfmN48sP1+rSPQ==", "countryIssue": "MY", "expiryMonth": "**", "expiryYear": "**", "hashCode": "18a87763a17e14d4e60f4ee421a010d0ab9a2376d493549431c01e39695a1f89", "instUserName": { "firstName": "*** CHOOI", "lastName": "LI" }, "mask": "519603******8111", "paymentMethodDetailMetadata": "{\"ipayCardIndex\":\"2021020419027100162059624568402\",\"ipayCardDetailIndex\":\"2021020419027100162871528763223\",\"bingingDT\":\"2021-02-04T06:25:12Z\",\"defaultCard\":\"F\"}" }, "paymentMethodDetailType": "CARD" }] |
status | String | No | The status of the binding payment method. Note:
| "SUCCESS" |
actionForm | ActionForm | No | The next action is provided when the processing result is not a final status, as a reference for the next action. | { "challengeRenderValue": "+6222***508", "challengeType": "sms" } |
Result processing logic
In the response, the result.resultStatus field indicates the result of the queryPaymentMethod request. The following table describes each result status:
Result status | Description |
S | The queryPaymentMethod request is accepted successfully. The corresponding result.resultCode is |
U | The status of the queryPaymentMethod request is unknown. The corresponding result.resultCode is |
F | The queryPaymentMethod 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. |
REPEAT_REQ_INCONSISTENT | F | Repeat request inconsistent. | Ensure the fields in the requests are the same. |
ORDER_NOT_EXIST | F | The order of binding card does not exist. | Check the paymentMethodRequestId value. |
USER_NOT_EXIST | F | The user does not exist. | Contact Alipay Technical Support for detailed reasons. |
USER_STATUS_ABNORMAL | F | The user status is abnormal. | Contact the digital wallet to check the user status. |
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. |
METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. | Ensure the HTTP method is POST. |
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. |
ACCESS_DENIED | F | Access denied. | Contact Alipay Technical Support for detailed reasons. |
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. |
Samples
Request：
Check bound payment methods:
{
"customerId": "****************",
"paymentMethodDetailTypes": ["bankAccount", "card"]
}polling:
{
"customerId": "****************",
"requestId" : "MDEDUCT001bd856ad81cec1e91a620c270bcba5a4223"
}Response：
Check bound payment methods:
{
"customerId": "****************",
"paymentMethodDetails": [{
"card": {
"billingAddress": {},
"brand": "MASTERCARD",
"cardIssuer": "CIMB BANK BERHAD",
"cardToken": "ALIPAYnMegKUM09Qu6cM0CxEvNm4/sEX0+lprK6rEg/SaQSak3dMATEwxZQKlw/myujdYSyWCloE4MwfmN48sP1+rSPQ==",
"countryIssue": "MY",
"expiryMonth": "**",
"expiryYear": "**",
"hashCode": "18a87763a17e14d4e60f4ee421a010d0ab9a2376d493549431c01e39695a1f89",
"instUserName": {
"firstName": "*** CHOOI",
"lastName": "LI"
},
"mask": "519603******8111",
"paymentMethodDetailMetadata": "{\"ipayCardIndex\":\"2021020419027100162059624568402\",\"ipayCardDetailIndex\":\"2021020419027100162871528763223\",\"bingingDT\":\"2021-02-04T06:25:12Z\",\"defaultCard\":\"F\"}"
},
"paymentMethodDetailType": "CARD"
}],
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"success"
}
}polling:
{
"actionForm": {},
"customerId": "****************",
"paymentMethodDetails": [{
"card": {
"instUserName": {},
"paymentMethodDetailMetadata": "{\"orderId\":\"2022030219055002163265206233012\",\"bindingStatus\":\"PROCCESS\",\"merchantTransId\":\"8972e366-d803-4d08-b0f0-e29dcd1a9da0\",\"useScene\":\"SELFT_HELP_BIND\",\"bingingDT\":\"2022-03-02T08:24:02Z\",\"verifyCardType\":\"CREDIT_CARD\"}"
},
"paymentMethodDetailType": "CARD"
}],
"status": "PROCCESS",
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"success"
}
}