Skip to main content

​
Overview

The List One-Time Payments endpoint allows you to retrieve all payment links created by your organization. You can filter results by status and currency, and use pagination to handle large datasets. Common use cases:
  • View all payment links in a dashboard
  • Filter by payment status (PENDING, CONFIRMED, CANCELLED)
  • Generate reports and reconciliation data
  • Monitor payment activity across your organization

​
Authentication

This endpoint requires API key authentication using the x-api-key header.
Your API key can be found in your organization settings. Keep it secure and never expose it in client-side code.

​
Query Parameters

​
page
integer
default:1
Page number for pagination. Must be a positive integer.
​
pageSize
integer
default:100
Number of items to return per page. Must be between 1 and 500.
​
status
string
Filter payments by status. Available values:
  • PENDING - Payment link is active and awaiting payment
  • CONFIRMED - Payment has been successfully completed
  • CANCELLED - Payment link has been cancelled
​
currency
string
Filter payments by currency. Currently only MXN is supported.

​
Response Format

The endpoint returns a paginated response with the following structure: 
{
  "count": 245,
  "page": 1,
  "pageSize": 100,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "PENDING",
      "description": "Payment for order #1234",
      "amount": 100,
      "currency": "MXN",
      "externalId": "order-1234",
      "expiresAt": "2026-01-11T10:30:00Z",
      "redirectUrl": "https://example.com/success",
      "homepageUrl": "https://example.com",
      "createdAt": "2026-01-09T10:30:00Z",
      "updatedAt": "2026-01-09T10:30:00Z",
      "billingInformation": {
        "email": "[email protected]",
        "firstName": "María",
        "lastName": "González",
        "phoneNumber": "+5215512345678",
        "address": {
          "addressLine": "Av. Insurgentes Sur 1234",
          "city": "Ciudad de México",
          "state": "CDMX",
          "zip": "03100"
        }
      }
    }
  ]
}

​
Response Fields

  • count - Total number of payments matching your filter criteria
  • page - Current page number
  • pageSize - Number of items per page
  • items - Array of payment objects

​
Examples

​
List all payments

curl -X GET 'https://api.harmony.compago.com/api/one-time-payment' \
  -H 'x-api-key: YOUR_API_KEY'

​
Filter by status

curl -X GET 'https://api.harmony.compago.com/api/one-time-payment?status=PENDING' \
  -H 'x-api-key: YOUR_API_KEY'

​
Pagination example

curl -X GET 'https://api.harmony.compago.com/api/one-time-payment?page=2&pageSize=50' \
  -H 'x-api-key: YOUR_API_KEY'

​
Filter by multiple parameters

curl -X GET 'https://api.harmony.compago.com/api/one-time-payment?status=CONFIRMED&currency=MXN&page=1&pageSize=50' \
  -H 'x-api-key: YOUR_API_KEY'

​
Best Practices

Optimize page sizes - Use appropriate page sizes for your use case. Smaller pages (10-50 items) for UI display, larger pages (100-500 items) for batch processing.
Filter when possible - Use status and currency filters to reduce the dataset and improve query performance.
Handle pagination properly - Always check the count field to determine the total number of pages available.
The maximum page size is 500 items. Requests exceeding this limit will return a 400 error.

​
Common Use Cases

​
Dashboard View

Display recent payments with status filtering: 
// Fetch the most recent pending payments for dashboard display
const params = new URLSearchParams({
  status: 'PENDING',
  page: '1',
  pageSize: '20'
});

const response = await fetch(
  `https://api.harmony.compago.com/api/one-time-payment?${params}`,
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);

const data = await response.json();
// Display data.items in your dashboard UI

​
Reconciliation

Export all confirmed payments for a specific period: 
// Fetch all confirmed payments for reconciliation
let allConfirmedPayments = [];
let page = 1;

while (true) {
  const params = new URLSearchParams({
    status: 'CONFIRMED',
    page: page.toString(),
    pageSize: '500' // Maximum page size for efficiency
  });

  const response = await fetch(
    `https://api.harmony.compago.com/api/one-time-payment?${params}`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );

  const data = await response.json();
  allConfirmedPayments = allConfirmedPayments.concat(data.items);

  if (page * 500 >= data.count) break;
  page++;
}

// Export to CSV or process for reconciliation

​
Reporting

Generate payment statistics: 
// Fetch counts by status
const statuses = ['PENDING', 'CONFIRMED', 'CANCELLED'];
const stats = {};

for (const status of statuses) {
  const params = new URLSearchParams({
    status,
    page: '1',
    pageSize: '1' // We only need the count, not the items
  });

  const response = await fetch(
    `https://api.harmony.compago.com/api/one-time-payment?${params}`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );

  const data = await response.json();
  stats[status] = data.count;
}

console.log('Payment Statistics:', stats);
// { PENDING: 42, CONFIRMED: 158, CANCELLED: 15 }

​
Error Responses

​
400
error
Invalid request parameters or missing organization context.
​
401
error
Unauthorized - missing or invalid API key.

​
Next Steps

Create Payment

Learn how to create new one-time payment links

Cancel Payment

Learn how to cancel active payment links