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

# Transactions

> Query your transaction history and recheck the status of individual purchases

## Overview

The transactions endpoints let you:

* **List** all transactions with filtering, pagination, and date range support
* **Requery** a single transaction by ID to get its current status

Use these endpoints to build reconciliation workflows, display purchase history to users, or confirm whether a pending transaction has settled.

## Authentication

Both endpoints use your merchant API key only.

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

***

## List transactions

```
GET /api/v1/transactions
```

### Query parameters

| Param | Type | Description |
| - | - | - |
| `page` | integer | Page number (default: `1`) |
| `limit` | integer | Results per page (default: `10`, max: `100`) |
| `start_date` | date-time | ISO 8601 start of range (e.g., `2025-01-01T00:00:00.000Z`) |
| `end_date` | date-time | ISO 8601 end of range |
| `service` | string | Filter by service name (e.g., `"Airtime"`, `"Data"`) |
| `status` | string | `SUCCESS`, `FAILED`, `PENDING`, `PROCESSING`, `CANCELLED` |
| `tranxType` | string | `DEBIT` or `CREDIT` |
| `query` | string | Free-text search across transaction fields |
| `isBulk` | boolean | Filter bulk transactions only |

```bash cURL theme={null}
# Last 20 successful airtime transactions
curl -sS "https://api.dancity.app/api/v1/transactions?service=Airtime&status=SUCCESS&limit=20" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const params = new URLSearchParams({
  service: "Airtime",
  status: "SUCCESS",
  limit: "20",
  page: "1",
});

const res = await fetch(
  `https://api.dancity.app/api/v1/transactions?${params}`,
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data.transactions → array of transaction objects
// data.total → total count for pagination
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/transactions",
    params={"service": "Airtime", "status": "SUCCESS", "limit": 20, "page": 1},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
print(res.json()["data"])
```

### Filter by date range

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/transactions?start_date=2025-04-01T00:00:00.000Z&end_date=2025-04-30T23:59:59.000Z" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const params = new URLSearchParams({
  start_date: "2025-04-01T00:00:00.000Z",
  end_date: "2025-04-30T23:59:59.000Z",
  limit: "50",
});

const res = await fetch(
  `https://api.dancity.app/api/v1/transactions?${params}`,
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
```

***

## Requery a single transaction

```
GET /api/v1/transactions/{transactionId}
```

Use this endpoint to get the latest status of a specific transaction. Pass any of these as the path parameter:

| Identifier | Example | Description |
| - | - | - |
| Mongo `_id` | `6a1c3e3de285680cc3b7d2ba` | Internal transaction id |
| `tranxId` | `DNTY8374056F678V` | Dancity reference from the purchase response |
| `customerRef` | `DATA-REF-001` | Your reference sent on the purchase request |

If multiple transactions share the same `customerRef`, the most recent one is returned.

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/transactions/TXN-2025-XXXXX" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  `https://api.dancity.app/api/v1/transactions/${transactionId}`,
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
console.log(data.status); // "SUCCESS" | "FAILED" | "PENDING" | "PROCESSING" | "CANCELLED"
```

```python Python theme={null}
import requests, os

res = requests.get(
    f"https://api.dancity.app/api/v1/transactions/{transaction_id}",
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
status = res.json()["data"]["status"]
```

### Sample response

```json theme={null}
{
  "success": true,
  "message": "Transaction fetched",
  "data": {
    "_id": "6a1c3e3de285680cc3b7d2ba",
    "tranxId": "DNTY8374056F678V",
    "service": "DATA",
    "product": "MTN GIFTING",
    "tranxType": "DEBIT",
    "status": "FAILED",
    "currency": "NGN",
    "remarks": "MTN GIFTING 40MB for 1 Day",
    "amount": 50,
    "fee": 0,
    "amountPaid": 50,
    "balanceBefore": 5276,
    "balanceAfter": 5226,
    "number": "09037346247",
    "customerRef": "DATA-REF-001",
    "channel": "API",
    "paymentMedium": "MAIN WALLET",
    "tranxDate": "2026-05-31T13:57:17.405Z",
    "apiResponse": "Sorry, you are not allowed to migrate to Betamix Bundle Mini Plan. Thank you! — Oh dear! It seems xxxxxxxxxxx is not eligible for this bundle. Please select a new bundle and try again",
    "isReversal": false,
    "quantity": 0,
    "createdAt": "2026-05-31T13:57:17.407Z"
  }
}
```

***

## Transaction status values

| Status | Meaning |
| - | - |
| `SUCCESS` | Transaction completed and delivered |
| `FAILED` | Transaction could not be completed |
| `PENDING` | Awaiting processing |
| `PROCESSING` | In progress with the provider |
| `CANCELLED` | Cancelled before completion |

> [!NOTE]
>
> A `PROCESSING` status means the transaction is in flight with the provider. Poll the requery endpoint at a reasonable interval (e.g., every 10–30 seconds) rather than immediately retrying the purchase.

***

## Reconciliation pattern

For automated reconciliation, page through transactions using a fixed date range and `limit=100`:

```javascript theme={null}
async function fetchAllTransactions(startDate, endDate) {
  const transactions = [];
  let page = 1;

  while (true) {
    const params = new URLSearchParams({
      start_date: startDate,
      end_date: endDate,
      limit: "100",
      page: String(page),
    });
    const res = await fetch(
      `https://api.dancity.app/api/v1/transactions?${params}`,
      { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
    );
    const { data } = await res.json();

    transactions.push(...data.transactions);

    if (transactions.length >= data.total) break;
    page++;
  }

  return transactions;
}
```

## Next steps

* [Webhooks: receive real-time status updates](https://docs.dancity.app/guides/webhook.md)
* [Error reference](https://docs.dancity.app/guides/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.