DOCS

/v1/payments/inquiryBill

POST /v1/payments/inquiryBill

The inquiryBill API is used to inquire the merchant/partner settlement file's download urls. Settlement file is generated based on each settlement period and merchant can use the settlement file to implement the settlement reconciliation. For example, the merchant has signed up for T+1 day settlement. If today is exactly the settlement date for the merchant, the merchant can invoke this interface to query the bill download link and subsequently download the bill in order to perform reconciliation operations.

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

billDate

String 

Yes

The time the wallet generates the bill for the merchant.

Max. length: 16 characters.

"2023-09-13"

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

 }

billDownloadUrl

List<String> 

No

The download address of the merchant bill.

[ "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X"

]

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 bill download url inquiry is successful.

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 unknown exception occurs on the wallet side. The merchant/partner can try again.

F

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 bill download url inquiry is failed. When resultCode is BILL_NOT_EXIST, it means that the merchant's bill does not exist, the merchant needs to check whether the billDate is correct, and if so, the merchant/partner need try again.

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

F

BILL_NOT_EXIST

The bill is not exist.

Settlement File Description

Note: All monetary values in the fields of settlement file represent amounts 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.

Property

Required

Description

Example

settlement_batch_id

Yes

Settlement batch id.

"20230610111213810400166000000000076"

transaction_id

Yes

The unqiue ID of a transaction generated by Wallet.

"20240306111212800100166064300075xxx"

transaction_type

Yes

Transaction type, such as PAYMENT, REFUND, CANCEL, CAPTURE, etc.

"PAYMENT"

acquirement_id 

Yes

The unqiue ID of a payment generated by Wallet.

"20240306111212800100166064300075xxxx"

merchant_id

Yes

Merchant ID.

"216620000000032419xxx"

settlement_date

Yes

The settlement date of the transaction."08/02/2024"
transaction_amount

Yes

The transaction amount.

500

transaction_currency

Yes

The three-character ISO-4217 currency numeric code.

368

transaction_date

Yes

The transaction date.

It follows the ISO 8601 standard.

"2024-02-07T17:09:15+03:00"

original_transaction_id

No

The original transaction id, If the current transaction is a refund, then it originalTransactionId is the paymentId.

"20240306111212800100166064300075xxx"

original_transaction_date

No

The original transaction time, If the current transaction is a refund, then it originalTransactionDate is the payment time.

"2024-02-07T17:09:15+03:00"

merchant_commission

Yes

The wallet charged the commission from the merchant.

Note: merchant_commission = merchant_mdr + merchant_vas.

0

merchant_mdr

Yes

The wallet charged the mdr(merchant discount rate) from the merchant.

0

merchant_vas

Yes

The wallet charged the vas(Value Added Service) from the merchant.

0

settle_amount

Yes

The settlement amount is always positive number.

Note: settle_amount = transaction_amount - merchant_commission

500

pay_method

Yes

The user's payment method for a single transaction, several pay_methods will be split by "|".

"BALANCE"

"DEBIT_CARD|COUPON"

merchant_cust_id

No

Input by merchant, to identify user in merchant system

"216610000000032419xxx"

shop_id

No

According by settle unit of merchant, if the settle unit is SHOP&REGION, the shop id will exist in settle file.

"216660000000018175xxx"

shop_name

No

According by settle unit of merchant, if the settle unit is SHOP&REGION, the shop name will exist in settle file.

في حالة كتابة الاسم بالحروف اللاتينية،

contract_id 

Yes

The unqiue ID of merchant conrtact generated by Wallet.

"20230609510510100100000306xxx"

settlement_currency

Yes

The three-character ISO-4217 currency numeric code.

368

product_code

Yes

The unqiue ID of acquiring product generated by Wallet.

"51051000101000100011"

payment_time

Yes

The transaction payment time.

"2024-02-07T17:09:15+03:00"

transaction_request_id 

No

The unqiue ID of generated by merchants when Initiate a request.

"UDQzzvxwyvrUDxGqhMlHUIBpGkydOQC6"

original_transaction_request_id 

No

The original transaction request id, If the current transaction is a refund, then it originalTransactionRequestId is the payment request id.

"UDQzzvxwyvrUDxGqhMlHUIBpGkydOQX6"

coupon_currency

No

The three-character ISO-4217 currency numeric code.

368

coupon_amount

No

The payment amount of coupon when the user pays by coupon.

500

merchant_name

Yes

The name of Merchant in Arabic.

"التاجر للاختبار"

Sample

For example, the merchant has signed up for T+1 day settlement. If today is exactly the settlement date for the merchant, the merchant can invoke this interface to query the bill download link and subsequently download the bill in order to perform reconciliation operations.

inquiryBill.png

  1. In T+N day, the merchant backend calls inquiryBill API to inquiry bill download url.
  2. The E-Wallet backend returns bill download url to the merchant backend.
  3. If the resultCode is BILL_NOT_EXIST, the merchant needs to check whether if the billDate is correct,
    1. if correct, please send inquiry request again.

Request

copy
{
 "billDate":"2023-09-13"
}
  • billDate the time the wallet generates the bill for the merchant.

Response

copy
{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "Success."
    },
      "billDownloadUrl": [
        "http://bill-demo.aliyuncs.com/download/settlement/20230819/216620000000214839721/settlement.zip?Expires=1694840478&OSSAccessKeyId=LTAI5tJVdEQQQQ&Signature=Ga8FM8XXXX"
    ]
}
  • billDownloadUrl the download address of the merchant bill.

Settlement File

📎merchant_settlement_216620000000121329xxx_DEFAULT_DEFAULT_20240208.csv