/v1/payments/pay

POST /v1/payments/pay

The pay API is used to initiate a payment request to wallets.

Note: A payment which takes place at wallets.

1)The merchant/partner initiates a payment request to wallet through this interface.

2)The wallet will handle different payment scenarios based on the parameters in the request.

Currently, this API support following scenarios:

  • Cashier payment:Usually used in the online payment scenario. In this scenario, the merchant/partner will call this API to create an order, and the wallet will return the cashier page URL to the merchant/partner, and then redirect to this cashier page. So user can finish the payment in the cashier page.

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

productCode

String 

Yes

Defined by wallets. The wallet uses the productCode to get the contract configuration which includes fee, limitation information, and so on.

Max. length: 32 characters.

  • Online Purchase: "51051000101000000011"
  • Online Purchase(Auth Capture):"51051000101000000012"
  • Agreement Payment: "51051000101000100031"

paymentRequestId

String 

Yes

The unqiue ID of a payment generated by merchants.

  • Max. length: 64 characters.
  • This field is used for idempotence control. For the payment requests which are initiated with the same paymentRequestId and reach a final status (S or F),  the wallet must return the unique result.

"UDQzzvxwyvrUDxGqhMlHUIBpGkydOQC6"

paymentAuthCode

String

No

The payment auth code generated by the wallet, such as the accessToken in the agreement pay scenario.

Max. length: 128 characters.

"000000000220231001JfQ6vpiUNV79nT00006725"

paymentAmount

Amount

Yes

The order amount, displaying users' consumption records, payment results page.

Note: The monetary unit of value is fils.

e.g. if the price is 150 IQD, then the paymentAmount.value should be 150000.

{

  "currency": "IQD",

  "value": "150000"

}

order

Order

Yes

The purchase order details, such as Merchant, Buyer, Goods, etc. The information in the Order is only used to display user's payment result page and transactions history, regulation reporting, etc. It will not make use of the amount in the order for fund operation.

The buyer field is optional only in the Agreement Payment scenario.

{

  "orderDescription": "order description",

  "buyer": {

  "referenceBuyerId": "21661000000003660xxxx"

  }

}

paymentExpiryTime

String/Datetime

No

The payment order close time defined by merchant, which means the payment order will be closed automatically after paymentExpiryTime. If empty, the expiryTime will be defined by E-wallet.

It follows the

ISO 8601 standard.

"2024-01-18T16:10:36+03:00"

paymentRedirectUrl

String 

No

The redirect URL defined by merchants.

Max. length: 1024 characters.

"https://www.merchant.com/redirectxxx"

paymentNotifyUrl

String 

No

The payment success notification URL defined by merchants.

Max. length: 1024 characters.

"https://www.merchant.com/paymentNotifyxxx"

voidNotifyUrl

String

No

The url that void notification will be sent to.

Max. length: 1024 characters.

"https://www.merchant.com/voidNotifyxxx"

extendInfo

String 

No

The extensive information. The wallet and merchant can put extensive information in this property. The format shoud be JSON format.

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 related to the request result, such as status and error codes.

{

   "resultCode": "SUCCESS",

   "resultStatus": "S",

   "resultMessage": "Success."  

 }

paymentId

String 

No

The unqiue ID of a payment generated by Wallet.

Max. length: 64 characters.

"2023120611121280010016600090000xxxx"

paymentTime

String/Datetime

No

Payment success time, which follows the ISO 8601 standard.

"2023-01-08T12:12:12+08:00"

redirectActionForm

RedirectActionForm

No

Indicates a redirect URL.

{

   "redirectionUrl":"https://www.wallet.com/cashier?orderId=xxxxxxx"

}

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.".

That means that this transaction is successful. The merchant/partner can update transaction to success.

A

The corresponding result.resultCode is "ACCEPT"; and the  result.resultMessage varies based on different situations.

That means that the transaction is already accepted by wallets. The merchant/partner needs to continue the next operation according to the redirectActionForm  response, such as display the order code to users or redirect to the wallet cashier page.

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.

That means that unknown exception occurs on the wallet side. The merchant/partner can inquiry the payment result or wait for the payment status notification to get the real payment result. What needs to note is :

  • Payment evaluation scenario can not be inquiried.
  • `U` status can not set to fail or success on the merchant/partner system.
  • `U` status can not refund to users by offline (Maybe will make fund loss).

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.

Usually the `F` transactions can not be successful again if use the same payment request to call wallets.

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

PAYMENT_IN_PROCESS

The payment is still under process.

F

REPEAT_REQ_INCONSISTENT

Repeated submission, and requests are inconsistent.

F

PAYMENT_AMOUNT_EXCEED_LIMIT

Payment amount exceeds limit.

F

USER_NOT_EXIST

The user does not exist.

F

USER_STATUS_ABNORMAL

The user status is abnormal.

F

USER_BALANCE_NOT_ENOUGH

The user balance is not enough for this payment.

F

PARTNER_NOT_EXIST

The partner does not exist.

F

PARTNER_STATUS_ABNORMAL

The partner status is abnormal.

F

RISK_REJECT

Risk reject.

F

CURRENCY_NOT_SUPPORT

The currency is not supported.

F

ORDER_STATUS_INVALID

Order is in invaid status such closed.

F

INVALID_ACCESS_TOKEN

Invalid accesstoken.

F

USER_AMOUNT_EXCEED_LIMIT

Payment amount exceeds user's amount limit.

F

AUTH_CODE_ALREADY_USED

Auth code already used.

F

INVALID_CODE

Auth code illegal.

Sample

Cashier Payment

For example, a user purchases a 100 IQD good at the merchant/partner(online merchant usually) , the merchant/partner calls this API to create the payment order first, the wallet will return the payment order ID and wallet cashier page URL to the merchant/partner, then merchant/partner can redirect user to wallet cashier page with the my.tradePay  API.

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).

Request

copy
{
    "productCode": "51051000101000000011",
    "paymentRequestId": "UDQzzvxwyvrUDxGqhMlHUIBpGkydOQC6",
    "paymentAmount": {
        "currency": "IQD",
        "value": "116000"
    },
    "order": {
        "orderDescription": "order description",
        "buyer": {
            "referenceBuyerId": "21661000000003660xxxx" 
        }
    },
    "paymentExpiryTime": "2024-01-18T16:10:36+03:00",
    "paymentNotifyUrl":"https://www.merchant.com/paymentNotifyxxx"  
}
  • paymentRequestId is generated by the merchant/partner, which uniquely identifies the payment. Wallet must make use of paymentRequestId for idempotent control. For example, if a payment with paymentRequestId== 2023112719074101000700000077771 has been processed successfully by Wallet, when the merchant/partner uses the same paymentRequestId for payment, Wallet will respond with sucessful payment.
  • productCode is the product code, The wallet uses the productCode to get the contract configuration which includes fee, limitation information, and so on.
    • Online Purchase: "51051000101000000011"
    • Online Purchase(Auth Capture): "51051000101000000012"
    • Agreement Payment: "51051000101000100031"
  • paymentNotifyUrl is the URL defined by the merchant/partner.  In the cashier payment scenario, after the user finished payment in the wallet cashier page, the wallet will notify the merchant of the payment result based on this URL.
  • paymentAmount describes the amount of 100 IQD to be collected by Wallet from user's account for this payment.
  • order describes the order details of the purchase of the 100 IQD merchandise by the  user at the  merchant. Such as Merchant, Buyer, Goods, etc are included in order. The information in the Order is only used to  display user's payment result page and transactions history,  regulation reporting, etc.
  • referenceBuyerId is the unique userID, which can be customerId obtained from accessToken information in applyToken API. It must not be default. Please make sure the buyer and the payer is the same person.
  • paymentExpiryTime is the payment order close time defined by merchant, which means the payment order will be closed automatically after paymentExpiryTime. If empty, the expiryTime will be defined by E-wallet.

Response

copy
{
 "result": {
    "resultCode":"ACCEPT",
    "resultStatus":"A",
    "resultMessage":"accept"
 },
 "paymentId": "2023120611121280010016600090000xxxx",
 "redirectActionForm":{
    "redirectionUrl":"https://www.wallet.com/cashier?orderId=xxxxxxx"
 }
}
  • result.resultStatus ==A shows that the  payment is accept success. After user finish payment in cashier page, payment will change to success.
  • paymentId is generated by Wallet, uniquely identifies the payment.
  • redirectActionForm returns the cashier page URL to the merchant/partner. After the merchant/partner receives the accept result, which will be redirected to this URL.

Agreement Payment

For example, a user authorizes a AgreementPay contract at the merchant/partner(online merchant usually), such as monthly subscription, the merchant/partner can call this API to automatically deduct money from the user's wallet without user's operation.

agreementPay.png

  1. The Mini Program calls merchant backend to prepare the contract.
  2. The merchant backend calls this prepare API with contract information to prepare the contract.
  3. The E-Wallet backend returns authorization information to the merchant backend, such as authorizationUrl.
  4. The merchant backend passes the authorization information to the Mini Program.
  5. The Mini Program calls the my.call("qicardSignContract") JSAPI with authorizationUrl to conduct the authorization.
  6. The E-Wallet App Service displays the authorization page with contract information provided in Step 2.
  7. The user confirms the authorization agreement pay in the authorization page.
  8. The E-Wallet App Service calls authorization service and execute the authorization process.
  9. When the authorization reaches the final status, the E-wallet backend returns the authCode to the Mini Program (Step 10).
  10. The Mini Program sends the authCode merchant backend.
  11. The merchant backend calls this applyToken API with authCode to apply the accessToken(Step 12).
  12. The E-Wallet backend returns accessToken information to the merchant backend, such as accessToken, refreshToken, etc.
  13. The merchant backend calls this payment API with accessToken to deduct money from user's balance silently without user operation(Step 14).
  14. The E-wallet backend returns the payment result to the merchant backend instantly(Step 15).
  15. Also the E-wallet backend notifies the merchant backend of the payment result with paymentNotifyUrl provided in Step 14(Step 16).
  16. Finally, E-wallet backend notifies the user of the payment result via SMS/Email/Inbox message (Step 17).

Request

copy
{
  "productCode": "51051000101000100031",
  "paymentRequestId": "UDQzzvxwyvrUDxGqhMlHUIBpGkydOQC6",
  "paymentAuthCode": "000000000220231001JfQ6vpiUNV79nT00006725",
  "paymentAmount": {
    "currency": "IQD",
    "value": "116000"
  },
  "order": {
    "orderDescription": "order description"
  },
  "paymentExpiryTime": "2024-01-18T16:10:36+03:00",
  "paymentNotifyUrl": "https://www.merchant.com/paymentNotifyxxx"
}
  • paymentRequestId is generated by the merchant/partner, which uniquely identifies the payment. Wallet must make use of paymentRequestId for idempotent control. For example, if a payment with paymentRequestId== 2023112719074101000700000077771 has been processed successfully by Wallet, when the merchant/partner uses the same paymentRequestId for payment, Wallet will respond with sucessful payment.
  • productCode is the product code, The wallet uses the productCode to get the contract configuration which includes fee, limitation information, and so on.
  • paymentNotifyUrl is the URL defined by the merchant/partner.  In the cashier payment scenario, after the user finished payment in the wallet cashier page, the wallet will notify the merchant of the payment result based on this URL.
  • paymentAmount describes the amount of 100 IQD to be collected by Wallet from user's account for this payment.
  • order describes the order details of the purchase of the 100 IQD merchandise by the  user at the  merchant. Such as Merchant, Buyer, Goods, etc are included in order . The information in the Order is only used to  display user's payment result page and transactions history,  regulation reporting, etc.
  • paymentAuthCode was generated by the wallet is the accessToken in the agreement pay scenario.
  • paymentExpiryTime is the payment order close time defined by merchant, which means the payment order will expire automatically after paymentExpiryTime. If empty, the expiryTime will be defined by E-wallet.

Response

copy
{
  "result": {
    "resultStatus": "S",
    "resultCode": "SUCCESS",
    "resultMessage": "Success."
  },
  "paymentId": "20231030111212800100166794100052745",
  "paymentTime": "2023-10-30T09:17:13+03:00"
}
  • result.resultStatus ==S shows that the  payment is success.
  • paymentId is generated by Wallet, uniquely identifies the payment.
  • paymentTime is generated by Wallet, it shows the payment finish time.