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 Botim Money, 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 Botim Money’s side will not appear in the statements.
2. Botim Money 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
  • The language for the response message. Defaults to English.
  • 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/json
• sign String Required
  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.
  • Example value: RSA_SIGNATURE_BASE64_STRING
• Partner-Id String Required
  • Unique partner identifier.
  • 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 (V1)

*mid:200000088724|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
mid	Merchant ID
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	Botim Money 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

Transaction Statement Example (V2)

*mid:200000088724|periodNo:20000008872420260702|startTime:2026-07-01 00:00|endTime:2026-07-02 00:00|totalCount:1
merchantOrderNo|orderNo|paidTime|payeeMid|merchantName|terminalId|operatorId|storeId|storeName|scheme|orderCurrency|totalAmount|transactionType|productName|paySceneCode|paymentMethodType|subject|installmentPlan|planAcceptanceID|originMerchantOrderNo|reserved|status|authCode|cardNumber|cardIssuingCountry|cardLevel|cardType|customerName|mobileNumber|emailAddress|source|agreementType|authProtocolNo|dccAmount|dccCurrency|exchangeRate|dccMarkup|dccQuoteId
90a95a3f7c3d414e8d2e37452ffbd567|131782884973278414|2026-07-01T09:49:33+0400|200000088724|StarBuck Five Star|||||MASTERCARD|AED|1.00|REFUND|Basic Payment Gateway|PAYPAGE|BANK||||M20260626174845E0F86C3A||SUCCESS||512345******0008|AE|Premium|DC|||||||||||*

Summary Data Fields

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

Transaction Data Fields

Field Name	Description
merchantOrderNo	Merchant order number
orderNo	Botim Money order number
paidTime	Payment success time (DD-MM-YYYY HH24:MI:SS)
payeeMid	Payee member ID
merchantName	Merchant name
terminalId	Terminal ID
operatorId	Operator ID
storeId	Store ID
storeName	Store name
scheme	Card scheme
orderCurrency	Order currency
totalAmount	Order amount
transactionType	Transaction type
productName	Product name
paySceneCode	Payment scenario code
paymentMethodType	Payment method type
subject	Transaction subject
installmentPlan	Installment plan
planAcceptanceID	Installment acceptance ID
originMerchantOrderNo	Original merchant order number
reserved	Reserved field
status	Transaction status
authCode	Authorization code
cardNumber	Card number
cardIssuingCountry	Card issuing country
cardLevel	Card level
cardType	Card type
customerName	Customer name
mobileNumber	Mobile number
emailAddress	Email address
source	Source
agreementType	Agreement type
authProtocolNo	Signed agreement number
dccAmount	DCC amount
dccCurrency	DCC currency
exchangeRate	Exchange rate
dccMarkup	DCC markup
dccQuoteId	DCC quote ID

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 (V1)

*mid:200000088724|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
mid	Merchant ID
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	Botim Money pre-tax commission total
totalVAT	Botim Money 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	Botim Money order number
paidTime	Payment success time (DD-MM-YYYY HH24:MI:SS)
status	Transaction status
comm	Botim Money pre-tax commission
commCurrency	Botim Money pre-tax commission currency
VAT	Botim Money VAT
VATCurrency	Botim Money 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

Settlement Statement Example (V2)

*mid:200000088724|settlePeriodNo:20000008872420260702|startTime:2026-07-01 00:00|endTime:2026-07-02 00:00|openingAmount:AED 2737.72|totalCount:1|totalCredit:AED 0.00|totalDebit:AED 1.00|totalComm:AED 0.00|totalVAT:AED 0.00|settleToBank:AED 2736.72 failure|stayAmount:AED 2736.72
merchantOrderNo|orderNo|settledTime|paidTime|payeeMid|merchantName|terminalId|operatorId|storeId|storeName|scheme|orderCurrency|totalAmount|transactionType|direction|productName|paySceneCode|paymentMethodType|subject|installmentPlan|planAcceptanceID|originMerchantOrderNo|reserved|status|settlementAmount|commCurrency|comm|VATCurrency|VAT|authCode|cardNumber|cardIssuingCountry|cardLevel|cardType|source|agreementType|authProtocolNo|dccAmount|dccCurrency|exchangeRate|dccMarkup|dccQuoteId
90a95a3f7c3d414e8d2e37452ffbd567|131782884973278414|2026-07-01T09:49:33+0400|2026-07-01T09:49:33+0400|200000088724|StarBuck Five Star|||||MASTERCARD|AED|1.00|REFUND|OUT|Basic Payment Gateway|PAYPAGE|BANK||||M20260626174845E0F86C3A||SUCCESS|1.00|AED|0.00|AED|0.00||512345******0008|AE|Premium|DC||||||||*

Settlement Summary Data Fields

Field Name	Description
mid	Merchant ID
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	Botim Money pre-tax commission total
totalVAT	Botim Money VAT total
settleToBank	Settlement amount and status to bank
stayAmount	Retained amount

Settlement Data Fields

Field Name	Description
merchantOrderNo	Merchant order number
orderNo	Botim Money order number
settledTime	Settlement time (DD-MM-YYYY HH24:MI:SS)
paidTime	Payment success time (DD-MM-YYYY HH24:MI:SS)
payeeMid	Payee member ID
merchantName	Merchant name
terminalId	Terminal ID
operatorId	Operator ID
storeId	Store ID
storeName	Store name
scheme	Card scheme
orderCurrency	Order currency
totalAmount	Order amount
transactionType	Transaction type
direction	Fund direction
productName	Product name
paySceneCode	Payment scenario code
paymentMethodType	Payment method type
subject	Transaction subject
installmentPlan	Installment plan
planAcceptanceID	Installment acceptance ID
originMerchantOrderNo	Original merchant order number
reserved	Reserved field
status	Transaction status
settlementAmount	Settlement amount
commCurrency	Botim Money pre-tax commission currency
comm	Botim Money pre-tax commission
VATCurrency	Botim Money VAT currency
VAT	Botim Money VAT
authCode	Authorization code
cardNumber	Card number
cardIssuingCountry	Card issuing country
cardLevel	Card level
cardType	Card type
source	Source
agreementType	Agreement type
authProtocolNo	Signed agreement number
dccAmount	DCC amount
dccCurrency	DCC currency
exchangeRate	Exchange rate
dccMarkup	DCC markup
dccQuoteId	DCC quote ID

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	Botim Money order number

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success
400	INVALID_PARAMETER	Invalid parameter	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too far in the past	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too far in the future	Adjust request time
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency
403	UNAUTHORIZED	API not authorized	Contact Botim Money
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact Botim Money
500	SYSTEM_ERROR	System error	Contact Botim Money, or try again later
504	SERVICE_TIMEOUT	Service timeout	Try again later
601	RISK_FAIL	Risk control verification failed	Adjust the business request
62008	EXPIREDTIME_LESS_THAN_REQUESTTIME	Expiry time is earlier than the request time	Adjust the expiry time
62013	STATEMENT_NOT_EXIST	Statement does not exist	The merchant has no statement available for download