/v2/miniprogram/transaction/notify

2021-07-21 11:23

POST /v2/miniprogram/transaction/notify

The notify API is used to require Mini Program to return a transaction result notification, for example, a payment or refund result, to wallets.

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
appId	String	Yes	The Mini Program App ID. Max. length: 32 characters.	"A00990049949xxxx"
productCode	String	No	The product code, including `AGREEMENT_PAYMENT` , `IN_STORE_PAYMENT` , or `CASHIER_PAYMENT` Max. length: 32 characters.	"CASHIER_PAYMENT"
paymentRequestId	String	Yes	The unique ID of payment is generated by merchants. Max. length: 64 characters.	"2019112719074101000700000077771xxxx"
paymentId	String	Yes	The unique ID of payment is generated by Wallets. Max. length: 64 characters.	"4374784884773748478499xxxx"
paymentAmount	Amount	Yes	The order amount, which is displayed in the user's consumption records on the payment results page.	{ "currency": "USD", "value": "10000" }
order	Order	No	The purchase order details, such as merchants, buyers, goods, and so on. The information in the `order` is only used to display a user's payment result page and transactions history, regulation reporting, and so on. It does not use the amount in the `order` for fund operation.	{ "referenceOrderId":"ID_0101010101xxxx", "orderDescription":"SHOES", "orderAmount":{ "currency": "USD", "value": "10000" }
paymentMethod	PaymentMethod	No	It is used to collect funds by wallets.	{ "paymentMethodType":"ID_000001xxxx", "paymentMethodId":"1" }
userId	String	No	The hashed unique identifier is allocated for a user. Max. length: 64 characters.	"2087848849498xxxx"
paymentStatus	String	No	`SUCCESS` - an order succeeds `FAIL` - an order fails `CANCELLED` - an order is canceled	"SUCCESS"
paymentTime	String/Datetime	No	The payment success time, which follows the ISO 8601 standard.	"2020-01-01T12:01:01+08:30"
refundId	String	No	The unique ID of a refund is generated by Wallets. Max. length: 64 characters.	"4374784884773748478499xxxx"
refundAmount	Amount	No	The refund amount, which is displayed on the user's consumption records page.	{ "currency": "USD", "value": "10" }
refundStatus	String	No	`SUCCESS` - a refund succeeds. `FAIL` - a refund fails.	"SUCCESS"

Response

Property

Data type

Required

Description

Example

result

Result

Yes

The request result, which contains information like 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	Description
S	The request is successful. The corresponding `result.resultCode` is "SUCCESS" and the `result.resultMessage` is "Success".
U	The API status 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 request fails. The corresponding `result.resultCode` and `result.resultMessage` are various 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 all Mini Program OpenAPIs.
API-specific error codes: the current OpenAPI does not have its dedicated error codes.

Sample

Request to notify a payment result

copy

{
    "appId":"A00990049949xxxx",
    "productCode": "CASHIER_PAYMENT",
    "paymentRequestId": "2019112719074101000700000077771xxxx",
    "paymentId": "4374784884773748478499xxxx",
    "paymentAmount": {
        "currency": "USD",
        "value": "10000"
    },
    "order":{
      "referenceOrderId":"ID_0101010101xxxx",
      "orderDescription":"SHOES",
      "orderAmount":{
        "currency": "USD",
        "value": "10000"
      },
    "paymentMethod":{
      "paymentMethodType":"ID_000001xxxx",
      "paymentMethodId":"1"
    },
    "userId": "2087848849498xxxx", 
    "paymentStatus": "SUCCESS", 
    "paymentTime": "2020-01-01T12:01:01+08:30"
}

Request to notify a refund result

copy

{
    "appId":"A00990049949",
    "productCode": "CASHIER_PAYMENT",
    "paymentRequestId": "2019112719074101000700000077771xxxx",
    "paymentId": "4374784884773748478499xxxx",
    "paymentAmount": {
        "currency": "USD",
        "value": "10000"
    },
    "order":{
      "referenceOrderId":"ID_0101010101xxxx",
      "orderDescription":"SHOES",
      "orderAmount":{
        "currency": "USD",
        "value": "10000"
      },
    "userId": "2087848849498xxxx", 
    "refundId": "4374784884773748478499xxxx",
    "refundAmount": {
        "currency": "USD",
        "value": "10"
    },
    "refundStatus": "SUCCESS"
}

Response

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S"
 }
}