Statement Report API

Export merchant settlement reports, payout batch records, fee summaries, and SARIE bank transfer logs by date range for ERP accounting reconciliation and financial audits.

Endpoint

POST /reports/statements

Request Headers

Authorization: YOUR_SECRET_KEY
X-Amwal-Key: sandbox-amwal-xxx
Content-Type: application/json

Header	Type	Required	Description
`Authorization`	String	Yes	Your Amwal Secret Key (e.g. `d9ccf8bc-ed63-44ad-a54c-9d8fee63df6b`).
`X-Amwal-Key`	String	No	Merchant publishable API Key or sandbox identifier.
`Content-Type`	String	Yes	Must be set to `application/json`.

Request Body

{
  "from_date": "2026-05-01T00:00:00Z",
  "to_date": "2026-05-31T23:59:59Z",
  "store_id": "f24267bd-79f4-433f-a9f2-485c171301e4",
  "format": "json"
}

Request Parameters

Field	Type	Required	Description
`from_date`	String (ISO 8601)	Yes	Start timestamp of reporting period in UTC (e.g. `2026-05-01T00:00:00Z`).
`to_date`	String (ISO 8601)	Yes	End timestamp of reporting period in UTC (e.g. `2026-05-31T23:59:59Z`).
`store_id`	String (UUID)	Yes	Store identifier for which financial statements are generated.
`format`	String	No	Desired report format: `"json"` (default), `"csv"`, or `"pdf"`.

Response (`200 OK`)

{
  "report_id": "rep_20260531_001",
  "generated_at": "2026-06-01T02:00:00Z",
  "currency": "SAR",
  "summary": {
    "total_gross_sales": 145000.00,
    "total_fees": 2175.00,
    "total_vat": 326.25,
    "total_refunds": 1200.00,
    "net_payout_amount": 141298.75
  },
  "settlements": [
    {
      "settlement_id": "SET-981240",
      "payout_date": "2026-05-15",
      "bank_reference": "SARB-98124-AMWAL",
      "net_amount": 72150.00,
      "status": "completed"
    }
  ]
}

Response Parameters

Top-Level Report Metadata

Field	Type	Description
`report_id`	String	Unique statement report execution ID.
`generated_at`	String (ISO 8601)	Timestamp when the report was compiled in UTC.
`currency`	String	Currency ISO code (`SAR`).
`summary`	Object	Aggregate financial summary for the specified date range.
`settlements`	Array of Objects	List of SARIE bank payout transfer batches.

Financial Summary (`summary`)

Field	Type	Description
`total_gross_sales`	Number	Total authorized installment and card sales gross volume in SAR.
`total_fees`	Number	Total Amwal transaction processing fees in SAR.
`total_vat`	Number	15% VAT assessed on processing fees in SAR.
`total_refunds`	Number	Total amount of customer refunds settled during the period.
`net_payout_amount`	Number	Net settled balance transferred to merchant bank account (`gross - fees - vat - refunds`).

Settlement Batch Record (`settlements[]`)

Field	Type	Description
`settlement_id`	String	Unique settlement batch reference code.
`payout_date`	String (ISO 8601 Date)	Date when funds were transferred via the SARIE interbank network.
`bank_reference`	String	Central bank / SARIE reference tracking number.
`net_amount`	Number	Net amount credited to the merchant IBAN in SAR.
`status`	String	Settlement payout status: `"completed"`, `"pending"`, or `"failed"`.

Error Responses

Status Code	Error Code	Description
`400 Bad Request`	`invalid_date_range`	`from_date` occurs after `to_date` or exceeds the maximum supported 1-year query window.
`401 Unauthorized`	`authentication_failed`	Missing or invalid Secret Key in the `Authorization` header.

On this page