List Payments - Digitzs API Documentation

List Payments

curl --request GET \
  --url https://api.example.com/payments

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/payments"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

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

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Not authorized to access this merchant's payments"
    }
  ]
}

GET

payments

List Payments

curl --request GET \
  --url https://api.example.com/payments

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/payments"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

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

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Not authorized to access this merchant's payments"
    }
  ]
}

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

Header	Value	Required
`x-api-key`	Your API key	Yes
`Authorization`	`Bearer {appToken}`	Yes
`appId`	Your application ID	Yes

Query Parameters

string

required

Merchant ID to retrieve payments for

integer

Number of results per page (default: 25, max: 100)

integer

Number of results to skip for pagination (default: 0)

string

Filter payments created after this date (ISO 8601 format)

string

Filter payments created before this date (ISO 8601 format)

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
  }
}

array

Array of payment objects (see GET /payments/ for full object structure)

object

Pagination metadata

Show properties

integer

Total number of payments matching the query

integer

Number of results per page

integer

Current pagination offset

boolean

Whether more results are available

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"

const axios = require('axios');

async function listPayments(merchantId, options = {}) {
  const params = new URLSearchParams({
    id: merchantId,
    limit: options.limit || 25,
    offset: options.offset || 0,
    ...options.filters
  });

  const response = await axios.get(
    `https://api.digitzs.com/payments?${params}`,
    {
      headers: {
        'x-api-key': 'your-api-key',
        'Authorization': 'Bearer your-app-token',
        'appId': 'your-app-id'
      }
    }
  );

  console.log(`Retrieved ${response.data.data.length} payments`);
  console.log(`Total: ${response.data.meta.total}`);
  return response.data;
}

// Get first page
listPayments('merchant_123456');

// Get completed payments from specific date range
listPayments('merchant_123456', {
  limit: 50,
  filters: {
    status: 'completed',
    startDate: '2024-01-01',
    endDate: '2024-01-31'
  }
});

import requests
from urllib.parse import urlencode

def list_payments(merchant_id, limit=25, offset=0, **filters):
    url = "https://api.digitzs.com/payments"

    params = {
        "id": merchant_id,
        "limit": limit,
        "offset": offset,
        **filters
    }

    headers = {
        "x-api-key": "your-api-key",
        "Authorization": "Bearer your-app-token",
        "appId": "your-app-id"
    }

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()

    data = response.json()
    print(f"Retrieved {len(data['data'])} payments")
    print(f"Total: {data['meta']['total']}")
    return data

# Get first page
list_payments("merchant_123456")

# Get completed payments from January 2024
list_payments(
    "merchant_123456",
    limit=50,
    status="completed",
    startDate="2024-01-01",
    endDate="2024-01-31"
)

<?php

function listPayments($merchantId, $options = []) {
    $params = array_merge([
        'id' => $merchantId,
        'limit' => 25,
        'offset' => 0
    ], $options);

    $url = "https://api.digitzs.com/payments?" . http_build_query($params);

    $headers = [
        "x-api-key: your-api-key",
        "Authorization: Bearer your-app-token",
        "appId: your-app-id"
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);
    echo "Retrieved " . count($data["data"]) . " payments\n";
    echo "Total: " . $data["meta"]["total"] . "\n";
    return $data;
}

// Get first page
listPayments("merchant_123456");

// Get completed payments from January 2024
listPayments("merchant_123456", [
    'limit' => 50,
    'status' => 'completed',
    'startDate' => '2024-01-01',
    'endDate' => '2024-01-31'
]);
?>

require 'net/http'
require 'json'
require 'uri'

def list_payments(merchant_id, options = {})
  params = {
    id: merchant_id,
    limit: options[:limit] || 25,
    offset: options[:offset] || 0
  }.merge(options[:filters] || {})

  uri = URI('https://api.digitzs.com/payments')
  uri.query = URI.encode_www_form(params)

  request = Net::HTTP::Get.new(uri)
  request['x-api-key'] = 'your-api-key'
  request['Authorization'] = 'Bearer your-app-token'
  request['appId'] = 'your-app-id'

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  data = JSON.parse(response.body)
  puts "Retrieved #{data['data'].length} payments"
  puts "Total: #{data['meta']['total']}"
  data
end

# Get first page
list_payments('merchant_123456')

# Get completed payments from January 2024
list_payments('merchant_123456', {
  limit: 50,
  filters: {
    status: 'completed',
    startDate: '2024-01-01',
    endDate: '2024-01-31'
  }
})

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

Date Range Queries

Always specify both startDate and endDate for better performance:

?startDate=2024-01-01&endDate=2024-01-31

Status Filtering

Filter by status to reduce response size:

?status=completed&startDate=2024-01-01

Large Result Sets

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"
    }
  ]
}

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "Not authorized to access this merchant's payments"
    }
  ]
}

Common Use Cases

Transaction History: Display payment history in merchant dashboard
Reporting: Generate financial reports for specific date ranges
Reconciliation: Match payments with bank deposits
Analytics: Analyze payment trends and patterns
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

Get Payment Status Merchant Endpoints

​Endpoint

​Overview

​Authentication

​Query Parameters

​Response

​Success Response (200 OK)

​Code Examples

​Pagination Example

​Filtering Best Practices

​Error Responses

​Common Use Cases

​Performance Tips

​Next Steps

Get Payment Details

Create Payment

Endpoint

Overview

Authentication

Query Parameters

Response

Success Response (200 OK)

Code Examples

Pagination Example

Filtering Best Practices

Error Responses

Common Use Cases

Performance Tips

Next Steps