Statement Download

Overview

Merchants can use this interface to download historical financial reports. The downloaded .zip file contains three types of statements:

1. Transaction Statement
   This includes all transactions such as payments, refunds, and transfers. Merchants can use this report to verify the accuracy of order statuses. For example, if discrepancies arise between the merchant’s records and the payer’s data due to issues like missing orders or system errors, this statement helps identify and correct payment statuses.

2. Settlement Statement
   This covers all settled payments, including detailed breakdowns of transactions and associated fees. Merchants can use it to reconcile the funds received from PayBy, understand deductions such as refunds and adjustments, and review the fees withheld for each transaction.

3. Fund Statement
   This outlines changes in the account balance, detailing all inflows and outflows. It provides a clear view of the merchant account’s financial movements.

---

Note:

1. Orders that failed to be placed successfully on PayBy’s side will not appear in the statements.
2. PayBy generates the previous day’s statements shortly after the merchant’s configured settlement cutoff time—typically within 10 minutes. It is recommended to download the statements at least 30 minutes after the cutoff.
3. All monetary values in the statements are denominated in AED (Dirhams).

---

API URL

• UAT : https://uat.test2pay.com/sgs/api/acquire2/download/getOrderStatement
• Production : https://api.payby.com/sgs/api/acquire2/download/getOrderStatement

Request

Http Header

Attributes

• Content-Language String

  • Language in which the response message will be used.
  • Currently, only English is supported.
  • Example value: en
  • Maximum length: 10

• Content-Type String Required

  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/<format> (e.g., application/json)
  • Example value: application/json

• sign String Required

  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.

• Partner-Id String Required

  • Merchant ID of your account.
  • Example value: 200001200101
  • Maximum length: 12

Http Body

• requestTime Timestamp Required

  • If the request time is more than 15 minutes away from the current time, the request will be rejected.
  • This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.
  • Example value: 1581493898000

• bizContent Object

  • statementDate String Required
    • The statement of which day you will download.
    • Format: YYYYMMDD
    • Example value: 20200120
    • Maximum length: 8

Request Sample

// Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018128",
    "sign": "RXF8WmC67QSnr62l3oU33fjpUvAo6Yrgvk05c/vYLtmHRGMoAH4qSnap2pto3mY7KgyP5wkNUsyQXJ/ZwbfccSONLb5zA7Z7q74IsOwdJw3BKXxVWr4tfjkA02Pfcp0cZWjE/Y8jTcbtgdc5VI90LNmkgPWbrSlDbNW8p3NlhnKg+Xfl95SgMBPF9afttsU/2a5jLnZXSVcXoSthxpJ6XkZwd45+jhOjBguT+IC8uLVSNRvwDisRGgf9PYv39OH6ITEhbY2sgjkdzBZBOZlt7awy2vkMEsePsuafwrNhuz7xzjj55PzNzk8+zCUu/791OhC/eFUyGimtDw5mX9cyQw=="
}

// Http Body
{
    "body": {
        "bizContent": {
            "statementDate": "20200605"
        },
        "requestTime": 1585142880000
    }
}

Response

If the request succeeded, the data will be returned as a compressed .zip file. If failed, the standard format of response will be returned.

Case 1: Response to Failed Statement Download Request

When a statement download request fails, the API returns an error response with specific headers and body content.

HTTP Header

• Content-Language String(10) Optional

  • Language code (e.g., en for English).
  • Example value: en

• Sign String Required

  • Digital signature for request verification.

• Partner-Id String(12) Required

  • Merchant identifier.

• Content-Type String(256) Required

  • MIME type of the response content.
  • Example value: application/json

HTTP Body

• head ResponseHeader Required
  • Contains response status and error information.

HTTP Header

{
    "sign": "VvlCywDHE0Pi35ypeJymje1GWHbDPhy3UJqPZTLnM0QqFa3QW+Yzc25kgsrB9t58c2oRdWo+stcvMhOeOgbrXNOhLAECD5bpSr2L1xEVhowd1k8tNlq+w2WhzUM0A77YVO2wapqqtBvsFi09o/ix7gCyX+850oLLxEEbbBR48fufVJxcOQ4y7bdkSufd+9gY4vdcJYMmnToSVQ72ObekhyZiXhT5zfnHjbFYGGpRXh/HvDiE+OGdTDYmHH4Ui+funH9kCg291/pWIV8Yp0hIQJ29cuJyCYsm1brkLopU1eak7fgculNo5SnCZH9nTIHYsIQtsMAXgI8q0MecBR2ovw=="
}

HTTP Body

{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "62013",
        "msg": "STATEMENT_NOT_EXIST",
        "traceCode": "1133"
    }
}

Case 2: Response to Successful Statement Download

When a statement download request succeeds, the API returns the data as a file stream containing a ZIP compressed file.

HTTP Header Parameters

• Content-Disposition String Required

  • File attachment information.
  • Example value: attachment; filename=200000054800_20210112Transaction_Settle_Statement.zip

• Content-Type String Required

  • MIME type indicating ZIP file format.
  • Example value: application/zip

File Structure and Naming Convention

After successful request processing, the system returns a ZIP file that contains CSV statement files when extracted.

File Name Formats

File Format	Example
PartnerId_dateTransaction_Settle_Statement.zip	200000054800_20210112Transaction_Settle_Statement.zip
Purchase_Statement_date_no.csv	Purchase_Statement_13012021_001.csv
Purchase_Settle_Statement_date_no.csv	Purchase_Settle_Statement_13012021_001.csv
PartnerId_date_fund_statement_no.csv	200000054800_20210112_fund_statement_001.csv

File Content Guidelines

The system generates different types of statement files with specific content rules:

1. Purchase_Statement files contain all orders with payment times on the statement date, excluding incomplete payments.
2. Purchase_Settle_Statement files contain all settlement orders with settlement times on the statement date.
3. Fund_statement files reflect all fund movements in the merchant account.
4. Each CSV file contains a maximum of 50,000 rows. When this limit is exceeded, the system generates additional numbered files starting from 001.

Transaction Statement File Format

Transaction statement files follow a specific three-row structure for data organization.

File Structure

1. Row 1: Summary data
2. Row 2: Data column headers
3. Row 3 and beyond: Detailed transaction data

Transaction Statement Example

*periodNo:20210113|startTime:2021-01-12 00:00|endTime:2021-01-13 01:00|totalCount:14
paidTime|transactionType|totalAmount|orderCurrency|productName|paySceneCode|merchantOrderNo|orderNo|status|paymentMethodType|subject|payeeMid|terminalId|operatorId|storeId|merchantName|storeName|originMerchantOrderNo|reserved
2021-01-12T17:46:36+0400|PAYMENT|60.00|AED|Smart Purchase|QRPAY|210112214643201985620006|131610459203006982|SUCCESS|BALANCE|LLH & Medeor Hospital Administration Office|200000054800|533|ADMIN|268|upload key test merchant1|LLH & Medeor Hospital Administration Office||*

Summary Data Fields

Field Name	Description
periodNo	Period number
startTime	Start time
endTime	End time
totalCount	Total record count

Transaction Data Fields

Field Name	Description
paidTime	Payment success time (DD-MM-YYYY HH24:MI:SS)
transactionType	Transaction type
totalAmount	Order amount
orderCurrency	Order currency
productName	Product name
paySceneCode	Payment scenario code
merchantOrderNo	Merchant order number
orderNo	PayBy order number
status	Transaction status
paymentMethodType	Payment method type
subject	Transaction subject
payeeMid	Payee member ID
terminalId	Terminal ID
operatorId	Operator ID
storeId	Store ID
merchantName	Merchant name
storeName	Store name
originMerchantOrderNo	Original merchant order number
reserved	Reserved field

Settlement Statement File Format

Settlement statement files contain comprehensive settlement information with summary and detailed data sections.

File Structure

1. Row 1: Summary data
2. Row 2: Data column headers
3. Row 3 and beyond: Detailed settlement data

Settlement Statement Example

*settlePeriodNo:20210113|startTime:2021-01-12 00:00|endTime:2021-01-13 01:00|openingAmount:AED 1.00|totalCount:33|totalCredit:AED 472.70|totalDebit:AED 333.21|totalComm:AED 14.92|totalVAT:AED 0.75|settleToBank:AED 139.49 success|stayAmount:AED 1.00
settledTIme|transactionType|direction|settlementAmount|orderCurrency|productName|paySceneCode|merchantOrderNo|orderNo|paidTime|status|comm|commCurrency|VAT|VATCurrency|paymentMethodType|subject|payeeMid|terminalId|operatorId|storeId|merchantName|storeName|originMerchantOrderNo|reserved
2021-01-13T00:18:39+0400|ADJUST|OUT|100.00|AED|||adjustfd059cd19066414d979013fc3a6d2467|804c2f6f-5b9f-41ae-aeaf-380ce624b269|2021-01-13T00:18:39+0400||0.00|AED|0.00|AED|BALANCE|||||||||*

Settlement Summary Data Fields

Field Name	Description
settlePeriodNo	Settlement period number
startTime	Start time
endTime	End time
openingAmount	Opening balance amount
totalCount	Total record count
totalCredit	Total income
totalDebit	Total expenditure
totalComm	PayBy pre-tax commission total
totalVAT	PayBy VAT total
settleToBank	Settlement amount and status to bank
stayAmount	Retained amount

Settlement Data Fields

Field Name	Description
settledTIme	Settlement time (DD-MM-YYYY HH24:MI:SS)
transactionType	Transaction type
direction	Fund direction
settlementAmount	Order amount
orderCurrency	Order currency
productName	Product name
paySceneCode	Payment scenario code
merchantOrderNo	Merchant order number
orderNo	PayBy order number
paidTime	Payment success time (DD-MM-YYYY HH24:MI:SS)
status	Transaction status
comm	PayBy pre-tax commission
commCurrency	PayBy pre-tax commission currency
VAT	PayBy VAT
VATCurrency	PayBy VAT currency
paymentMethodType	Payment method type
subject	Transaction subject
payeeMid	Payee member ID
terminalId	Terminal ID
operatorId	Operator ID
storeId	Store ID
merchantName	Merchant name
storeName	Store name
originMerchantOrderNo	Original merchant order number
reserved	Reserved field

Fund Statement File Format

Fund statement files provide comprehensive account balance and transaction information with a four-row structure.

File Structure

1. Row 1: Summary data headers
2. Row 2: Summary data content
3. Row 3: Detailed data headers
4. Row 4 and beyond: Detailed transaction data

Fund Statement Example

*ACCOUNTING_DATE|NUMBER_INCOME|AMOUNT_INCOME|NUMBER_PAYOUT|AMOUNT_PAYOUT|BEGINNING_BALANCE|ENDING_BALANCE
2021-01-12T00:00:00+0400|21|275.90|22|1600.30|1330.9100|6.51
ACCOUNTING_TIME|TXN_NO|PRODUCT|BUSINESS_TYPE|DIRECTION|TXN_AMT|BEFORE_AMT|AFTER_AMT|ACCOUNT_TYPE|MERCHANT_ORDER_NO|ORDER_NO
2021-01-12T00:00:19+0400|fd20210112000442901|Settlement|Pay|Payout|639.43|1330.91|691.48|BASIC|gp134_statement2withdraw-20210112000000128|131610395233021228*

Fund Summary Data Fields

Field Name	Description
ACCOUNTING_DATE	Accounting date
NUMBER_INCOME	Number of income records
AMOUNT_INCOME	Income amount
NUMBER_PAYOUT	Number of payout records
AMOUNT_PAYOUT	Payout amount
BEGINNING_BALANCE	Beginning balance
ENDING_BALANCE	Ending balance

Fund Transaction Data Fields

Field Name	Description
ACCOUNTING_TIME	Accounting time
TXN_NO	Transaction serial number
PRODUCT	Product name
BUSINESS_TYPE	Business type
DIRECTION	Fund direction
TXN_AMT	Transaction amount
BEFORE_AMT	Amount before transaction
AFTER_AMT	Amount after transaction
ACCOUNT_TYPE	Account type
MERCHANT_ORDER_NO	Merchant order number
ORDER_NO	PayBy order number