Pagination

List endpoints return paginated results to efficiently handle large datasets. Pagination divides results into pages, reducing response size and improving API performance.

Request Parameters

Include pagination parameters in the query string:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based index)
`pagesize`	integer	`10`	Number of items per page (max: 100)

Paginated request

curl https://api-staging.martis.id/api/v1/payments/charges?page=2&pagesize=20 \
  --header 'Authorization: Bearer {API_KEY}'

Response Format

Paginated responses include metadata alongside the data array:

Paginated response

{
  "status": "success",
  "data": [
    {
      "id": "01HZCHARGE123456ABCDEF",
      "payment_method": "qris",
      "status": "success",
      "amount": 50000.00
    },
    {
      "id": "01HZCHARGE789012GHIJKL",
      "payment_method": "virtual_account",
      "status": "pending",
      "amount": 150000.00
    }
  ],
  "page": 2,
  "page_size": 20,
  "total_items": 157
}

Response Attributes

Name
data
Type
array
Description
Array of resource objects for the current page
Name
page
Type
integer
Description
Current page number (1-based)
Name
page_size
Type
integer
Description
Number of items per page in this response
Name
total_items
Type
integer
Description
Total number of items across all pages

Calculating Total Pages

Derive the total number of pages from the response metadata:

Calculate total pages

const totalPages = Math.ceil(totalItems / pageSize);

Pagination Examples

First Page

Request first page

curl https://api-staging.martis.id/api/v1/payments/charges?page=1&pagesize=10 \
  --header 'Authorization: Bearer {API_KEY}'

Specific Page

Request page 5

curl https://api-staging.martis.id/api/v1/payments/charges?page=5&pagesize=10 \
  --header 'Authorization: Bearer {API_KEY}'

Custom Page Size

Request with custom page size

curl https://api-staging.martis.id/api/v1/payments/charges?page=1&pagesize=50 \
  --header 'Authorization: Bearer {API_KEY}'

Iterating Through Pages

JavaScript Implementation

Iterate all pages

async function fetchAllCharges() {
  const allCharges = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://api-staging.martis.id/api/v1/payments/charges?page=${page}&pagesize=50`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    );
    
    const result = await response.json();
    allCharges.push(...result.data);
    
    const totalPages = Math.ceil(result.total_items / result.page_size);
    hasMore = page < totalPages;
    page++;
  }
  
  return allCharges;
}

Python Implementation

Iterate all pages

import requests

def fetch_all_charges():
    all_charges = []
    page = 1
    
    while True:
        response = requests.get(
            'https://api-staging.martis.id/api/v1/payments/charges',
            params={'page': page, 'pagesize': 50},
            headers={'Authorization': f'Bearer {API_KEY}'}
        )
        
        result = response.json()
        all_charges.extend(result['data'])
        
        total_pages = -(-result['total_items'] // result['page_size'])
        if page >= total_pages:
            break
        page += 1
    
    return all_charges

Best Practices

Performance

Use appropriate page sizes — Larger pages reduce API calls but increase response time and memory usage
Avoid fetching all pages — Implement filtering and search to reduce result sets
Cache when possible — Store frequently accessed pages to reduce API load

Implementation

Handle empty results — An empty data array indicates no more results
Validate page bounds — Requesting beyond the last page returns an empty array
Use consistent ordering — Results are ordered by creation date (newest first) by default

Error Handling

Check for valid responses — Verify the response status before processing pagination metadata
Handle rate limits — Implement backoff when iterating through many pages

Edge Cases

Scenario	Result
`page=0` or negative	Returns page 1
`page` exceeds total pages	Returns empty `data` array
`pagesize=0` or negative	Uses default page size
`pagesize` exceeds 100	Capped at 100
No items exist	Returns empty `data` with `total_items: 0`

Supported Endpoints

Pagination is available on all list endpoints:

Endpoint	Resource
`GET /v1/payments/charges`	Payment charges
`GET /v1/payouts`	Payouts
`GET /v1/transfers`	Transfers
`GET /v1/payments/methods`	Payment methods