Analytics & Payments

Access payment data and store analytics

The Management API provides access to payment information and analytics data for your store.

Payments

Retrieve detailed payment information for transactions in your store.

List Payments

Retrieve all payments with optional filtering.

const response = await client.payments.getPayments({
  params: {
    limit: 50,
    after: 'payment-id', // Optional: for pagination
    asc: false // Optional: sort order (false = newest first)
  }
});

console.log(response.data); // Array of PaymentDto

Parameters

• limit (optional): Maximum number of payments to return
• after (optional): Return payments after this ID (cursor-based pagination)
• before (optional): Return payments before this ID
• asc (optional): Sort order - true for ascending, false for descending

Response

Returns an array of payment objects containing:

• Payment ID and status
• Amount and currency
• Payment method details (card, PayPal, etc.)
• Associated order ID
• Customer information
• Timestamps
• Fees and net amount

Get Payment by ID

Retrieve detailed information about a specific payment.

const response = await client.payments.getPaymentById({
  path: {
    paymentId: '1234567890'
  }
});

console.log(response.data); // PaymentDto

Parameters

• paymentId (required): The ID of the payment to retrieve

Response

Returns a complete payment object with full details including:

• Payment method information (card brand, last 4 digits, etc.)
• Risk assessment data
• Chargeback coverage information
• Fee breakdown
• Related order and customer data

Payment Methods

Manage available payment methods for your store.

Get Store Payment Method Types

Retrieve all payment method types available for your store.

const response = await client.paymentMethodTypes.getStorePaymentMethodTypes();

console.log(response.data); // Array of payment method types

Returns information about supported payment methods such as:

• Credit/debit cards
• PayPal
• Cash App
• Alipay
• And more regional payment methods

Toggle Payment Method Type

Enable or disable a specific payment method for your store.

await client.paymentMethodTypes.toggleStorePaymentMethodType({
  path: {
    paymentMethodTypeId: 'card'
  },
  data: {
    enabled: true
  }
});

Payment Settings

Manage payment configuration for your store.

Get Payment Settings

const response = await client.paymentSettings.getStorePaymentSettings();

console.log(response.data); // Payment settings

Update Payment Settings

await client.paymentSettings.updateStorePaymentSettings({
  data: {
    // Payment configuration options
    minimum_charge_amount: 100, // Minimum $1.00
    // ... other settings
  }
});

Subscriptions

Manage and view subscription data.

List Subscriptions

Retrieve all active subscriptions for your store.

const response = await client.subscriptions.getSubscriptions({
  params: {
    limit: 50,
    after: 'subscription-id',
    asc: false
  }
});

console.log(response.data); // Array of SubscriptionDto

Get Subscription by ID

Retrieve detailed information about a specific subscription.

const response = await client.subscriptions.getSubscriptionById({
  path: {
    subscriptionId: '1234567890'
  }
});

console.log(response.data); // SubscriptionDto

Cancel Subscription

Cancel an active subscription.

const response = await client.subscriptions.cancelSubscription({
  path: {
    subscriptionId: '1234567890'
  },
  data: {
    reason: 'Customer requested cancellation'
  }
});

console.log(response.data); // Cancelled subscription details

Example: Payment Analytics

import { createManagementClient, isPayNowError } from '@paynow-gg/typescript-sdk';

const client = createManagementClient(
  process.env.STORE_ID!,
  process.env.API_KEY!
);

interface PaymentStats {
  totalRevenue: number;
  totalPayments: number;
  averageOrderValue: number;
  paymentMethods: Record<string, number>;
}

async function getPaymentAnalytics(): Promise<PaymentStats> {
  try {
    const payments = await client.payments.getPayments({
      params: { limit: 1000 } // Adjust based on your needs
    });

    let totalRevenue = 0;
    const paymentMethods: Record<string, number> = {};

    for (const payment of payments.data) {
      // Sum up successful payments
      if (payment.status === 'succeeded') {
        totalRevenue += payment.amount;

        // Track payment methods
        const method = payment.payment_method?.type || 'unknown';
        paymentMethods[method] = (paymentMethods[method] || 0) + 1;
      }
    }

    const stats: PaymentStats = {
      totalRevenue,
      totalPayments: payments.data.length,
      averageOrderValue: totalRevenue / payments.data.length,
      paymentMethods
    };

    console.log('Payment Analytics:');
    console.log(`  Total Revenue: $${(stats.totalRevenue / 100).toFixed(2)}`);
    console.log(`  Total Payments: ${stats.totalPayments}`);
    console.log(`  Average Order Value: $${(stats.averageOrderValue / 100).toFixed(2)}`);
    console.log('  Payment Methods:', stats.paymentMethods);

    return stats;

  } catch (error) {
    if (isPayNowError(error)) {
      console.error('API Error:', error.response?.data);
    }
    throw error;
  }
}

getPaymentAnalytics();

Example: Subscription Management

async function manageSubscriptions() {
  try {
    // Get all active subscriptions
    const subscriptions = await client.subscriptions.getSubscriptions({
      params: { limit: 100 }
    });

    console.log(`Total subscriptions: ${subscriptions.data.length}`);

    // Find subscriptions expiring soon
    const now = new Date();
    const thirtyDaysFromNow = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000);

    for (const sub of subscriptions.data) {
      if (!sub.current_period_end) continue;

      const endDate = new Date(sub.current_period_end);
      
      if (endDate < thirtyDaysFromNow) {
        console.log(`Subscription ${sub.id} expires soon:`);
        console.log(`  Customer: ${sub.customer?.email}`);
        console.log(`  Expires: ${endDate.toLocaleDateString()}`);
        console.log(`  Product: ${sub.product?.name}`);
      }
    }

  } catch (error) {
    if (isPayNowError(error)) {
      console.error('Error fetching subscriptions:', error.response?.data);
    }
    throw error;
  }
}

manageSubscriptions();

Example: Export Payment Data

import { writeFileSync } from 'fs';

async function exportPaymentData(outputFile: string) {
  try {
    const allPayments = [];
    let hasMore = true;
    let lastId: string | undefined;

    // Paginate through all payments
    while (hasMore) {
      const response = await client.payments.getPayments({
        params: {
          limit: 100,
          after: lastId,
          asc: false
        }
      });

      allPayments.push(...response.data);

      if (response.data.length < 100) {
        hasMore = false;
      } else {
        lastId = response.data[response.data.length - 1].id;
      }
    }

    // Convert to CSV format
    const csvHeader = 'Payment ID,Date,Amount,Currency,Status,Customer Email,Payment Method\n';
    const csvRows = allPayments.map(payment => {
      return [
        payment.id,
        payment.created_at,
        (payment.amount / 100).toFixed(2),
        payment.currency,
        payment.status,
        payment.customer?.email || 'N/A',
        payment.payment_method?.type || 'N/A'
      ].join(',');
    }).join('\n');

    const csv = csvHeader + csvRows;
    writeFileSync(outputFile, csv);

    console.log(`Exported ${allPayments.length} payments to ${outputFile}`);

  } catch (error) {
    if (isPayNowError(error)) {
      console.error('Export failed:', error.response?.data);
    }
    throw error;
  }
}

exportPaymentData('payments.csv');

Payment Status

Payments can have the following statuses:

• succeeded - Payment completed successfully
• pending - Payment is being processed
• failed - Payment failed
• refunded - Payment has been refunded
• disputed - Payment is under dispute/chargeback

Related Resources

• Orders - Manage orders and refunds
• Customers - View customer purchase history
• Webhooks - Receive real-time payment notifications