notify addPaymentMethod

2022-07-04 05:45

DWS uses this API to send the binding result to the merchant asynchronously. With this API call, the needed information is stored in JSON.

Note:
The merchant must provide their URL for DWS to notify.

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
referenceCustomerId	String	Yes	Customer ID in the merchant system. More information about this field: Maximum length: 64 characters This field and referenceUserId can only have one for each request	"216610000006358131449"
requestId	String	Yes	The unique ID that is assigned by a merchant to identify a payment method adding request. DWS uses this field for idempotence control. More information about this field: Maximum length: 64 characters Note: This field is an API idempotency field.	"2015032412007101547201355678"
paymentMethodDetail	PaymentMethodDetail	Yes	The details of this payment method.	M
operateSource	String	Yes	Operate source. Valid values are: `MERCHANT` More information about this field: Maximum length: 16 characters	"MERCHANT"

Response parameters

Field	Data type	Required	Description	Examples
result	Result	Yes	The request result, which contains information such as status and error codes.	/

Result processing logic

The iPayNotifyAddCardResult interface cannot accept the failure that is caused by business reasons. If the processing fails due to some business reasons, the merchant must first accept the notification and return SUCCESS to DWS.

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

Result status	Description
S	The iPayNotifyAddCardResult request is accepted successfully. The corresponding result.resultCode is `SUCCESS`, and result.resultMessage is `success`.
U	The status of the iPayNotifyAddCardResult 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 iPayNotifyAddCardResult 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.
INVALID_SIGNATURE	F	Signature is invalid.	Check whether the private key used to sign a request matches the public key of Alipay Developer Center.
ACCESS_DENIED	F	Access denied.	Contact Alipay Technical Support for detailed reasons.

Samples

Request:

DWS sends the binding result notification to the merchant.

copy

{
  "paymentMethodDetail": {
    "card": {
      "brand": "MASTERCARD",
      "cardToken": "ALIPAYpwBScbbHru3DE3CY5gvUVo4rNiaOibl1UmIR+AHKh9CpZFl0Wv/Co7iGaHHSXKR4yWCloE4MwfmN48sP1+rSPQ==",
      "expiryMonth": "**",
      "expiryYear": "**",
      "hashCode": "3caa419cf22c6567047c15d82e3ad644d9cb539fb9da5ae37eeff80d2000d53d",
      "instUserName": {
        "firstName": "****",
        "lastName": "Tung"
      },
      "mask": "523945******1949",
      "paymentMethodDetailMetadata": "{\"isFirstBoundAssetForPayOrTopUp\":\"true\",\"isBoundByOthers\":\"false\"}"
    },
    "paymentMethodDetailType": "CARD"
  },
  "requestId": "20990501203220303032821078591",
  "referenceCustomerId": "300005538591"
}

Response:

The merchant returns an acknowledged receipt to DWS.

copy

{
  "result":{
    "resultStatus":"S",
    "resultCode":"SUCCESS",
    "resultMsg":"success"
  }
}