List Payments

Returns a paginated list of payments. Payments are returned sorted by creation date (most recent first) by default.

Endpoint

GET /api/v1/payments

Authentication

This endpoint requires HMAC Integration Authentication.

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1, minimum: 1)
`limit`	number	No	Number of payments per page (default: 10, minimum: 1, maximum: 100)
`status`	string	No	Filter by payment status (see status values below)
`paymentMethod`	string	No	Filter by payment method: `"promptpay"` or `"bank_transfer"`
`dateFrom`	string	No	Filter payments created after this date (ISO 8601 format)
`dateTo`	string	No	Filter payments created before this date (ISO 8601 format)
`sortBy`	string	No	Sort field: `"amount"`, `"status"`, `"createdAt"`, `"confirmedAt"`, `"capturedAt"`, `"referenceId"`
`sortOrder`	string	No	Sort order: `"asc"` or `"desc"` (default: `"desc"`)

Status Filter Values

requires_payment_method
requires_confirmation
requires_action
processing
requires_capture
succeeded
canceled
expired
payment_failed

Example Request

import crypto from 'crypto';

const API_KEY = process.env.PAYMENT_API_KEY!;
const API_SECRET = process.env.PAYMENT_API_SECRET!;

async function listPayments(page = 1, limit = 10, filters = {}) {
  const queryParams = new URLSearchParams({
    page: page.toString(),
    limit: limit.toString(),
    ...(filters.status && { status: filters.status }),
    ...(filters.paymentMethod && { paymentMethod: filters.paymentMethod }),
    ...(filters.sortBy && { sortBy: filters.sortBy }),
    ...(filters.sortOrder && { sortOrder: filters.sortOrder }),
  });

  const method = 'GET';
  const path = `/api/v1/payments?${queryParams.toString()}`;
  const body = '';
  const timestamp = Date.now().toString();

  const message = `${timestamp}.${body}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(message)
    .digest('hex');

  const response = await fetch(`https://api.example.com${path}`, {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': `sha256=${signature}`,
    },
  });

  const result = await response.json();

  if (result.success) {
    console.log(`Total payments: ${result.data.total}`);
    console.log(`Page ${result.data.page} of ${result.data.totalPages}`);
    console.log(`Payments:`, result.data.data);
    return result.data;
  } else {
    console.error('Error:', result.error);
    throw new Error(result.error.message);
  }
}

// List all payments
const payments = await listPayments();

// List succeeded payments
const succeededPayments = await listPayments(1, 20, {
  status: 'succeeded',
});

// List PromptPay payments, sorted by amount descending
const promptpayPayments = await listPayments(1, 10, {
  paymentMethod: 'promptpay',
  sortBy: 'amount',
  sortOrder: 'desc',
});

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "amount": "1000.00",
        "currency": "THB",
        "status": "succeeded",
        "paymentMethod": "promptpay",
        "referenceId": "order-12345",
        "description": "Payment for order #12345",
        "metadata": {
          "order_id": "12345"
        },
        "clientSecret": null,
        "nextAction": null,
        "confirmedAt": "2024-01-01T00:05:00.000Z",
        "capturedAt": "2024-01-01T00:05:00.000Z",
        "canceledAt": null,
        "expiresAt": "2024-01-01T01:00:00.000Z",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:05:00.000Z"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "amount": "2000.00",
        "currency": "THB",
        "status": "processing",
        "paymentMethod": "bank_transfer",
        "referenceId": "order-12346",
        "description": "Payment for order #12346",
        "metadata": null,
        "clientSecret": null,
        "nextAction": {
          "type": "display_bank_transfer_instructions",
          "bankTransferInstructions": {
            "bankName": "Kasikorn Bank",
            "accountNumber": "1234567890",
            "accountName": "Example Company Ltd.",
            "amount": "2000.00",
            "reference": "ORDER-12346"
          }
        },
        "confirmedAt": null,
        "capturedAt": null,
        "canceledAt": null,
        "expiresAt": "2024-01-01T02:00:00.000Z",
        "createdAt": "2024-01-01T01:00:00.000Z",
        "updatedAt": "2024-01-01T01:00:00.000Z"
      }
    ],
    "total": 2,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

Pagination

The response includes pagination metadata:

Field	Type	Description
`data`	array	Array of payment objects
`total`	number	Total number of payments
`page`	number	Current page number
`limit`	number	Number of payments per page
`totalPages`	number	Total number of pages

Pagination Examples

# Get first page (10 payments)
GET /api/v1/payments?page=1&limit=10

# Get second page (next 10 payments)
GET /api/v1/payments?page=2&limit=10

# Get larger page size (50 payments)
GET /api/v1/payments?page=1&limit=50

Filtering

By Status

Filter payments by their current status:

# Get only succeeded payments
GET /api/v1/payments?status=succeeded

# Get only processing payments
GET /api/v1/payments?status=processing

# Get canceled payments
GET /api/v1/payments?status=canceled

By Payment Method

Filter payments by payment method:

# Get only PromptPay payments
GET /api/v1/payments?paymentMethod=promptpay

# Get only bank transfer payments
GET /api/v1/payments?paymentMethod=bank_transfer

By Date Range

Filter payments by creation date:

# Get payments from January 2024
GET /api/v1/payments?dateFrom=2024-01-01T00:00:00Z&dateTo=2024-01-31T23:59:59Z

# Get payments created after a specific date
GET /api/v1/payments?dateFrom=2024-01-01T00:00:00Z

Combined Filters

You can combine multiple filters:

# Get succeeded PromptPay payments from January 2024
GET /api/v1/payments?status=succeeded&paymentMethod=promptpay&dateFrom=2024-01-01T00:00:00Z&dateTo=2024-01-31T23:59:59Z

Sorting

Sort Fields

You can sort by the following fields:

amount - Payment amount
status - Payment status
createdAt - Creation date (default)
confirmedAt - Confirmation date
capturedAt - Capture date
referenceId - Reference ID

Sort Order

asc - Ascending order
desc - Descending order (default)

Sorting Examples

# Sort by amount descending (highest first)
GET /api/v1/payments?sortBy=amount&sortOrder=desc

# Sort by creation date ascending (oldest first)
GET /api/v1/payments?sortBy=createdAt&sortOrder=asc

# Sort by status alphabetically
GET /api/v1/payments?sortBy=status&sortOrder=asc

On this page