/v2/payments/notifyPayment
POST /v2/payments/notifyPayment
The notifyPayment
API is used to notify the merchant/partner of the payment result.
Note:
- It is to notify the merchant/partner of the payment result when the payment processing reaches the final state (Success/Fail).
- It is not applied to all payment scenarios. For example, in the sync payment scenario (B Scan C, auto-debit payment), the merchant/partner does not need to receive this notification.
Message structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:
Request
Property | Data Type | Required | Description | Example |
paymentId | String | Yes | The unique ID of a payment is generated by the wallet. Max. length: 64 characters. | "201911271907410100070000009999xxxx" |
paymentRequestId | String | Yes | The unique ID of a payment is generated by merchants. Max. length: 64 characters. | "2019112719074101000700000088881xxxx" |
paymentResult | No | The result of a payment. | { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" } | |
paymentAmount | Yes | Order amount on the payment results page, which displays user consumption records. | { "currency": "USD", "value": "10000" } | |
paymentTime | String/Datetime | No | Payment success time, which follows the ISO 8601 standard. | "2019-11-27T12:02:01+08:30" |
paymentCreateTime | String/Datetime | No | Payment creation time, which follows the ISO 8601 standard. | "2019-11-27T12:02:01+08:30" |
extendInfo | String | No | The extended information that wallets and merchants want to describe. Max. length: 4096 characters. | copy
|
Response
Property | Data Type | Required | Description | Example |
result | Yes | The request result, which contains information such as status and error codes. | { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" } |
Result Process Logic
In the response, the result.resultStatus
field indicates the result of processing a request as follow:
resultStatus | Description |
S | The corresponding It means that the merchant/partner already receives this payment status notification. |
U | The corresponding It means that when the merchant/partner handles this notification, an unknown exception occurs. The wallet can retry if get the `U` response. If other responses (rarely occur), the wallet will process like `U`. |
F | That means this transaction is failed. The corresponding It means that the merchant/partner fails to handle this notification request. |
Error codes
Error codes are usually classified into the following categories:
- Common error codes are common for all mini program's OpenAPIs.
- API-specific error codes are listed in the following table.
resultStatus | resultCode | resultMessage | Further Action |
F | REPEAT_REQ_INCONSISTENT | The submitted request is not consistent with the last one. |
Sample
- The mini program calls my.tradePay interface to do payment (Step 1).
- The wallet returns the payment result to the mini program (Step 5).
- The wallet notifies the payment result with paymentNotifyUrl provided by the merchant (Step 4).
For example, a wallet user purchases 100 USD merchandise at a merchant/partner and finished payment on the wallet cashier page, the wallet will send a payment status notification to the merchant/partner.
Payment
A. Request with payment upon success
{
"paymentId": "201911271907410100070000009999xxxx",
"paymentRequestId": "2019112719074101000700000088881xxxx",
"paymentAmount": {
"currency": "USD",
"value": "10000"
},
"paymentTime": "2019-11-27T12:02:01+08:30"
}
- paymentId is generated by the wallet, uniquely identifies the payment.
- paymentRequestId is generated by merchant/partner,uniquely identifies this payment. In payment notify request, paymentRequestId should be the paymentRequestId in origin payment request.
- paymentAmount describes the amount of 100 USD already collected by the wallet from the user account for this payment.
- paymentTime is the time when this transaction is successful.
B. Request with payment failed
{
"paymentId": "201911271907410100070000009999xxxx",
"paymentRequestId": "2019112719074101000700000088881xxxx",
"paymentAmount": {
"currency": "USD",
"value": "10000"
},
"paymentCreateTime": "2019-11-27T12:01:01+08:30",
"paymentTime": "2019-11-27T12:02:01+08:30"
}
Response
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"success"
}
}
- result.resultStatus==S shows that merchant/partner already received this notification.