/v1/payments/notifyPayment

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

/v1/payments/notifyPayment
  1. The Mini Program calls my.tradePay interface to do payment (Step 1).
  2. E-wallet App returns payment result to the Mini Program (Step 5).
  3. 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.

B.

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.