/v1/payments/notifyPayment

2021-07-21 11:23

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

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
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	Amount	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	`SUCCESS` - order is succeeded. `FAIL` - order is failed.
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	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

copy

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

copy

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

copy

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

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