/v1/payments/notifyPayment

2021-08-06 01:49

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

Request

Property	Data type	Required	Description
paymentId	String (64)	Yes	The unqiue ID of a payment generated by Wallet.
paymentRequestId	String (64)	Yes	The unqiue ID of a payment generated by Wallet merchants.
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.
paymentResult	JSON	Yes	resultStauts: `S` - order is succeeded. `F` - order is failed.
paymentFailReason	String (256)	No	The fail reason of payment order when paymentStatus is FAIL.
extendInfo	String (4096)	No	The extend information,wallet and merchant can put extend info here.

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 10000 MYR merchandise at a merchant/partner, after user finished payment in wallet cashier page, wallet will send payment notification to merchant/partner.

Payment

A. Request sample with payment success

copy
{
    "paymentResult": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "success"
    },
    "paymentId": "20210726111212800110171163001220213",
    "paymentRequestId": "6-20210714041658535w",
    "customerId": "1000000839990000",
    "paymentTime": "2021-07-26T12:13:50+08:00",
    "paymentAmount": {
        "currency": "MYR",
        "value": "10000"
    }
}

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 10000 MYR already collected by Wallet from user account for this payment.
paymentTime is the success date time of this transaction.
paymentResult is the payment status in wallet. resultStatus "S" means transaction already success.

B. Request sample with payment failed

copy
{
    "paymentResult": {
        "resultStatus": "F",
        "resultCode": "ORDER_IS_CLOSED",
        "resultMessage": "ORDER_IS_CLOSED"
    },
    "paymentId": "20210722111212800110171936301182782",
    "paymentRequestId": "6-20210722010156790E",
    "customerId": "216810000000000090000"
}

paymentResult is the payment status in wallet. resultStatus "F" 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.