notifyPayment
1. Overview
Endpoint: /v1/payments/notifyPayment
This interface is used to notify the payment result to Issuing Participant when an AlipayHK payment processing reaches a final state of success or failure.
2. Sample
- After the AlipayHK payment is successful, the payment notification request is sent to Issuing Participant.
{
"paymentResult": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"success"
},
"paymentRequestId":"20200101234567890132",
"paymentId":"202001012345678901322222",
"paymentTime": "2020-01-01T12:01:01+08:30",
"paymentAmount":{
"value":"100",
"currency":"JPY"
},
"payToAmount":{
"value":"1000",
"currency":"KRW"
},
"customerId":"1234567",
"paymentPromoInfo":{
"paymentPromoDetails":[
{
"promoId": "2021011819050111540150009999900160350019673599",
"promoName": "滿10減1夏日優惠券活動",
"promoType": "CASHLESS_FIXED_VOUCHER",
"savingsAmount": {
"currency":"HKD",
"value":"100"
}
}
]
}
}- Issuing Participant processes the payment notification and returns the notification processing result to AlipayHK.
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"success"
}
}3. Structure
3.1 Request
No. | Field | Description |
1 | paymentResult | MANDATORY PaymentResult The payment result. The paymentResult.resultStatus field reflects the payment status, with S representing success and F representing failure. The payment result notification message doesn't have U for resultStatus. |
2 | paymentRequestId | MANDATORY String (64) The unique ID that is assigned by the payment initiator to identify an order payment |
3 | paymentId | OPTIONAL String (64) The unique ID that is assigned by the payment executor to identify a payment. This field is required when paymentResult.resultStatus is S. |
4 | paymentAmount | OPTIONAL Amount The amount that is collected by the payment executor. This field is required when paymentResult.resultStatus is S. |
5 | payToAmount | OPTIONAL Amount The amount that is paid by the payment executor. This field is required when paymentResult.resultStatus is S and payToAmount is not equal to paymentAmount. |
6 | paymentTime | OPTIONAL Datetime The date and time when the payment reaches a final state of success or failure. This field is required when paymentResult.resultStatus is S. |
7 | customerId | OPTIONAL String (64) The unique ID that is assigned by AlipayHK to identify a customer. This field is required when paymentResult.resultStatus is S. |
8 | paymentPromoInfo | OPTIONAL PaymentPromoInfo Payment promotion information. See PaymentPromoInfo for details. |
9 | passThroughInfo | OPTIONAL String (2048) Passthrough information in the set of key-value pairs that is transmitted between AlipayHK and participants |
3.2 Response
4. Result code
No. | resultCode | resultStatus | resultMessage |
1 | SUCCESS | S | Success |
2 | PROCESS_FAIL | F | A general business failure occurred. Don't retry. |
3 | PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. |
4 | KEY_NOT_FOUND | F | The key is not found. |
5 | ACCESS_DENIED | F | The access is denied. |
6 | REQUEST_TRAFFIC_EXCEED_LIMIT | U | The request traffic exceeds the limit. |
7 | INVALID_API | F | The called API is invalid or not active. |
8 | INVALID_CLIENT | F | The client is invalid. |
9 | INVALID_SIGNATURE | F | The signature is invalid. |
10 | METHOD_NOT_SUPPORTED | F | The server does not implement the requested HTTP method. |
11 | MEDIA_TYPE_NOT_ACCEPTABLE | F | The server does not implement the media type that is acceptable to the client. |
12 | UNKNOWN_EXCEPTION | U | An API calling is failed, which is caused by unknown reasons. |
5. PaymentResult
No. | resultCode | resultStatus | resultMessage |
1 | SUCCESS | S | Success |
2 | INVALID_CONTRACT | F | The contract is invalid. |
3 | INVALID_CODE | F | The code is invalid. |
4 | INVALID_TOKEN | F | The access token is invalid. |
5 | EXPIRED_CODE | F | The code is expired. |
6 | CURRENCY_NOT_SUPPORT | F | The currency is not supported. |
7 | USER_BALANCE_NOT_ENOUGH | F | The user balance is not enough for the payment. |
8 | USER_NOT_EXIST | F | The user does not exist. |
9 | USER_STATUS_ABNORMAL | F | The user status is abnormal. |
10 | USER_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the user payment limit. |
11 | PAYMENT_AMOUNT_EXCEED_LIMIT | F | The payment amount exceeds the limit. |
12 | PAYMENT_COUNT_EXCEED_LIMIT | F | The number of payments exceeds the limit. |
13 | ORDER_IS_CLOSED | F | The order is closed. |
14 | BUSINESS_NOT_SUPPORT | F | The payment business is not supported. |
15 | RISK_REJECT | F | The request is rejected because of the risk control. |
16 | PROCESS_FAIL | F | A general business failure occurred. Don't retry. |