# Transactions

`GET /v2/billing/transactions`

**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/transactions" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

This endpoint allows you to query and retrieve detailed information about transactions across your accounts. With the ability to apply various filters, you can refine your search to find specific transactions easily. Additionally, you can export the results into a CSV file for further analysis or record-keeping.

---

### Request

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

---

#### Query parameters

| Key | Description | Type | Required |
| --- | --- | --- | --- |
| type | One or more of the following types: payment-received, payment-received-reversal, payment-debit, payment-debit-reversal, payment-credit, payment-credit-reversal, payment-refund, payment-refund-reversal, fee, fee-reversal, payout, payout-reversal, admin-debit, admin-debit-reversal, admin-credit, admin-credit-reversal, promotional-credit, promotional-credit-reversal, promotional-debit, promotional-debit-reversal, balance-adjustment-credit, balance-adjustment-debit, bad-debt-write-off, bad-debt-write-off-reversal, chargeback, chargeback-reversal | array of string | No |
| search | Case-insensitive partial match on transactions | string | No |
| start_date | Start date for the time period (format: YYYY-MM-DD HH:MM:SS) | string (date/time) | No |
| end_date | End date for the time period (format: YYYY-MM-DD HH:MM:SS) | string (date/time) | No |
| csv | Use true to export the results into a CSV file. The CSV is generated in the background and emailed to you. | boolean | No |
| order | ASC / DESC | string | No |
| order_by | Order by any field | string | No |
| offset | The number of records to skip | integer | No |
| limit | Limit the number of records returned | integer | No |

---

### Response

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

**Response body example:**

```json
{
    "billing_transactions": [
        {
            "id": 65473,
            "transaction_date": "2024-06-18T10:14:43.010441+02:00",
            "type": "payment-debit",
            "description": "reversal-pay-shap-36625",
            "amount": -200,
            "amount_excl_vat": -200,
            "vat": 0,
            "doc_number": "",
            "account_id": 259,
            "account_code": "BOB009",
            "created_by": 246,
            "time_created": "2024-06-18T10:14:43.00013+02:00",
            "time_modified": "2024-06-18T10:14:43.01135+02:00",
            "modified_by": 246,
            "modified_by_user": {
                "id": 246,
                "name": "Jane Smith",
                "email": "jane@example.co.za"
            },
            "invoice_id": null,
            "credit_note_id": null,
            "payment_intent_id": 54363,
            "payment_intent": {
                "id": 54363,
                "short_reference": "3RLH7",
                "payment_method": "pay-shap",
                "custom_payment_id": "99999",
                "email": "customer@example.co.za",
                "item_name": "Order 1452",
                "item_description": "Lego Star Wars"
            }
        }
    ],
    "count": 4
}
```

---

### Response fields

| Key | Description | Type |
| --- | --- | --- |
| billing_transactions | Array containing the transaction objects matching the query. | array of objects |
| id | Unique identifier for the transaction. | integer |
| transaction_date | Date and time of the transaction. | string (datetime) |
| type | Transaction type (e.g., payment-debit, payment-credit, fee, payout, etc.). | string |
| description | Description of the transaction. | string |
| amount | Amount of the transaction (negative for debits). | float |
| amount_excl_vat | Amount excluding VAT (signed the same way as `amount`). | float |
| vat | VAT amount. | float |
| doc_number | Associated document number (e.g., invoice or credit note number). | string |
| account_id | Account associated with the transaction. | integer |
| account_code | Code of the account associated with the transaction. | string |
| created_by | User ID who created the transaction. | integer |
| time_created | Timestamp when the transaction was created. | string (datetime) |
| time_modified | Timestamp when the transaction was last modified. | string (datetime) |
| modified_by | User ID who last modified the transaction. | integer |
| modified_by_user | User object with details of the last modifier. | object |
| invoice_id | Associated invoice ID. | integer |
| credit_note_id | Associated credit note ID. | integer |
| payment_intent_id | Payment intent ID associated with this transaction, if applicable. | integer |
| payment_intent | Payment intent object with additional details. | object |
| retained_until | If the funds are retained, the date until which they are retained. | string (datetime) |

**modified_by_user object fields:**

| Key | Description | Type |
| --- | --- | --- |
| id | User ID | integer |
| name | User's full name | string |
| email | User's email | string |

**payment_intent object fields:**

| Key | Description | Type |
| --- | --- | --- |
| id | Payment intent ID | integer |
| short_reference | Short reference code | string |
| payment_method | Payment method name | string |
| custom_payment_id | Custom payment reference | string |
| email | Payer's email | string |
| item_name | Name of the item | string |
| item_description | Description of the item | string |