Payments

Overview

These examples call the production host. While you build, replace https://api-harmony.compago.com with https://demo-api-harmony.compago.com and use a key from the Demo dashboard. See Environments.

GET /developer/v1/payment returns every payment your organization has taken, newest first, whatever channel it came through: a payment link, a one-time payment, a saved card, a terminal, or a subscription’s recurring charge.

curl "https://api-harmony.compago.com/api/developer/v1/payment?limit=50&status=CONFIRMED" \
  -H "x-api-key: $COMPAGO_API_KEY"

The payment object

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "operationCode": 61695145722,
  "status": "CONFIRMED",
  "type": "CARD_NOT_PRESENT",
  "amount": 1500,
  "currency": "MXN",
  "fee": 3.5,
  "terms": 3,
  "paidTerms": 1,
  "periodicity": "MONTHLY",
  "financingMethod": "MSI",
  "source": "SHAREPAY_PAYMENT_LINK",
  "createdAt": "2026-03-04T05:06:07.089Z",
  "refundedAt": null,
  "heldAmount": null,
  "heldAt": null,
  "capturedAt": null,
  "holdReleasedAt": null,
  "holdExpiresAt": null,
  "holdExpired": false,
  "holdDaysRemaining": null,
  "card": { "lastFourDigits": "4242", "network": "VISA", "fundingSource": "CREDIT", "issuingBank": "BANORTE" },
  "customer": { "firstName": "Ana", "lastName": "Ramirez", "email": "ana@example.com", "phoneNumber": "+525512345678" },
  "paymentLinkId": "11111111-2222-3333-4444-555555555555",
  "paymentIntentId": null,
  "oneTimePaymentId": null,
  "paymentMethodId": null,
  "subscriptionId": null
}

Fields worth explaining

operationCode is the reference your customers quote

id is the API’s identifier. operationCode is the number printed on receipts and shown in the dashboard, and it is what a customer or your support team will read out. Filter on it with ?operationCode=61695145722, an exact match rather than a partial one.

terms and paidTerms describe an installment plan

terms is how many installments the customer agreed to, 1 for a single payment. paidTerms is how many have settled to you.On a plan where you are paid per installment, paidTerms climbs as each one settles. On every other plan you are paid up front, so a settled payment reads as fully paid and an unsettled one as nothing paid.

fee is your cost, not the customer's

The percentage fee charged to you on this payment, after any promotion discount. The promotion’s own economics, meaning what the funding organization absorbed, are not part of this response.

The hold fields describe an authorization

A payment created with holdFunds reserves money without capturing it. heldAmount is what the bank authorized and amount is what actually moved, so they differ after a partial capture. holdExpiresAt is when the authorization lapses and is reported even after the hold ends, because it stays a fact about the payment. holdExpired and holdDaysRemaining only answer while the payment is still HELD.See Hold and capture.

The source ids tell you where the payment came from

Usually exactly one of paymentLinkId, oneTimePaymentId, paymentMethodId and paymentIntentId is set, and subscriptionId is set as well when the payment is a recurring charge. Each is filterable.

Statuses

Status	Meaning
`CONFIRMED`	The payment succeeded. Funds are captured or scheduled for settlement
`CANCELLED`	The payment did not complete
`REFUNDED`	The payment was returned to the customer
`HELD`	Funds are authorized but not captured
`HOLD_RELEASED`	The authorization was released without being captured
`HOLD_EXPIRED`	The authorization lapsed before it was captured

These are the statuses a merchant sees, and the only ones this API returns. Compago tracks finer internal states while a payment is in flight; they are a detail of how settlement works and are collapsed into the list above before the response leaves the API. A payment that is still settling reports CONFIRMED, which is what the dashboard shows you.

Reconciliation

The common job is “everything that happened yesterday”. Bound the window, then follow the cursor.

curl "https://api-harmony.compago.com/api/developer/v1/payment?createdAtFrom=2026-03-03T00:00:00Z&createdAtTo=2026-03-03T23:59:59Z&limit=100" \
  -H "x-api-key: $COMPAGO_API_KEY"

async function paymentsBetween(apiKey, from, to) {
  const payments = [];
  let cursor = null;

  do {
    const url = new URL('https://api-harmony.compago.com/api/developer/v1/payment');
    url.searchParams.set('createdAtFrom', from.toISOString());
    url.searchParams.set('createdAtTo', to.toISOString());
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, { headers: { 'x-api-key': apiKey } });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

    const body = await res.json();
    payments.push(...body.data);
    cursor = body.pagination.nextCursor;
  } while (cursor);

  return payments;
}

Bound the window rather than crawling the whole history each night. It is faster, it costs a fraction of your rate-limit budget, and it gives a stable result: a completed day does not gain new rows underneath you.

Filters

Parameter	Notes
`status`	Repeat for several: `?status=CONFIRMED&status=REFUNDED`
`type`	`CARD_PRESENT` or `CARD_NOT_PRESENT`
`operationCode`	Exact match on the receipt reference
`createdAtFrom`, `createdAtTo`	ISO-8601 bounds, both inclusive
`paymentLinkId`	Everything sold through one link
`subscriptionId`	Everything billed by one subscription
`oneTimePaymentId`	The payment for one one-time link
`paymentMethodId`	Everything charged to one saved card

Two endpoints return the same payment object, already scoped:

GET /developer/v1/subscription/{id}/payment for one subscription’s billing history
GET /developer/v1/payment-method/{id}/payment for everything charged to one saved card

What this endpoint does not include

Payments funded by one of your promotions but taken by another merchant are not listed here. “Your payments” means the ones you took. A promotion-funded payment belongs to another merchant and carries that merchant’s customer details.

Get Started

Core Concepts

Developer API

Accept Payments

Integrations

Overview

The payment object

Fields worth explaining

Statuses

Reconciliation

Filters

What this endpoint does not include

​Overview

​The payment object

​Fields worth explaining

​Statuses

​Reconciliation

​Filters

​Related views

​What this endpoint does not include

Overview

The payment object

Fields worth explaining

Statuses

Reconciliation

Filters

Related views

What this endpoint does not include