目录

Querying Settlement Bills

Function

Downloads offline settlement bill files.

  1. To obtain the settlement bill API capabilities, the administrator needs to enable the function of obtaining the settlement bill API in Function settings on the Huawei Pay merchant platform. After the function is enabled, the settlement bill of the previous day is generated on the next day.

  2. Bills are automatically generated every day, regardless of whether transactions are generated. If the query date exceeds the limit or no file is generated, no file download information is returned. In other cases, file download information is returned.

  3. After the bills are downloaded, you are advised to traverse the attachment directory to obtain the .csv files for parsing.

  4. When parsing the file content, you need to consider schema updates such as adding new columns.

Scenario

This API is used to obtain the link for downloading the offline files of Huawei Pay merchants' settlement bills, helping you quickly complete fund reconciliation.

Prototype

Request Parameters

Request Header

Parameter Mandatory Type Description
Content-Type Yes String The value is application/json; charset=UTF-8.
PayMercAuth Yes String The value is a JSON string of PayMercAuth.

Request Query

Parameter Mandatory Type Description
billDate Yes String

Bill date. Only bills generated within 90 days can be queried. The value must be accurate to a specific day in the format of yyyyMMdd (for example, 20210101).

Bills of the current day cannot be downloaded. Only bills generated before 24:00 of the previous day can be downloaded. Bills of the current day are generally generated after 15:00 of the next day. In special cases (for example, system exceptions), the generation may be delayed.

Request Example

GET /v1/bill/settle-bill/downloadInfo?billDate=20221010 HTTP/1.1
Content-Type: application/json;charset=UTF-8
PayMercAuth: {"callerId":"10132120***","traceId":"202305151518027020519","time":1684135082153,"authId":"120291744647139***","headerSign":"KJfXV9wiYjV9dpV********************vobQngEKq02sOB0RbrxZIk2Hll20OSMNPBsO8PIWk3168=","bodySign":"mL8Kf2jy9c7A7Yh9az3NlETYdzgOfNzLBJ2l/feRfoMeYViiGQdYX********************/pbTViW2ypPM="}

Response Parameters

Response Header

Parameter Mandatory Type Description
Content-Type Yes String The value is application/json; charset=UTF-8.

Response Body

Parameter Mandatory Type Description
resultCode Yes String Result code. The value 000000 indicates success, and other values indicate failure.
resultDesc Yes String Result description.
subCode No String Service result code.
subDesc No String Service result description.
sign Yes String Signature, which is used to perform anti-tamper verification on response packets.
billDownloadParam No BillDownloadParam Bill download request information. The value is returned when bill data is generated.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "sign": "MEUCIGnmUY8Yg34Ma5NBwqYzLBd********************cRVu/W3HH+8WGGJsV3TA=",
  "resultCode": "000000",
  "resultDesc": "Success",
  "billDownloadParam": {
    "headers": {
      "Authorization": "AWS4-HMAC-SHA256 Credential=BJIIJMUMOQKXDCODXVCG/202211********************mz-date, Signature=e7275216278aebc548f413f899eb2f4d82011ed479087f0055c702fa6addc8e5",
      "x-amz-content-sha256": "UNSIGNED-PAYLOAD",
      "x-amz-client-request-id": "20210863286224479792",
      "x-amz-date": "20221103T005326Z",
      "connection": "close",
      "Host": "petalpay-merchant-test-001.obs.cn-north-4.myhuaweicloud.cn",
      "user-agent": "Apache-HttpAsyncClient/4.1.2 (Java/1.8.0_272)",
      "Content-Type": "application/octet-stream"
    },
    "method": "GET",
    "downloadUrl": "https://petalpay-merchant-test-001.obs.cn-north-4.myhuaweicloud.cn/xxxxxx.zip"
  }
}

Error Codes

For error codes of resultCode other than 400000, see Common Result Codes.

Return Code Error Code Description Solution
400000 NOT_SETTLEMENT_DATE The bill is not generated on the non-settlement day. Modify the input date and try again.
400000 INVALID_ARGUMENTS Invalid parameter. Check the request parameters.
400000 BILL_SWITCH_NOT_TURN_ON The bill switch is not turned on. Check and turn on the bill switch.
400000 UNKNOWN_ERROR Service temporarily unavailable. Try again later. Try again later.

Example of File Download

RestTemplate restTemplate = new RestTemplate(new HttpComponentsClientHttpRequestFactory(HttpClients.createSystem()));
HttpHeaders headers = new HttpHeaders();
// billResponse is the response object of the bill request API.
billResponse.getBillDownloadParam().getHeaders().forEach(headers::add);
HttpEntity<?> httpEntity = new HttpEntity<>(headers);
ResponseEntity<byte[]> responseEntity = restTemplate.exchange(billResponse.getBillDownloadParam().getDownloadUrl(), HttpMethod.GET, httpEntity, byte[].class, new Object[0]);
if (responseEntity.getStatusCode() == HttpStatus.OK) {
    // The path of the settlement bill 2022xxxx.zip can be customized.
    Files.write(Paths.get("./Settlement bill 2022xxxx.zip"), responseEntity.getBody());
}

Settlement Bill File Description

Field Mandatory Description Example Value
Settlement sheet No. Yes Order number allocated by Huawei Pay to the merchant number for settlement. 71306c214b2d486199e3c19a6******X
Settlement date Yes Date when Huawei Pay settles the transaction amount to the merchant's settlement account based on the settlement period of the merchant number. The format is yyyyMMdd. 20220826
Merchant name Yes Name of the Huawei Pay merchant that initiates the transaction. Test ****** merchant
Merchant number Yes Number of the Huawei Pay merchant that initiates the transaction. 1015******89
Transaction creation time Yes Time when the transaction is created, in the format of yyyyMMdd. 20220825
Transaction completion time Yes Time when the transaction is completed, in the format of yyyy-MM-dd HH:mm:ss. 2022-08-25 10:29:19
System transaction order No. Yes Order number allocated by Huawei Pay. 1220825102620000******857556
Merchant order No. Yes Merchant order number, which is passed by the merchant and corresponds to the mercOrderNo field in the order API. Imagazine_1661394******
Transaction type Yes

Type of the order, including but not limited to the following (more types may be added in the future):

- Receipt: order in which payment is collected through Huawei Pay

- Refund: order in which a refund is made to a user

- Allocation: order in which collected funds are allocated to a partner

- Allocated fund recovery (inflow): order in which funds are recovered from partners after allocation.

- Allocated fund recovery (outflow): order in which partners recover funds after allocation.

- Agreement-based allocation: order in which collected funds are allocated to a partner based on the allocation rules

- Freezing: order in which the settlement amount of a disputed transaction is frozen

- Unfreezing: order in which the settlement amount of a disputed transaction is unfrozen

- Merchant receipt: order in which payment is collected through Huawei Pay

- B2C transfer: order in which funds are transferred to a user's payment account

 Receipt
Product instance ID No Transaction product ID used in the order. 87178478298******0
Product name No Transaction product name used in the order. Quick payment by debit card
Bank name No Bank where the transaction in the order is made. ICBC
Card Type No

Bank card type used for this order transaction.

- Debit card

- Credit card

 Debit card
Transaction currency Yes

Transaction currency of the order.

The default value is CNY.

 CNY
Settlement amount (CNY) Yes Actual settlement amount of the order. The value can contain a maximum of two decimal places. 5.01
Order amount (CNY) Yes Total amount of the order, including the payment amount and discount amount. The value can contain a maximum of two decimal places. 5.01
Discount Amount (CNY) No Deduction and exemption amount of the order when the user makes the payment. The value can contain a maximum of two decimal places. 0
Handling fee amount (CNY) Yes Transaction handling fee generated by the order. The value can contain a maximum of two decimal places. 0.03
Handling fee collection mode Yes

Handling fee collection mode of Huawei Pay for the order. Generally, the mode is configured based on the merchant number. The options are as follows:

- Handling fee netting

- Handling fee collection after transaction

- Handling fee collection from the account

 Handling fee netting
Allocation type Yes

Order allocation mode. The options are as follows:

- No allocation

- Allocation

- Allocation recovery

- Agreement-based allocation

 No allocation
Partner merchant name No Merchant name of the party that initiates the fee allocation order. xyz
Partner merchant No. Yes Merchant number of the party that initiates the fee allocation order. 1015******89
Original system transaction order No. No Original transaction order number in the Huawei Pay system for refund or fee allocation. 124042317******0740873494880
Original merchant order No. No Original merchant order number for refund or fee allocation. czl00120******554112
Merchant reserved information No Merchant reserved information during pre-order. payload test
AppID No

App ID.

If app ID verification is not configured for merchant transactions, this parameter is left empty.

 5765880******8652727
User ID No

OpenID generated based on the merchant app ID.

If app ID verification is not configured for merchant transactions, this parameter is left empty.

 2248554******3012454
Handling fee receiver No Merchant ID to which the handling fee is charged. 1135******82