> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Read the payments your organization has taken, with filters built for reconciliation

## Overview

<Note>
  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-started/environments).
</Note>

`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.

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

## The payment object

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/payment-method/hold).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

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

<Note>
  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.
</Note>

## Reconciliation

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

```bash theme={null}
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"
```

```javascript theme={null}
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;
}
```

<Tip>
  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.
</Tip>

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

## Related views

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

<Warning>
  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.
</Warning>