Creating and finding payments

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:

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. To remind the customer about a payment later, see qualy://guides/contacting-customers.

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

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

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

{
  "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)

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

{
  "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.