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

# Developer API overview

> Read your payments, subscriptions, catalogue and organization from your own systems

## What it is

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

The Developer API is Compago's read-only API for merchants. It exposes what your organization has sold and what it has configured, so you can reconcile against your accounting system, feed a data warehouse, or build an internal dashboard on your own data.

Everything lives under `/api/developer/v1` and authenticates with the API key you already use.

```
https://api-harmony.compago.com/api/developer/v1/...
```

<Info>
  **This version reads. It does not write.** Every endpoint is a `GET`. There is nothing here that creates, updates, archives or deletes, and the API returns `404` for any other method. Creating payments stays on the [payment-acceptance endpoints](/one-time-payment/create); managing your catalogue, links and subscriptions stays in the dashboard.
</Info>

<CardGroup cols={2}>
  <Card title="Payments" icon="receipt" href="/developer/payments">
    Every payment you have taken, with its card, customer and hold state.
  </Card>

  <Card title="Subscriptions" icon="arrows-rotate" href="/developer/subscriptions">
    Recurring agreements, their dunning state and billing history.
  </Card>

  <Card title="Catalogue" icon="box" href="/developer/catalogue">
    Payment links and the products behind them.
  </Card>

  <Card title="Organization" icon="building" href="/developer/organization">
    Your profile, team, salespeople and promotions.
  </Card>

  <Card title="Core concepts" icon="book" href="/core-concepts/pagination">
    Pagination, rate limits and error handling.
  </Card>

  <Card title="Authentication" icon="lock" href="/get-started/authentication">
    Creating and using an API key.
  </Card>
</CardGroup>

## Two API surfaces

Both use the same `x-api-key` header and the same host. They are separate contracts and evolve independently.

| | Payment acceptance | Developer API |
| - | - | - |
| Path | `/api/...` | `/api/developer/v1/...` |
| Purpose | Take money: checkouts, saved cards, terminals | Read what happened and how you are configured |
| Methods | `GET`, `POST`, `PATCH` | `GET` only |
| Pagination | `page` and `pageSize` | `limit` and `cursor` |
| Errors | Mixed. `/payment-method` returns JSON, the rest plain text | Always `{ message, code }` |

The payment-acceptance endpoints are unchanged and are not deprecated. If your integration only creates checkouts, you do not need to move.

<Note>
  The `v1` in the path is a promise: when a breaking change is needed, it ships as `v2` alongside this one rather than changing what your integration already reads.
</Note>

## Getting started

<Steps>
  <Step title="Create an API key">
    In the dashboard, go to **Configuraciones**, then **Desarrollador**. Copy the key immediately: it is shown once. See [Authentication](/get-started/authentication).
  </Step>

  <Step title="Confirm it works">
    ```bash theme={null}
    curl https://api-harmony.compago.com/api/developer/v1/organization \
      -H "x-api-key: $COMPAGO_API_KEY"
    ```

    A `200` with your organization's name means you are connected. A `403` with `MERCHANT_ONLY` means the key belongs to a manufacturer organization, which this API does not serve. A `403` with `KEY_NOT_SCOPED` means the key predates organization binding: create a new one.
  </Step>

  <Step title="Read something real">
    ```bash theme={null}
    curl "https://api-harmony.compago.com/api/developer/v1/payment?limit=5" \
      -H "x-api-key: $COMPAGO_API_KEY"
    ```
  </Step>

  <Step title="Handle pagination and rate limits before you go live">
    Read [Pagination](/core-concepts/pagination) and [Rate limits](/core-concepts/rate-limits). Both have copy-paste helpers.
  </Step>
</Steps>

## What you can see

An API key is bound to exactly one organization: the one it was created in. Every list is filtered to that organization in the database query itself, and an id belonging to anyone else returns `404`, not `403`, so this API cannot be used to discover whether an id exists.

Three things are deliberately absent:

* **Card numbers and stored tokens.** A saved card is referenced only by its `id`. You get the last four digits, the network, the funding source and the issuing bank, and nothing that could be used to charge the card elsewhere.
* **Salesperson credentials.** Password hashes and device tokens are never read from the database by this API, let alone returned.
* **The other side of a promotion.** When a promotion funds one of your payments you see your own fee, not the funding organization's take.

<Note>
  Available to **merchant** organizations. Manufacturer organizations receive `403 MERCHANT_ONLY`: a manufacturer's view of a payment is subject to a customer-data gate that this API does not implement.
</Note>

## Environments

| Environment | Base URL |
| - | - |
| Demo | `https://demo-api-harmony.compago.com/api/developer/v1` |
| Production | `https://api-harmony.compago.com/api/developer/v1` |

Keys are per environment. A demo key will not authenticate against production.