Transactions

The transactions API allows you to retrieve and manage transaction history across all payment types. This guide covers transaction listing, filtering, pagination, and status tracking for deposits, withdrawals, and other transaction types.

Overview

The transactions API provides comprehensive access to all transaction data including:

Deposits - Incoming payments and deposits
Withdrawals - Outgoing payments and payouts
Settlements - Settlement transactions
Fees - Transaction fees and charges
Status tracking - Real-time transaction status updates

Retrieving Transactions

GET /api/transactions

Retrieve a paginated list of transactions with optional filtering.

Request

curl -X GET "https://api.dcepay.io/api/transactions?page=1&limit=10&type=DEPOSIT&status=CONFIRMED&currency=USD" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 10, max: 100)
`type`	string	No	Transaction type filter (DEPOSIT, WITHDRAWAL, SETTLEMENT)
`status`	string	No	Status filter (PENDING, CONFIRMED, FAILED)
`currency`	string	No	Currency filter (USD, EUR, BTC, etc.)
`startDate`	string	No	Start date filter (ISO 8601 format)
`endDate`	string	No	End date filter (ISO 8601 format)

Response

{
  "transactions": [
    {
      "id": "txn_xxxxxxxxxxxxxxxx",
      "type": "DEPOSIT",
      "status": "CONFIRMED",
      "amount": "100.00",
      "currency": "USD",
      "description": "Customer payment",
      "createdAt": "2024-12-19T10:30:00Z",
      "updatedAt": "2024-12-19T10:35:00Z",
      "metadata": {
        "orderId": "order_123",
        "customerEmail": "[email protected]"
      },
      "deposit": {
        "source": "CRYPTO_WALLET",
        "referenceId": "ref_123",
        "clearedAt": "2024-12-19T10:35:00Z",
        "fee": "1.00"
      },
      "category": {
        "name": "Customer Payment",
        "description": "Incoming customer payments"
      },
      "tags": [
        { "name": "customer-payment" },
        { "name": "crypto" }
      ]
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "pages": 15
  }
}

JavaScript Example

async function getTransactions(filters = {}) {
  const params = new URLSearchParams();
  
  if (filters.page) params.append('page', filters.page);
  if (filters.limit) params.append('limit', filters.limit);
  if (filters.type) params.append('type', filters.type);
  if (filters.status) params.append('status', filters.status);
  if (filters.currency) params.append('currency', filters.currency);
  if (filters.startDate) params.append('startDate', filters.startDate);
  if (filters.endDate) params.append('endDate', filters.endDate);

  const response = await fetch(`https://api.dcepay.io/api/transactions?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.DCE_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch transactions: ${response.statusText}`);
  }

  return response.json();
}

// Usage examples
const allTransactions = await getTransactions();
const deposits = await getTransactions({ type: 'DEPOSIT', status: 'CONFIRMED' });
const recentTransactions = await getTransactions({ 
  startDate: '2024-12-01T00:00:00Z',
  endDate: '2024-12-31T23:59:59Z'
});

Transaction Types

Deposit Transactions

Deposit transactions represent incoming payments from customers or external sources.

{
  "id": "txn_xxxxxxxxxxxxxxxx",
  "type": "DEPOSIT",
  "status": "CONFIRMED",
  "amount": "100.00",
  "currency": "USD",
  "deposit": {
    "source": "CRYPTO_WALLET",
    "referenceId": "ref_123",
    "clearedAt": "2024-12-19T10:35:00Z",
    "fee": "1.00"
  }
}

Withdrawal Transactions

Withdrawal transactions represent outgoing payments to customers or external addresses.

{
  "id": "txn_xxxxxxxxxxxxxxxx",
  "type": "WITHDRAWAL",
  "status": "PENDING",
  "amount": "50.00",
  "currency": "USD",
  "withdrawal": {
    "destination": "0x1234567890123456789012345678901234567890",
    "referenceId": "ref_456",
    "processedAt": null,
    "fee": "0.50",
    "reason": null
  }
}

Settlement Transactions

Settlement transactions represent merchant settlement payouts.

{
  "id": "txn_xxxxxxxxxxxxxxxx",
  "type": "SETTLEMENT",
  "status": "CONFIRMED",
  "amount": "1000.00",
  "currency": "USD",
  "settlement": {
    "destinationAddress": "0x1234567890123456789012345678901234567890",
    "destinationNetwork": "ETH",
    "processedAt": "2024-12-19T10:35:00Z",
    "fee": "25.00"
  }
}

Transaction Status

Status Values

Status	Description
`PENDING`	Transaction is being processed
`CONFIRMED`	Transaction has been confirmed and completed
`FAILED`	Transaction failed and cannot be completed
`CANCELLED`	Transaction was cancelled by user or system

Status Transitions

PENDING → CONFIRMED (successful completion)
PENDING → FAILED (processing failure)
PENDING → CANCELLED (user cancellation)

Filtering and Search

Type Filtering

Filter transactions by type:

# Get only deposits
GET /api/transactions?type=DEPOSIT

# Get only withdrawals
GET /api/transactions?type=WITHDRAWAL

# Get only settlements
GET /api/transactions?type=SETTLEMENT

Status Filtering

Filter transactions by status:

# Get pending transactions
GET /api/transactions?status=PENDING

# Get confirmed transactions
GET /api/transactions?status=CONFIRMED

# Get failed transactions
GET /api/transactions?status=FAILED

Date Range Filtering

Filter transactions by date range:

# Get transactions from specific date range
GET /api/transactions?startDate=2024-12-01T00:00:00Z&endDate=2024-12-31T23:59:59Z

Currency Filtering

Filter transactions by currency:

# Get USD transactions
GET /api/transactions?currency=USD

# Get BTC transactions
GET /api/transactions?currency=BTC

Pagination

The transactions API supports pagination with the following parameters:

Pagination Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number (1-based)
`limit`	number	10	Items per page (max: 100)

Pagination Response

{
  "transactions": [...],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "pages": 15
  }
}

Pagination Example

async function getAllTransactions() {
  let allTransactions = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await getTransactions({ page, limit: 100 });
    allTransactions = allTransactions.concat(response.transactions);
    
    hasMore = page < response.pagination.pages;
    page++;
  }

  return allTransactions;
}

Transaction Metadata

Transactions can include metadata for additional context:

{
  "id": "txn_xxxxxxxxxxxxxxxx",
  "metadata": {
    "orderId": "order_123",
    "customerEmail": "[email protected]",
    "paymentMethod": "crypto",
    "source": "webhook",
    "ipAddress": "192.168.1.1"
  }
}

Error Handling

Common Errors

Status Code	Error	Description
400	`Invalid request data`	Invalid query parameters
401	`Unauthorized`	Missing or invalid API key
403	`Insufficient permissions`	User lacks required permissions
500	`Internal server error`	Server-side error

Error Response Format

{
  "error": "Error message",
  "details": [
    {
      "field": "page",
      "message": "Page number must be positive"
    }
  ]
}

Best Practices

1. Efficient Pagination

Use appropriate limit values (10-50 for most use cases)
Implement caching for frequently accessed data
Use date filters to reduce result sets

2. Real-time Updates

Use webhooks for real-time transaction status updates
Poll the API periodically for status changes
Implement retry logic for failed requests

3. Data Management

Store transaction IDs for reconciliation
Implement proper error handling
Log all transaction operations for audit trails

4. Performance Optimization

// Efficient transaction fetching
async function getRecentTransactions(days = 7) {
  const startDate = new Date();
  startDate.setDate(startDate.getDate() - days);
  
  return getTransactions({
    startDate: startDate.toISOString(),
    limit: 50
  });
}

// Batch processing for large datasets
async function processTransactions(transactions) {
  const batchSize = 10;
  const results = [];
  
  for (let i = 0; i < transactions.length; i += batchSize) {
    const batch = transactions.slice(i, i + batchSize);
    const batchResults = await Promise.all(
      batch.map(tx => processTransaction(tx))
    );
    results.push(...batchResults);
  }
  
  return results;
}

Integration Examples

E-commerce Integration

class TransactionManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
  }

  async getOrderTransactions(orderId) {
    return getTransactions({
      metadata: { orderId }
    });
  }

  async getCustomerTransactions(customerEmail) {
    return getTransactions({
      metadata: { customerEmail }
    });
  }

  async getRevenueReport(startDate, endDate) {
    const transactions = await getTransactions({
      type: 'DEPOSIT',
      status: 'CONFIRMED',
      startDate,
      endDate
    });

    return transactions.reduce((total, tx) => {
      return total + parseFloat(tx.amount);
    }, 0);
  }
}

Accounting Integration

class AccountingIntegration {
  async exportTransactions(startDate, endDate) {
    const transactions = await getTransactions({
      startDate,
      endDate,
      limit: 1000
    });

    return transactions.map(tx => ({
      date: tx.createdAt,
      description: tx.description,
      amount: tx.amount,
      currency: tx.currency,
      type: tx.type,
      status: tx.status,
      reference: tx.id
    }));
  }
}

For more information about specific transaction types, see the Deposits and Withdrawals documentation.