List Transactions

Retrieve a paginated list of all transactions for your account with optional filtering and sorting capabilities.

Endpoint

GET /transactions

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer token with your secret API key
`Content-Type`	string	Required	Must be `application/json`

Query Parameters

page

integer

default:"1"

Page number for pagination (starts from 1)

per_page

integer

default:"50"

Number of transactions per page (maximum 100)

status

string

Filter transactions by statusAvailable statuses: success, failed, pending, abandoned, cancelled

currency

string

Filter transactions by currency code (e.g., NGN, USD, GBP)

channel

string

Filter transactions by payment channelAvailable channels: card, bank, ussd, qr, mobile_money, bank_transfer

customer

string

Filter transactions by customer email or customer ID

amount

string

Filter transactions by exact amount (in smallest currency unit)

from

string

Start date for date range filter (ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ)

string

End date for date range filter (ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ)

sort

string

default:"created_at"

Field to sort byAvailable fields: created_at, amount, status, paid_at

order

string

default:"desc"

Sort order - asc (ascending) or desc (descending)

Example Request

curl -X GET "https://api.payvessel.com/transactions" \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json"

Response

status

string

Request status indicator - "success" or "error"

message

string

Human-readable message describing the result

data

array

Array of transaction objects

Show Transaction Object

data[].id

integer

Internal transaction ID

data[].reference

string

Unique transaction reference

data[].amount

integer

Transaction amount in smallest currency unit

data[].currency

string

Transaction currency code

data[].status

string

Transaction status - success, failed, pending, abandoned, cancelled

data[].gateway_response

string

Response message from the payment gateway

data[].paid_at

string

ISO 8601 timestamp when payment was completed (null if not paid)

data[].created_at

string

ISO 8601 timestamp when transaction was created

data[].channel

string

Payment method used - card, bank, ussd, qr, mobile_money, bank_transfer

data[].fees

integer

Transaction fees charged in smallest currency unit

data[].customer

object

Customer information object

data[].authorization

object

Payment authorization details (for successful card payments)

data[].metadata

object

Custom metadata attached to the transaction

Example Response

{
  "status": "success",
  "message": "Transactions retrieved successfully",
  "data": [
    {
      "id": 123456789,
      "reference": "TXN_2024_001",
      "amount": 50000,
      "currency": "NGN",
      "status": "success",
      "gateway_response": "Successful",
      "paid_at": "2024-01-15T14:35:22Z",
      "created_at": "2024-01-15T14:30:00Z",
      "channel": "card",
      "fees": 750,
      "customer": {
        "id": 12345,
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+2348012345678"
      },
      "authorization": {
        "authorization_code": "AUTH_xyz789abc",
        "bin": "408408",
        "last4": "4081",
        "card_type": "visa",
        "bank": "TEST BANK"
      },
      "metadata": {
        "custom_fields": [
          {
            "display_name": "Order ID",
            "variable_name": "order_id",
            "value": "ORD_001"
          }
        ]
      }
    },
    {
      "id": 123456790,
      "reference": "TXN_2024_002",
      "amount": 75000,
      "currency": "NGN",
      "status": "pending",
      "gateway_response": "Processing",
      "paid_at": null,
      "created_at": "2024-01-15T15:00:00Z",
      "channel": "bank",
      "fees": 0,
      "customer": {
        "id": 12346,
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "phone": "+2348012345679"
      },
      "authorization": null,
      "metadata": {}
    }
  ],
  "meta": {
    "total": 147,
    "page": 1,
    "per_page": 50,
    "pages": 3,
    "has_more": true
  }
}

Filtering Examples

By Status
By Date Range
By Payment Method
By Customer
Complex Filters

# Get all successful transactions
curl -X GET "https://api.payvessel.com/transactions?status=success" \
  -H "Authorization: Bearer sk_test_abc123..."

# Get failed transactions
curl -X GET "https://api.payvessel.com/transactions?status=failed" \
  -H "Authorization: Bearer sk_test_abc123..."

# Get transactions from January 2024
curl -X GET "https://api.payvessel.com/transactions?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer sk_test_abc123..."

# Get transactions from last 7 days
curl -X GET "https://api.payvessel.com/transactions?from=2024-01-08&to=2024-01-15" \
  -H "Authorization: Bearer sk_test_abc123..."

# Get card transactions only
curl -X GET "https://api.payvessel.com/transactions?channel=card" \
  -H "Authorization: Bearer sk_test_abc123..."

# Get bank transfer transactions
curl -X GET "https://api.payvessel.com/transactions?channel=bank" \
  -H "Authorization: Bearer sk_test_abc123..."

# Get transactions for specific customer
curl -X GET "https://api.payvessel.com/[email protected]" \
  -H "Authorization: Bearer sk_test_abc123..."

# Get transactions by customer ID
curl -X GET "https://api.payvessel.com/transactions?customer=12345" \
  -H "Authorization: Bearer sk_test_abc123..."

# Successful card payments in NGN from January 2024
curl -X GET "https://api.payvessel.com/transactions?status=success&channel=card&currency=NGN&from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer sk_test_abc123..."

Pagination

PayVessel uses page-based pagination for the transactions list endpoint:

Navigate Pages

Use page parameter to navigate through pages:

?page=1 - First page
?page=2 - Second page
etc.

Control Page Size

Use per_page parameter to control results per page:

Default: 50 transactions
Maximum: 100 transactions

Pagination Example

// Function to get all transactions
const getAllTransactions = async () => {
  let allTransactions = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await payvessel.transaction.list({
      page: page,
      per_page: 100 // Maximum per page
    });
    
    allTransactions = allTransactions.concat(response.data);
    hasMore = response.meta.has_more;
    page++;
  }
  
  return allTransactions;
};

Sorting Options

By Creation Date (Default)

# Newest first (default)
?sort=created_at&order=desc

# Oldest first
?sort=created_at&order=asc

By Amount

# Highest amount first
?sort=amount&order=desc

# Lowest amount first
?sort=amount&order=asc

By Payment Date

# Most recently paid first
?sort=paid_at&order=desc

# Earliest paid first
?sort=paid_at&order=asc

By Status

# Sort by status alphabetically
?sort=status&order=asc

Common Use Cases

Dashboard Analytics
Customer Statement
Failed Payment Analysis
Reconciliation

// Get successful transactions for revenue calculation
const getRevenueData = async (startDate, endDate) => {
  const transactions = await payvessel.transaction.list({
    status: 'success',
    from: startDate,
    to: endDate,
    per_page: 100
  });
  
  const revenue = transactions.data.reduce((total, txn) => {
    return total + (txn.amount - txn.fees);
  }, 0);
  
  return {
    total_revenue: revenue,
    transaction_count: transactions.meta.total,
    average_transaction: revenue / transactions.meta.total
  };
};

// Get transaction history for a specific customer
const getCustomerStatement = async (customerEmail, months = 3) => {
  const threeMonthsAgo = new Date();
  threeMonthsAgo.setMonth(threeMonthsAgo.getMonth() - months);
  
  const transactions = await payvessel.transaction.list({
    customer: customerEmail,
    from: threeMonthsAgo.toISOString().split('T')[0],
    sort: 'created_at',
    order: 'desc'
  });
  
  return transactions.data;
};

// Analyze failed payments to improve success rates
const analyzeFailedPayments = async () => {
  const failedTransactions = await payvessel.transaction.list({
    status: 'failed',
    per_page: 100
  });
  
  const failureReasons = {};
  failedTransactions.data.forEach(txn => {
    const reason = txn.gateway_response;
    failureReasons[reason] = (failureReasons[reason] || 0) + 1;
  });
  
  return failureReasons;
};

// Daily reconciliation of successful payments
const dailyReconciliation = async (date) => {
  const startOfDay = `${date}T00:00:00Z`;
  const endOfDay = `${date}T23:59:59Z`;
  
  const transactions = await payvessel.transaction.list({
    status: 'success',
    from: startOfDay,
    to: endOfDay,
    per_page: 100
  });
  
  return {
    date: date,
    transaction_count: transactions.meta.total,
    total_amount: transactions.data.reduce((sum, txn) => sum + txn.amount, 0),
    total_fees: transactions.data.reduce((sum, txn) => sum + txn.fees, 0)
  };
};

Best Practices

Efficient Pagination

Use appropriate per_page values. Start with 50, increase to 100 only when needed to reduce response times.

Date Range Limits

Limit date ranges for better performance. Query large date ranges in smaller chunks for faster responses.

Filter Early

Apply filters to reduce the dataset before pagination. This improves performance and reduces bandwidth.

Cache Results

Cache frequently accessed transaction lists (like daily summaries) to improve application performance.

Verify Transaction

Get detailed information about a specific transaction

Initialize Payment

Create a new payment transaction

Export Transactions

Download transaction data as CSV or Excel

Transaction Analytics

Get aggregated transaction analytics and insights

Getting Started

Transactions

Transfers

Identity Verification

Wallets

Virtual Accounts

Webhook

Bill Payments

Card Management

List Transactions

List Transactions

Endpoint

Headers

Query Parameters

Example Request

Response

Example Response

Filtering Examples

Navigate Pages

Control Page Size

Sorting Options

Common Use Cases

Best Practices

Efficient Pagination

Date Range Limits

Filter Early

Cache Results

Verify Transaction

Initialize Payment

Export Transactions

Transaction Analytics

Getting Started

Transactions

Transfers

Identity Verification

Wallets

Virtual Accounts

Webhook

Bill Payments

Card Management

​List Transactions

​Endpoint

​Headers

​Query Parameters

​Example Request

​Response

​Example Response

​Filtering Examples

​Pagination

Navigate Pages

Control Page Size

​Pagination Example

​Sorting Options

​Common Use Cases

​Best Practices

Efficient Pagination

Date Range Limits

Filter Early

Cache Results

​Related Endpoints

Verify Transaction

Initialize Payment

Export Transactions

Transaction Analytics

List Transactions

Endpoint

Headers

Query Parameters

Example Request

Response

Example Response

Filtering Examples

Pagination

Pagination Example

Sorting Options

Common Use Cases

Best Practices

Related Endpoints