/v2/payments/notifyPayment

2023-05-31 12:13

POST /v2/payments/notifyPayment

With this API call, the super app can send the payment result to the merchant when the payment processing reaches a final state of success or failure.

Note: When the merchant develops this API, the merchant needs to follow the specifications below.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
paymentId	String	Yes	Indicates the unique ID assigned by the super app to identify a payment. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"201911271907410100070000009999xxxx"
paymentRequestId	String	Yes	Indicates the unique ID assigned by the merchant to identify a payment request. Maximum length: 64 characters Characters not allowed: special characters such as @ # ?	"2019112719074101000700000088881xxxx"
paymentResult	Result	Yes	Indicates details about the payment result, such as payment status, result code, and result message.	{ "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "success" }
paymentAmount	Amount	Yes	Indicates the payment amount that the merchant requests to receive.	{ "currency": "USD", "value": "10000" }
paymentTime	Datetime	No	Indicates the actual date and time when the payment is successful. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30". Note: This field is required when the payment processing reaches the final state of success.	"2019-11-27T12:02:01+08:30"
paymentCreateTime	Datetime	Yes	Indicates the actual date and time when the payment is created. The value follows the ISO 8601 standard format. For example, "2019-11-27T12:01:01+08:30".	"2019-11-27T12:02:01+08:30"
extendInfo	String	No	Indicates the extended information about this API. Maximum length: 4096 characters Characters not allowed: special characters such as @ # ? Can be `Null`.	{ "memo": "memo" }

Response parameters

Field

Data type

Required

Description

Example

result

Result

Yes

Indicates the request result, which is used to notify the super app whether the merchant received the notification.

{

"resultCode": "SUCCESS",

"resultStatus": "S",

"resultMessage": "success"

}

Result process logic

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

Result status	Description
S	The notification is sent successfully. No further action is needed. The corresponding result.resultCode is `SUCCESS` and the result.resultMessage is `Success`.
U	The status of the notification is unknown. 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.
F	The notification fails to send. The corresponding result.resultCode and result.resultMessage vary based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common for mini program's Open APIs in V2.
API-specific error codes are listed in the following table:

Error code	Result status	Error message	Further action
REPEAT_REQ_INCONSISTENT	F	The payment request is duplicated with the previous one.	For a new request, use another paymentRequestId.

Samples

The data flow of sending the payment result is illustrated as below:

The super app calls this API to notify the merchant server of the payment result.
The merchant server returns the result of whether it received the payment result.

Request

Send result of a successful payment

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

The payment is processed successfully at the paymentTime (2019-11-27T12:02:01+08:30).
The total payment amount is 100 USD.

Send result of a failed payment

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"
}

The payment (201911271907410100070000009999xxxx) is initiated at the paymentCreateTime (2019-11-27T12:01:01+08:30) but fails to complete at the paymentTime (2019-11-27T12:02:01+08:30).
The total payment amount is 100 USD.

Response

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

The value of result.resultStatus is S, which shows that the payment result is sent successfully.