/v1/payments/notifyPayment
POST /v1/payments/notifyPayment
The notifyPayment
API is used to notify the merchant/partner of the payment result.
Note:
- Follow the specifications below when the merchant develops this API.
- It is to notify the merchant/partner of the payment result when the payment processing reaches the final state (Success/Fail).
- It is not applied for all payment scenarios. For example, in the sync payment scenario (B Scan C, auto-debit payment), the merchant/partner does not need to receive this notification.
Note: All monetary values in the fields of request and response in their smallest currency units, and for IQD, the smallest unit is fils. Thus, if a transaction amount is 150 IQD, the value will be gaven as 150000.
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 |
paymentId | String | Yes | The unqiue ID of a payment generated by Wallet. Max. length: 64 characters. | "2023120611121280010016600090000xxxx" |
paymentRequestId | String | Yes | The unqiue ID of a payment generated by merchants. Max. length: 64 characters. | "2023112719074101000700000088881xxxx" |
paymentResult | No | The result of a payment. | { "resultCode": "SUCCESS", "resultStatus": "S", "resultMessage": "Success." } | |
paymentAmount | Yes | Order amount for display of user consumption records, payment results page. | { "currency": "IQD", "value": "10000" } | |
paymentTime | String/Datetime | No | Payment success time, which follows the ISO 8601 standard. | "2023-11-27T12:02:01+08:30" |
paymentCreateTime | String/Datetime | No | Payment creation time, which follows the ISO 8601 standard. | "2023-11-27T12:02:01+08:30" |
extendInfo | String | No | The extend information,wallet and merchant can put extend info here. Max. length: 2048 characters. | "extendInfo: This is additional information" |
Response
Property | Data type | Required | Description | Example |
result | Yes | The request result, which contains information such as 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 | Decription |
S | The corresponding It means that the merchant/partner already receives this payment status notification. |
U | The corresponding It means that when the merchant/partner handles this notification, an unknown exception occurs. The wallet can retry if get the `U` response. If other response (almost never occur), the wallet will process like `U`. |
F | That means this transaction is failed. The corresponding It means that the merchant/partner fails to handle this notification request. |
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: are listed in the following table.
resultStatus | resultCode | resultMessage |
U | SYSTEM_ERROR | The receiver has some unknown exceptions when processing this notice. When a sender gets this error code, the sender will retry to deliver. |
F | REPEAT_REQ_INCONSISTENT | There are repeated request submissions, and requests are inconsistent. |
Sample
For example, a wallet user purchases a 100 IQD merchandise at a merchant/partner, after user finished payment in wallet cashier page, wallet will send payment status notification to merchant/partner.
- The Mini Program calls this my.getAuthCode JSAPI with specific scopes(USER_ID) to request an authorization code.
- The E-wallet App service calls authorization service to processes the authorization information.
- The E-wallet backend verifies the authorization information, generates the authCode and returns.
- The E-wallet App service returns the authCode to the Mini Program.
- The Mini Program sends the authCode to the merchant backend.
- The merchant backend calls the applyToken API with authCode to apply the accessToken.
- The E-Wallet backend returns accessToken information to the merchant backend, such as customerId, accessToken, refreshToken, etc.
- The Mini Program creates an order with customerId.
- The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
- The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
- The merchant backend passes the payment detail information to the Mini Program.
- The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
- The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
- The user confirms the payment in the cashier page.
- The E-Wallet App Service calls payment service and execute the payment process.
- When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 18).
- Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10(Step 19).
- Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).
Payment
A. Request with payment success
{
"paymentId": "2023120611121280010016600090000xxxx",
"paymentRequestId": "2023112719074101000700000088881xxxx",
"paymentAmount": {
"currency": "IQD",
"value": "10000"
},
"paymentTime": "2023-11-27T12:02:01+08:30",
"paymentCreateTime": "2023-11-27T12:01:01+08:30",
"paymentResult": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"Success."
}
}
- 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 IQD already collected by Wallet from user account for this payment.
- paymentTime is the success date time of this transaction.
B. Request with payment fail
{
"paymentId": "2023120611121280010016600090000xxxx",
"paymentRequestId": "2023112719074101000700000088881xxxx",
"paymentAmount": {
"currency": "IQD",
"value": "10000"
},
"paymentCreateTime": "2023-11-27T12:01:01+08:30",
"paymentResult": {
"resultCode":"PROCESS_FAIL",
"resultStatus":"F",
"resultMessage":"Process fail."
}
}
Response
{
"result": {
"resultCode":"SUCCESS",
"resultStatus":"S",
"resultMessage":"Success."
}
}
- result.resultStatus==S shows that merchant/partner already received this notification.