Skip to main content
GET
/
payments
List Payments
curl --request GET \
  --url https://api.example.com/payments
{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Invalid merchant ID"
    }
  ]
}

​
Endpoint

GET https://api.digitzs.com/payments

​
Overview

Use this endpoint to retrieve a paginated list of payment transactions for a specific merchant account.

​
Authentication

HeaderValueRequired
x-api-keyYour API keyYes
AuthorizationBearer {appToken}Yes
appIdYour application IDYes

​
Query Parameters

​
id
string
required
Merchant ID to retrieve payments for
​
limit
integer
Number of results per page (default: 25, max: 100)
​
offset
integer
Number of results to skip for pagination (default: 0)
​
startDate
string
Filter payments created after this date (ISO 8601 format)
​
endDate
string
Filter payments created before this date (ISO 8601 format)
​
status
string
Filter by payment status: pending, completed, failed, refunded, voided

​
Response

​
Success Response (200 OK)

{
  "links": {
    "self": "https://api.digitzs.com/payments?id=merchant_123456&limit=25",
    "next": "https://api.digitzs.com/payments?id=merchant_123456&limit=25&offset=25"
  },
  "data": [
    {
      "type": "payments",
      "id": "pay_abc123",
      "attributes": {
        "paymentType": "card",
        "status": "completed",
        "createdAt": "2024-01-15T10:30:00Z",
        "transaction": {
          "amount": "2500",
          "currency": "USD",
          "invoice": "INV-001",
          "gross": "2500",
          "net": "2399"
        }
      }
    },
    {
      "type": "payments",
      "id": "pay_xyz789",
      "attributes": {
        "paymentType": "ACH",
        "status": "pending",
        "createdAt": "2024-01-15T09:00:00Z",
        "transaction": {
          "amount": "10000",
          "currency": "USD",
          "invoice": "INV-002"
        }
      }
    }
  ],
  "meta": {
    "total": 156,
    "limit": 25,
    "offset": 0,
    "hasMore": true
  }
}
​
data
array
Array of payment objects (see GET /payments/ for full object structure)
​
meta
object
Pagination metadata

​
Code Examples

curl -X GET "https://api.digitzs.com/payments?id=merchant_123456&limit=25" \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer your-app-token" \
  -H "appId: your-app-id"

​
Pagination Example

async function getAllPayments(merchantId) {
  let allPayments = [];
  let offset = 0;
  const limit = 100; // Max per request
  let hasMore = true;

  while (hasMore) {
    const response = await listPayments(merchantId, { limit, offset });
    allPayments = allPayments.concat(response.data);
    hasMore = response.meta.hasMore;
    offset += limit;

    console.log(`Fetched ${allPayments.length} of ${response.meta.total} payments`);
  }

  return allPayments;
}

​
Filtering Best Practices

Always specify both startDate and endDate for better performance:
?startDate=2024-01-01&endDate=2024-01-31
Filter by status to reduce response size:
?status=completed&startDate=2024-01-01
Use maximum limit (100) to minimize API calls when retrieving large datasets:
?limit=100&offset=0

​
Error Responses

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Invalid merchant ID"
    }
  ]
}

​
Common Use Cases

  1. Transaction History: Display payment history in merchant dashboard
  2. Reporting: Generate financial reports for specific date ranges
  3. Reconciliation: Match payments with bank deposits
  4. Analytics: Analyze payment trends and patterns
  5. Customer Support: Search for specific transactions by invoice or date

​
Performance Tips

Optimize Queries: Use date ranges and status filters to reduce result set size and improve response times.
Caching: Consider caching results for completed payments as they won’t change (except for potential refunds).

​
Next Steps

Get Payment Details

View complete details for a specific payment

Create Payment

Process a new payment transaction