/v1/payments/notifyPayment
POST /v1/payments/notifyPayment
The notifyPayment
API is used to notify payment result to merchant/partner.
Note:
1) to notify merchant/partner the payment result when payment processing reaches the final state (Success/Fail).
2) Not all scenario merchant/partner need receive this notify. Such as sync payment scenario(B Scan C, Agreement Pay).
Message structure
Request
Property | Data type | Required | Description |
partnerId | String | Yes | The partnerId allocated by wallet. Max. length: 32 characters. |
paymentId | String | Yes | The unqiue ID of a payment generated by Wallet. Max. length: 64 characters. |
paymentRequestId | String | Yes | The unqiue ID of a payment generated by Wallet merchants. Max. length: 64 characters. |
paymentAmount | Yes | Order amount for display of user consumption records, payment results page. | |
paymentTime | String/Datetime | No | Payment success time, which follows the ISO 8601 standard. |
paymentStatus | String | Yes |
|
paymentFailReason | String | No | The fail reason of payment order when paymentStatus is FAIL. Max. length: 256 characters. |
extendInfo | String | No | The extend information,wallet and merchant can put extend info here. Max. length: 4096 characters. |
Response
Property | Data type | Required | Description |
result | Yes | The request result, which contains information related to the request result, such as status and error codes. |
Result Process Logic
- If result.resultStatus == S, Means the merchant/partner already received this notification.
- If result.resultStatus == F, it means merchant/partner handle this notification failed.
- If result.resultStatus==U, it means merchant/partner handle this notification occur unknown exception, wallet will retry if get U response.
- If other response (almost never occur),wallet will process like U.
Result
No | resultStatus | resultCode | resultMessage |
1 | S | SUCCESS | Success. |
2 | U | UNKNOWN_EXCEPTION | An API calling is failed, which is caused by unknown reasons. |
3 | U | REQUEST_TRAFFIC_EXCEED_LIMIT | The request traffic exceeds the limit. |
4 | F | REPEAT_REQ_INCONSISTENT | Repeated submit, and requests are inconsistent. |
5 | F | PROCESS_FAIL | A general business failure occurred. Don't retry. |
6 | F | INVALID_API | The called API is invalid or not active. |
7 | F | PARAM_ILLEGAL | Illegal parameters. For example, non-numeric input, invalid date. |
Sample
- The Mini Program calls my.tradePay interface to do payment (Step 1).
- E-wallet App returns payment result to the Mini Program (Step 5).
- E-wallet notifies the payment result with paymentNotifyUrl provided by merchant (Step 4).
For example, a wallet user purchases a 100 USD merchandise at a merchant/partner, after user finished payment in wallet cashier page, wallet will send payment status notification to merchant/partner.
Payment
A. Request sample with payment success
{
"partnerId": "P000000000000001xxxx",
"paymentId": "201911271907410100070000009999xxxx",
"paymentRequestId": "2019112719074101000700000088881xxxx",
"paymentAmount": {
"currency": "USD",
"value": "10000"
},
"paymentTime": "2019-11-27T12:02:01+08:30",
"paymentStatus": "SUCCESS"
}
- partnerId is the idetifier of a merchant/partner, allocated by Wallet.
- paymentId is generated by 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 Wallet from user account for this payment.
- paymentTime is the success date time of this transaction.
- paymentStatus is the payment status in wallet. SUCCESS means transaction already success.
B.
{
"partnerId": "P000000000000001xxxx",
"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",
"paymentStatus": "FAIL",
"paymentFailReason":"Order payment expired."
}
- paymentStatus is the payment status in wallet. FAIL means this transaction already failed, usually payment fail are because of this payment already expired .
- paymentFailReason used to fill the payment fail reason, only payment status is FAIL will return this parameter.
Response
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"success"
}
}
- result.resultStatus==S shows that merchant/partner already received this notification.