> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagpay.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Export Transactions

> Download transaction records as CSV files for reporting and reconciliation.

All export endpoints return a `text/csv` file attachment. The response `Content-Disposition` header is set to `attachment; filename=data.csv`, which causes browsers to trigger a file download.

<Info>
  Export endpoints return all matching records without a hard page limit. For large date ranges, consider narrowing the range or filtering by `type` to keep file sizes manageable.
</Info>

***

## Download merchant transactions

Export all transactions for your merchant account as a CSV file.

```
GET https://api.tagpay.ng/v1/transaction/download/merchant
```

### Query parameters

<ParamField query="type" type="string" default="ALL">
  Filter by transaction direction: `CREDIT`, `DEBIT`, or `ALL`.
</ParamField>

<ParamField query="category" type="string">
  Filter by transaction category, e.g. `BANK_TRANSFER`.
</ParamField>

<ParamField query="startDate" type="string">
  ISO 8601 date string. Includes transactions created on or after the start of this date.
</ParamField>

<ParamField query="endDate" type="string">
  ISO 8601 date string. Includes transactions created on or before the end of this date.
</ParamField>

### Response

Returns a `200 OK` with `Content-Type: text/csv`. Records are sorted by `createdAt` descending.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/download/merchant?type=DEBIT&startDate=2024-01-01&endDate=2024-03-31" \
    --header "Authorization: Bearer <token>" \
    --output merchant-transactions.csv
  ```
</RequestExample>

<ResponseExample>
  ```text CSV (200) theme={null}
  id,reference,type,status,amount,fee,vat,total,currency,category,description,createdAt
  a1b2c3d4-...,TXN-001,DEBIT,success,500000,1000,75,501075,NGN,BANK_TRANSFER,Transfer to Access Bank,2024-03-15T10:30:00.000Z
  b2c3d4e5-...,TXN-002,DEBIT,success,250000,500,37,250537,NGN,BANK_TRANSFER,Transfer to GTBank,2024-03-14T14:20:00.000Z
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Unable to download transactions. Please try again."
  }
  ```
</ResponseExample>

***

## Download customer transactions

Export transaction history for a specific customer as a CSV file.

```
GET https://api.tagpay.ng/v1/transaction/download/customer
```

### Query parameters

<ParamField query="customerId" type="string" required>
  The ID of the customer whose transactions you want to export. Must belong to your merchant account.
</ParamField>

<ParamField query="startDate" type="string">
  ISO 8601 date string for the start of the date range.
</ParamField>

<ParamField query="endDate" type="string">
  ISO 8601 date string for the end of the date range.
</ParamField>

### Response

Returns a `200 OK` with `Content-Type: text/csv`. Records are sorted by `createdAt` descending.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/download/customer?customerId=cust_abc123&startDate=2024-01-01&endDate=2024-03-31" \
    --header "Authorization: Bearer <token>" \
    --output customer-transactions.csv
  ```
</RequestExample>

<ResponseExample>
  ```text CSV (200) theme={null}
  id,reference,type,status,amount,fee,vat,total,currency,category,description,createdAt
  c3d4e5f6-...,TXN-100,CREDIT,success,100000,0,0,100000,NGN,CUSTOMER_ACCOUNT_FUNDED,Wallet top-up,2024-02-20T08:00:00.000Z
  d4e5f6a7-...,TXN-101,DEBIT,success,50000,500,37,50537,NGN,CUSTOMER_BANK_TRANSFER,ATM withdrawal,2024-02-21T12:00:00.000Z
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Customer could not be found."
  }
  ```
</ResponseExample>

***

## Export pending transactions

Export the list of pending transactions awaiting approval as a CSV file. Only transactions at or above your user's configured `approvalLimit` are included.

```
GET https://api.tagpay.ng/v1/transaction/pending/export
```

### Query parameters

<ParamField query="type" type="string" default="ALL">
  Filter by direction: `CREDIT`, `DEBIT`, or `ALL`.
</ParamField>

<ParamField query="category" type="string">
  Filter by transaction category.
</ParamField>

<ParamField query="page" type="number">
  When provided, paginates the export using the `perPage` value. Omit to export all matching records.
</ParamField>

<ParamField query="perPage" type="number" default="20">
  Records per page when `page` is specified.
</ParamField>

### Response

Returns a `200 OK` with `Content-Type: text/csv`. Each row includes the transaction fields plus flattened `creator` and `approvedBy` objects.

<Warning>
  This endpoint returns a `400` error if no pending transactions match your filters. Check that transactions exist before calling this endpoint from automated scripts.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/pending/export?type=DEBIT" \
    --header "Authorization: Bearer <token>" \
    --output pending-transactions.csv
  ```
</RequestExample>

<ResponseExample>
  ```text CSV (200) theme={null}
  id,amount,type,status,category,createdAt,updatedAt
  c3d4e5f6-...,10000000,DEBIT,PENDING,BANK_TRANSFER,2024-04-02T08:15:00.000Z,2024-04-02T08:15:00.000Z
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Unable to export pending transactions list as csv"
  }
  ```
</ResponseExample>

***

## Export batch transactions

Export the list of batch transactions as a CSV file.

```
GET https://api.tagpay.ng/v1/transaction/batch/export
```

### Query parameters

<ParamField query="type" type="string" default="ALL">
  Filter by direction: `CREDIT`, `DEBIT`, or `ALL`.
</ParamField>

<ParamField query="category" type="string">
  Filter by transaction category.
</ParamField>

<ParamField query="search" type="string">
  Filter by batch reference string.
</ParamField>

<ParamField query="page" type="number">
  When provided, paginates the export. Omit to export all matching records.
</ParamField>

<ParamField query="perPage" type="number" default="20">
  Records per page when `page` is specified.
</ParamField>

### Response

Returns a `200 OK` with `Content-Type: text/csv`. Each row represents a batch record. Internal columns `mode` and `merchantId` are excluded.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/batch/export?type=DEBIT&startDate=2024-01-01" \
    --header "Authorization: Bearer <token>" \
    --output batch-transactions.csv
  ```
</RequestExample>

<ResponseExample>
  ```text CSV (200) theme={null}
  id,reference,type,status,totalAmount,totalCount,category,createdAt,updatedAt
  d4e5f6a7-...,BATCH-001,DEBIT,success,5000000,10,BATCH_BANK_TRANSFER,2024-04-01T14:00:00.000Z,2024-04-01T14:05:30.000Z
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Unable to export batch transactions list as csv"
  }
  ```
</ResponseExample>

***

## CSV format notes

* All CSV files use comma delimiters with a header row.
* Monetary amounts are returned in the smallest currency unit (kobo for NGN). Divide by `100` to get the naira value.
* Timestamps follow ISO 8601 format in UTC.
* Date range filters are inclusive: `startDate` is treated as the start of that calendar day and `endDate` as the end of that calendar day.
* There is no enforced date range limit on export endpoints, but requests spanning more than 90 days may be slow on large accounts. Prefer narrower ranges for automated reconciliation jobs.