/v2/payments/notifyPayment

2022-11-17 04:34

POST /v2/payments/notifyPayment

The notifyPayment API is used to notify the merchant/partner of the payment result.

Note:

Follow the specifications below when the merchant develops this API.
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 for 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

Request

Property	Data type	Required	Description	Example
paymentId	String	Yes	The unqiue ID of a payment generated by Wallet. Max. length: 64 characters.	"201911271907410100070000009999xxxx"
paymentRequestId	String	Yes	The unqiue ID of a payment generated by merchants. Max. length: 64 characters.	"2019112719074101000700000088881xxxx"
paymentResult	Result	No	The result of a payment.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }
paymentAmount	Amount	Yes	Order amount for display of user consumption records, payment results page.	{ "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 extend information,wallet and merchant can put extend info here. Max. length: 4096 characters.	"This is additional information"

Response

Property

Data type

Required

Description

Example

result

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 follows.

resultStatus	Decription
S	The corresponding `result.resultCode` is "SUCCESS" and the `result.resultMessage` is "Success". It means that the merchant/partner already receives this payment status notification.
U	The corresponding `result.resultCode` is "UNKNOWN_EXCEPTION" and `result.resultMessage` is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section. 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 response (almost never occur), the wallet will process like `U`.
F	That means this transaction is failed. The corresponding `result.resultCode` and `result.resultMessage` vary based on different situations. For details, see the following Error codes section. 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 OpenAPIs.
API-specific error codes: are listed in the following table.

resultStatus	resultCode	resultMessage
F	REPEAT_REQ_INCONSISTENT	There are repeated request submissions, and requests are inconsistent.

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 with payment success

copy
{
  "paymentId": "201911271907410100070000009999xxxx",
  "paymentRequestId": "2019112719074101000700000088881xxxx",
  "paymentAmount": {
    "currency": "USD",
    "value": "10000"
  },
  "paymentTime": "2019-11-27T12:02:01+08:30"
}

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.

copy
{
  "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

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
 }

result.resultStatus==S shows that merchant/partner already received this notification.