# Creating and finding payments

> Create a payment for a contact (finding or adding them first), find payments with filters and date windows, and get their receipts and tax invoices.

> **Note — For assistants**
>
> An assistant connected to the Qualy MCP server reads this guide as the resource `qualy://guides/payments`. Generated from the Qualy MCP server’s guide registry.

A payment is money you collect from one contact: line items in one currency, an optional due date, and a payment link the customer pays through. Find the contact, then create the payment. To find payments later, filter the list instead of paging through it.

## 1. Find the contact

`payment_intent_create` takes the contact as an id or an email, and the email must already belong to a contact. So make sure they are on file:

| You have | Use | Notes |
| --- | --- | --- |
| A name, a phone number or part of an email | `search` with `index: contacts` | Fuzzy. Returns hits with their ids; follow up with `contact_get`. |
| An email | `contact_get`, or `entity_resolve` with `entity: contact` | Exact. `entity_resolve` returns only the id. |
| No hit yet | `contact_list` with `status: inactive` | Archived contacts are never in search, and lists leave them out unless you ask. |

Create someone with `contact_create` (only the email is required) only when none of these finds them. An email belongs to one contact: if one already has it, archived included, nothing is created and the call fails with 409, with the existing contact's id in details.contact and its status in details.status. Use that contact, and change its details with `contact_update` if they differ.

## 2. Create the payment

Call `payment_intent_create` with:

- `contact`: the id or email from step 1.
- `currency`: an ISO 4217 code, such as AUD or USD.
- `items`: one or more, each with a `name` and an `amount` above zero in major units (1500.50 is 1,500.50), and optionally a `description`.
- `dueAt`: optional, a date (YYYY-MM-DD) between 2000 and 2100. Qualy's automatic payment reminders work from it.

The first call returns a preview to show the person: who, each item, the total and the due date, or "with no due date". Nothing is charged: the customer pays through the payment link. A payment Qualy would not create, such as one with a due date out of range, is refused at the preview, before anyone approves it. Once approved, the call creates the payment and returns it, with its display `number`, `status`, `total` and the payment link to share in `links.short`.

For payments that repeat on a schedule, set up a subscription instead: [`qualy://guides/subscriptions`](/docs/mcp-server/guides/subscriptions.md). To remind the customer about a payment later, see [`qualy://guides/contacting-customers`](/docs/mcp-server/guides/contacting-customers.md).

## 3. Find payments

- One payment: `payment_intent_get` with its id or display number (QLY-PYMT-1234). It returns data (items, contact, totals, links), not a document.
- Several: `payment_intent_list`, newest first. Filter by `contact` (id or email), `status`, a date window (`createdAtFrom`/`createdAtTo`, `dueAtFrom`/`dueAtTo`, `paidAtFrom`/`paidAtTo`, where paidAt is when it was paid in full) or the total (`totalMin`/`totalMax` in major units; set both to the same value for an exact amount). `sort` names the date to order by, such as dueAt or paidAt, with a leading - for newest first. `limit` is at most 100.

Both ends of a window are inclusive. A bare YYYY-MM-DD is a whole UTC day, so for a local day pass an offset, such as 2026-09-24T00:00:00+10:00.

`status` takes the API value; say the label to people: Draft `added`, Upcoming `requires-condition`, Due `due`, Processing `processing`, Overdue `overdue`, Canceled `canceled`, Pending review `review-pending`, Partially paid `paid-partial`, Paid `paid-full`, Partial refund `refunded-partial`, Full refund `refunded-full`.

`count` is how many payments match the whole filter, and `hasMore` says whether there are more pages (`nextOffset` is where the next one starts). Never present one page as all of them. For totals and trends, use `payment_intent_stats`, which adds up in the database, instead of adding up pages.

## 4. Get its documents

Qualy generates the PDFs itself:

- `payment_intent_receipt`: the receipt, once the payment is Paid, Partially paid or Partial refund.
- `payment_intent_tax_invoice`: the tax invoice, when tax invoices are turned on in your account's payment settings. When they are off it says so: that is a settings answer, not a missing document.

Each returns the file and a download `url` that stops working at `expiresAt`, about 15 minutes later. Hand over the file, and generate it again rather than reusing an old link. Never transcribe a document's figures yourself: the PDF is the record.

## Worked examples

### Find a contact by name

```json
{
  "tool": "search",
  "arguments": {
    "index": "contacts",
    "query": "Jane Doe"
  }
}
```

Each hit carries the contact’s id. No hits is not proof they aren’t on file: check contact_list with status inactive before creating anyone.

### Create a payment with two items

```json
{
  "tool": "payment_intent_create",
  "arguments": {
    "contact": "jane.doe@example.com",
    "currency": "AUD",
    "items": [
      {
        "name": "Tuition fee, Term 1",
        "amount": 4500
      },
      {
        "name": "Enrolment fee",
        "amount": 250
      }
    ],
    "dueAt": "2026-11-30"
  }
}
```

Amounts are major units: 4500 is AUD 4,500.00. Once created, share the payment link in links.short.

Previews first: the call returns a preview to show the person. Call it again with the same arguments plus `confirmationId` and `userConfirmed: true` only after they approve.

### List one contact’s overdue payments, oldest due first

```json
{
  "tool": "payment_intent_list",
  "arguments": {
    "contact": "jane.doe@example.com",
    "status": "overdue",
    "sort": "dueAt"
  }
}
```

count is how many there are in all. While hasMore is true, call again with offset set to nextOffset.

### List the payments paid in full in September (UTC)

```json
{
  "tool": "payment_intent_list",
  "arguments": {
    "paidAtFrom": "2026-09-01",
    "paidAtTo": "2026-09-30",
    "limit": 100
  }
}
```

For how much was collected, ask payment_intent_stats rather than adding up this page.

### Get the receipt for a paid payment

```json
{
  "tool": "payment_intent_receipt",
  "arguments": {
    "paymentIntentId": "QLY-PYMT-1234"
  }
}
```

Hand over the returned file. The link expires: generate the receipt again rather than reusing it.