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.
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
List 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 |
# 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"
Filter by date range
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"
Requery a single transaction
GET /api/v1/transactions/{transactionId}
| 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 |
customerRef, the most recent one is returned.
curl -sS "https://api.dancity.app/api/v1/transactions/TXN-2025-XXXXX" \
-H "Authorization: Bearer $DANCITY_API_KEY"
Sample response
{
"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 |
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:
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
