/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

Result

No

The result of a payment.

{

   "resultCode": "SUCCESS",

   "resultStatus": "S",

   "resultMessage": "Success."  

 }

paymentAmount

Amount

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

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 result.resultCode is "SUCCESS" and the  result.resultMessage  is "Success".

It means that the merchant/partner already receives this payment status notification.

U

The corresponding result.resultCode is "UNKNOWN_EXCEPTION" and result.resultMessage  is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.

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 result.resultCode  and result.resultMessage vary based on different situations. For details, see the following Error codes section.

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.

cashierPay.png

  1. The Mini Program calls this my.getAuthCode JSAPI with specific scopes(USER_ID) to request an authorization code.
  2. The E-wallet App service calls authorization service to processes the authorization information.
  3. The E-wallet backend verifies the authorization information, generates the authCode and returns.
  4. The E-wallet App service returns the authCode to the Mini Program.
  5. The Mini Program sends the authCode to the merchant backend.
  6. The merchant backend calls the applyToken API with authCode to apply the accessToken.
  7. The E-Wallet backend returns accessToken information to the merchant backend, such as customerId, accessToken, refreshToken, etc.
  8. The Mini Program creates an order with customerId.
  9. The merchant backend calls the payment API to initialte payment flow, including customerId as referenceBuyerId, paymentNotifyUrl(optional), etc.
  10. The E-Wallet backend returns payment detail information the merchant backend, such as redirectionUrl.
  11. The merchant backend passes the payment detail information to the Mini Program.
  12. The Mini Program calls the my.tradePay JSAPI with redirectionUrl to conduct the payment.
  13. The E-Wallet App Service displays the cashier page with order information, such as amount, order details, etc.
  14. The user confirms the payment in the cashier page.
  15. The E-Wallet App Service calls payment service and execute the payment process.
  16. When the payment reaches the final status, the E-wallet backend returns the payment result to the Mini Program (Step 18).
  17. Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 10(Step 19).
  18. Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 20).

Payment

A. Request with payment success

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

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

copy
{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"Success."
  }
 }
  • result.resultStatus==S  shows that merchant/partner already received this notification.