AI agents & coding tools

Qualy is built to be read and used by AI. Whether you're pointing an AI coding tool at Qualy to generate an integration, or connecting an assistant that calls the API on your behalf, everything it needs is published in a machine-readable form — a curated llms.txt index, plain-Markdown docs, an OpenAPI spec, a glossary, and a remote MCP server.

This page is the one link to hand an AI tool. Paste it (or the resources below) into your assistant and it can get from zero to a working payment on its own.

Two ways AI works with Qualy

There are two distinct things an AI tool might do, and they use different resources:

• Generate integration code — a coding tool (Cursor, Lovable, Bolt, v0, Replit, GitHub Copilot) writes an app that talks to the Qualy REST API. It needs documentation it can read: the llms.txt index, the Markdown docs, and the OpenAPI spec.
• Call the API directly — an assistant (ChatGPT, Claude, or your own agent) performs tasks against your live data: find a contact, raise a payment request, search. It connects to the MCP server, which exposes a curated, tenant-scoped set of tools.

Many teams use both — a coding tool to build their product surface, an assistant for day-to-day operations.

Machine-readable resources

Every resource below is public and stable. Point any tool at these URLs.

Point a coding tool at Qualy

The fastest way to give any AI coding tool accurate context is to hand it the llms.txt index. From there it can follow links to the exact pages it needs.

Build against the Qualy API. Read https://docs.qualyhq.com/llms.txt for an index of the docs, and https://v1-spec.qualyhq.com/swagger-spec.json for the full OpenAPI spec. The base URL is https://api.qualyhq.com/v1 — it only uses GET and POST and returns JSON.

Most tools accept a docs URL or let you paste this as context. Tools with native web access (Cursor's @Docs, ChatGPT, Claude) can fetch the URLs directly; for others, paste the relevant .md pages inline.

If your tool speaks MCP, you can also connect the Qualy MCP server so the assistant can look things up against real data while it builds — Cursor, Windsurf, Replit, ChatGPT, and Claude all support remote MCP servers.

The one flow that matters: accept a payment

If you tell a coding tool to "accept a payment with Qualy," this is the path to generate. Create a Payment Intent for a contact, then redirect the payer to the hosted portal URL returned in links.short. Qualy handles method selection, payer verification, processing, and confirmation — no payment UI to build, and card payments stay PCI-compliant on the hosted portal.

curl https://api.qualyhq.com/v1/payment-intents/create \
  -X POST \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": "camila@example.com",
    "currency": "AUD",
    "items": [{ "name": "Tuition — Semester 1", "amount": 12000 }]
  }'

const res = await fetch('https://api.qualyhq.com/v1/payment-intents/create', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey your-api-key-here',
    'X-TENANT-ID': 'your-tenant-id-here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact: 'camila@example.com',
    currency: 'AUD',
    items: [{ name: 'Tuition — Semester 1', amount: 12000 }],
  }),
})

const { data: intent } = await res.json()

// Send this URL to the payer — email, SMS, or a redirect.
console.log(intent.links.short)

The contact field takes an email directly thanks to Smart references — no separate lookup needed. See Collecting payments for the full flow, including calling payment methods (PIX, Boleto, PayID, bank transfer) directly instead of using the portal.

What a tool needs to know to get it right

A few conventions keep generated code correct on the first try:

• Base URL — https://api.qualyhq.com/v1. Only GET and POST are used; each request works on a single object (no bulk updates).
• Auth — two headers on every request: Authorization: ApiKey <key> and X-TENANT-ID: <tenant-id>. Create both in the Dashboard under Settings → API keys & webhooks. See API keys and Multi-tenancy. (The MCP server uses a single bearer header and no tenant header — the tenant is encoded in the key.)
• Responses are wrapped in a data envelope — read res.data, not the top-level object.
• Errors come back with a machine-readable code and message — see Errors so your tool can branch on them.
• Idempotency — send an idempotency key on writes so retries never double-charge.
• Smart references — wherever an endpoint takes a contact, partnership, or service, you can pass a natural identifier (email, code, name) instead of an ObjectId. See Smart references.

Test mode

Generated code should run against a sandbox before it touches real money. Test mode lets you simulate payments — including test cards — without moving funds. Sandbox access is granted on request; get in touch to have it enabled for your tenant.