> ## 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.

# List Transactions

> Retrieve paginated transaction records for your merchant account or for individual customers.

All list endpoints require a valid `Authorization: Bearer <token>` header and return results scoped to your merchant account and the current API mode (sandbox or production).

## List customer transactions

Retrieve the transaction history for a specific customer wallet.

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

### Query parameters

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

<ParamField query="page" type="number" default="1">
  Page number for pagination. Must be a positive integer.
</ParamField>

<ParamField query="perPage" type="number" default="20">
  Number of records per page. Must be a positive integer.
</ParamField>

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

<ParamField query="status" type="string">
  Filter by transaction status. Common values: `success`, `pending`, `failed`.
</ParamField>

<ParamField query="category" type="string">
  Filter by transaction category, such as `BANK_TRANSFER` or `WALLET_TO_WALLET_TRANSFER`.
</ParamField>

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

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

### Response

<ResponseField name="status" type="boolean">
  `true` when the request succeeded.
</ResponseField>

<ResponseField name="transactions" type="object[]">
  Array of transaction objects.

  <Expandable title="Transaction object">
    <ResponseField name="id" type="string">
      Unique transaction identifier (UUID).
    </ResponseField>

    <ResponseField name="reference" type="string">
      Merchant-assigned or system-generated transaction reference.
    </ResponseField>

    <ResponseField name="type" type="string">
      `CREDIT` or `DEBIT`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Transaction status: `success`, `pending`, or `failed`.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in the smallest currency unit (kobo).
    </ResponseField>

    <ResponseField name="fee" type="number">
      Processing fee applied to the transaction.
    </ResponseField>

    <ResponseField name="vat" type="number">
      VAT applied to the transaction.
    </ResponseField>

    <ResponseField name="total" type="number">
      Total amount including fees and VAT.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code, e.g. `NGN`.
    </ResponseField>

    <ResponseField name="category" type="string">
      Transaction category, e.g. `BANK_TRANSFER`, `WALLET_TO_WALLET_TRANSFER`.
    </ResponseField>

    <ResponseField name="description" type="string">
      Human-readable transaction description.
    </ResponseField>

    <ResponseField name="source" type="string">
      Source account or wallet identifier.
    </ResponseField>

    <ResponseField name="destination" type="string">
      Destination account or wallet identifier.
    </ResponseField>

    <ResponseField name="balance_before" type="number">
      Wallet balance immediately before the transaction.
    </ResponseField>

    <ResponseField name="balance_after" type="number">
      Wallet balance immediately after the transaction.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary key-value metadata attached to the transaction.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the transaction was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the transaction was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination metadata.

  <Expandable title="Pagination">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="totalRecords" type="number">
      Total number of matching records.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages at the current `perPage` size.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/customer?customerId=cust_abc123&page=1&perPage=20&type=DEBIT" \
    --header "Authorization: Bearer <token>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "transactions": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "reference": "TXN-20240401-001",
        "type": "DEBIT",
        "status": "success",
        "amount": 500000,
        "fee": 1000,
        "vat": 75,
        "total": 501075,
        "currency": "NGN",
        "category": "BANK_TRANSFER",
        "description": "Transfer to Access Bank",
        "source": "wallet_001",
        "destination": "0123456789",
        "balance_before": 1000000,
        "balance_after": 498925,
        "metadata": {},
        "createdAt": "2024-04-01T10:30:00.000Z",
        "updatedAt": "2024-04-01T10:30:05.000Z"
      }
    ],
    "metadata": {
      "page": 1,
      "totalRecords": 84,
      "totalPages": 5
    }
  }
  ```

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

***

## List merchant transactions

Retrieve all transactions across your merchant account.

```
GET https://api.tagpay.ng/v1/merchant/transactions
```

### Query parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="perPage" type="number" default="20">
  Number of records per page.
</ParamField>

<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.
</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

The response shape mirrors the customer transactions endpoint. The `transactions` array contains the same transaction object structure. The `metadata` object contains `page`, `totalRecords`, and `totalPages`.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/merchant/transactions?page=1&perPage=20&type=ALL&startDate=2024-01-01&endDate=2024-04-30" \
    --header "Authorization: Bearer <token>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "transactions": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "reference": "TXN-20240401-002",
        "type": "CREDIT",
        "status": "success",
        "amount": 2000000,
        "fee": 0,
        "vat": 0,
        "total": 2000000,
        "currency": "NGN",
        "category": "ACCOUNT_FUNDED",
        "description": "Wallet funding",
        "createdAt": "2024-04-01T09:00:00.000Z",
        "updatedAt": "2024-04-01T09:00:02.000Z"
      }
    ],
    "metadata": {
      "page": 1,
      "totalRecords": 312,
      "totalPages": 16
    }
  }
  ```
</ResponseExample>

***

## List pending transactions

Retrieve transactions that are awaiting approval. Only transactions at or above your user's configured `approvalLimit` are returned.

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

### Query parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="perPage" type="number" default="20">
  Number of records per page.
</ParamField>

<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="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

<ResponseField name="status" type="boolean">
  `true` when the request succeeded.
</ResponseField>

<ResponseField name="data" type="object[]">
  Array of pending transaction objects.

  <Expandable title="Pending transaction object">
    <ResponseField name="id" type="string">
      Unique pending transaction ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      `CREDIT` or `DEBIT`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Always `PENDING` for results from this endpoint.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in kobo.
    </ResponseField>

    <ResponseField name="category" type="string">
      Transaction category.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary metadata for the transaction.
    </ResponseField>

    <ResponseField name="creator" type="object">
      The user who initiated the transaction.

      <Expandable title="Creator">
        <ResponseField name="id" type="string">User ID.</ResponseField>
        <ResponseField name="firstName" type="string">First name.</ResponseField>
        <ResponseField name="lastName" type="string">Last name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="approvedBy" type="object">
      The user who approved the transaction, if already approved. `null` when still pending.

      <Expandable title="Approver">
        <ResponseField name="id" type="string">User ID.</ResponseField>
        <ResponseField name="firstName" type="string">First name.</ResponseField>
        <ResponseField name="lastName" type="string">Last name.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 last-updated timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination metadata with `page`, `totalRecords`, and `totalPages`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/pending?page=1&perPage=20" \
    --header "Authorization: Bearer <token>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "data": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "type": "DEBIT",
        "status": "PENDING",
        "amount": 10000000,
        "category": "BANK_TRANSFER",
        "metadata": {
          "accountNumber": "0123456789",
          "bankCode": "044"
        },
        "creator": {
          "id": "usr_001",
          "firstName": "Amara",
          "lastName": "Okonkwo"
        },
        "approvedBy": null,
        "createdAt": "2024-04-02T08:15:00.000Z",
        "updatedAt": "2024-04-02T08:15:00.000Z"
      }
    ],
    "metadata": {
      "page": 1,
      "totalRecords": 3,
      "totalPages": 1
    }
  }
  ```
</ResponseExample>

***

## List batch transactions

Retrieve batch transaction records. A batch groups multiple individual transfers initiated together.

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

### Query parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="perPage" type="number" default="20">
  Number of records per page.
</ParamField>

<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">
  Search by batch reference string.
</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

<ResponseField name="status" type="boolean">
  `true` when the request succeeded.
</ResponseField>

<ResponseField name="data" type="object[]">
  Array of batch transaction objects.
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination metadata with `page`, `totalRecords`, and `totalPages`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/batch?page=1&perPage=20&type=DEBIT" \
    --header "Authorization: Bearer <token>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "data": [
      {
        "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "reference": "BATCH-20240401-001",
        "type": "DEBIT",
        "status": "success",
        "totalAmount": 5000000,
        "totalCount": 10,
        "category": "BATCH_BANK_TRANSFER",
        "createdAt": "2024-04-01T14:00:00.000Z",
        "updatedAt": "2024-04-01T14:05:30.000Z"
      }
    ],
    "metadata": {
      "page": 1,
      "totalRecords": 7,
      "totalPages": 1
    }
  }
  ```
</ResponseExample>