# Get billing statement

`GET /v2/billing/statements`

**Base URLs:**

- Sandbox: `https://api.sandbox.bobpay.co.za`
- Production: `https://api.bobpay.co.za`

**Authentication:** Bearer token required. Obtain one via `POST /login` (see the Authentication page).

## Example request

```bash
curl -X GET "https://api.sandbox.bobpay.co.za/v2/billing/statements" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

This endpoint retrieves an account statement for a specified period, with an option to download as PDF.

---

### Request

**Method:** GET
**URL:** `https://api.sandbox.bobpay.co.za/v2/billing/statements`

---

#### Query parameters

| Key | Description | Type | Required |
| --- | --- | --- | --- |
| pdf | Boolean flag to return a PDF download link for the statement instead of the statement data. | boolean | No |
| start_date | The start date for the statement period (format: YYYY-MM-DD HH:MM:SS). | string (date/time) | No |
| end_date | The end date for the statement period (format: YYYY-MM-DD HH:MM:SS). | string (date/time) | No |
| account_id | The unique identifier of the account whose statement is being requested. | integer | Yes |

**Note:** Very large statements cannot be returned directly as a PDF. In that case, the PDF is generated in the background and emailed to the authenticated user, and the response is `{"queued": "true", "email": "<your email address>"}` instead of a download link.

---

### Response

**Status code:** 200 OK
**Content-Type:** application/json

---

#### Response body (statement data)

```json
{
    "statement": {
        "from_date": "2023-10-01T00:00:00Z",
        "to_date": "2023-10-31T00:00:00Z",
        "pending": 0,
        "closing_balance": 0,
        "issuer_details": {},
        "account": {},
        "account_billing_info": {},
        "balance_brought_forward": {},
        "transactions": []
    }
}
```

---

#### Response body (PDF download URL)

```json
{
    "download_url": {
        "url": "https://payments-backend-dev-infra-billing.s3.af-south-1.amazonaws.com/pdfs/statement_335.pdf?...",
        "filename": "pdfs/statement_335.pdf",
        "bucket": "payments-backend-dev-infra-billing",
        "file_size": 45600
    }
}
```

---

### Response fields

| Key | Description | Type |
| --- | --- | --- |
| statement | Object containing the statement data for the specified period. | object |
| from_date | The start date of the statement period. | string (datetime) |
| to_date | The end date of the statement period. | string (datetime) |
| pending | The amount of pending transactions. | float |
| closing_balance | The closing balance at the end of the period. | float |
| issuer_details | Object with the issuer's details (name, address, contact info, etc.). | object |
| account | Object with account details. | object |
| account_billing_info | Object with account billing details. | object |
| balance_brought_forward | Object describing the balance carried over into the period. | object |
| transactions | Array of statement transactions (may be null if no transactions). | array of objects |
| download_url | Object containing PDF download info if pdf=true is used. | object |

---

**Note:** When `pdf=true` is used, the response will contain a `download_url` object instead of statement details.