/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

Result

No

The result of a payment.

{

   "resultCode": "SUCCESS",

   "resultStatus": "S",

   "resultMessage": "success"  

 }

paymentAmount

Amount

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
{
    "memo": "memo"
}

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 follow:

resultStatus

Description 

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 responses (rarely occur), the wallet will process like `U`.

F

That means this transaction is failed. The corresponding result.resultCode  and result.resultMessage are various 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'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

/v2/payments/notifyPayment
  1. The mini program calls my.tradePay interface to do payment (Step 1).
  2. The wallet returns the payment result to the mini program (Step 5).
  3. 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

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

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.