# Qualy API

> REST API for international-education payments — create payment intents, orders, splits and subscriptions, and track a payment from creation through checkout.

The Qualy API is organised around REST with predictable, resource-oriented URLs, JSON request/response bodies, and standard HTTP response codes. Only `GET` and `POST` are used, and each request works on a single object — there are no bulk updates. The current version is `v1`; the base URL is `https://api.qualyhq.com/v1`.

The full OpenAPI specification is published at https://v1-spec.qualyhq.com/. Qualy also exposes an MCP server for AI assistants — see https://docs.qualyhq.com/docs/mcp-server.

## Introduction

- [Getting started](https://docs.qualyhq.com/)

## Getting started

- [Quick start](https://docs.qualyhq.com/docs/guides/quick-start): Go from zero to your first collected payment with the Qualy API in about 10 minutes.
- [Creating your API keys](https://docs.qualyhq.com/docs/api-keys): Use API keys to authenticate API requests to Qualy.
- [Setting up webhooks](https://docs.qualyhq.com/docs/webhooks): Use incoming webhooks to get real-time updates of Qualy events.
- [Webhook events reference](https://docs.qualyhq.com/docs/webhooks/events): Every webhook event type Qualy can send, when it fires, and what the payload looks like.
- [Terminology](https://docs.qualyhq.com/docs/terminology): Learn key terms used by the Qualy API.
- [MCP Server](https://docs.qualyhq.com/docs/mcp-server): Connect AI agents to Qualy through the Model Context Protocol (MCP) server.
- [AI agents & coding tools](https://docs.qualyhq.com/docs/ai-tools): Everything an AI assistant or AI coding tool (Cursor, Lovable, Bolt, v0, Replit, ChatGPT, Claude) needs to understand and build against the Qualy API.

## Key concepts

- [Multi-tenancy](https://docs.qualyhq.com/docs/tenants): Understand the multi-tenant architecture of Qualy.
- [Authentication](https://docs.qualyhq.com/docs/authentication): Authorizing API requests to Qualy.
- [Querying data](https://docs.qualyhq.com/docs/queries): Querying data via the Qualy API.
- [Smart references](https://docs.qualyhq.com/docs/smart-references): Use ObjectIds or natural identifiers in supported reference fields.
- [Idempotency](https://docs.qualyhq.com/docs/idempotency): Prevent duplicate financial operations with idempotent API requests.
- [Currencies & countries](https://docs.qualyhq.com/docs/currencies-countries): Learn how Qualy handles curencies and countries.
- [Errors](https://docs.qualyhq.com/docs/errors): Learn how Qualy handles error codes, messages and more.

## Implementation guides

- [Creating payment intents](https://docs.qualyhq.com/docs/guides/creating-payment-intents): Creating a payment using Qualy's API.
- [Creating orders](https://docs.qualyhq.com/docs/guides/creating-orders): Creating a payment plan (Order) using Qualy's API.
- [Creating payment splits](https://docs.qualyhq.com/docs/guides/creating-payment-splits): Creating a payment split using Qualy's API.
- [Bulk payment splits](https://docs.qualyhq.com/docs/guides/bulk-payment-splits): Group many partner payment splits into one settlement, mark it paid, and generate a statement PDF.
- [Creating subscriptions](https://docs.qualyhq.com/docs/guides/creating-subscriptions): Creating a subscription using Qualy's API.
- [Financing & installments](https://docs.qualyhq.com/docs/guides/financing-options): Retrieve installment and pay-later financing options for a payment, then simulate a specific plan to get the per-installment amount, total cost, and fees.
- [Tax rates & calculation](https://docs.qualyhq.com/docs/guides/handling-using-tax-rates): Learn how Qualy handles different types of Tax Rates, including inclusive/exclusive rates.
- [Issuing refunds](https://docs.qualyhq.com/docs/guides/issuing-transaction-refunds): Learn how Qualy can issue refunds to payments.
- [Handling disputes](https://docs.qualyhq.com/docs/guides/handling-disputes): List, inspect, and respond to payment disputes (chargebacks) with the Qualy API.
- [Dunning (chasing payments)](https://docs.qualyhq.com/docs/guides/dunning): Chase overdue receivables with Qualy's dunning API — send notices, track chases, and record outcomes.
- [Approvals](https://docs.qualyhq.com/docs/guides/approvals): Gate money-moving actions behind maker-checker approval policies with the Qualy API.
- [Creating bank accounts](https://docs.qualyhq.com/docs/guides/creating-bank-accounts): Creating a bank account using Qualy's API.
- [Public demo](https://docs.qualyhq.com/docs/guides/public-demos): Embeddable API endpoints for FX rate comparisons and financing simulations — no backend or reverse proxy required.
- [Collecting payments](https://docs.qualyhq.com/docs/guides/collecting-payments): Two ways to collect payments - redirect to Qualy's payment portal, or call the API directly for PIX, Boleto, PayID, bank transfers, and more.

## Testing

- [Simulating payments](https://docs.qualyhq.com/docs/testing): Simulate payments to test your integration.

## API Reference

Full OpenAPI 3.x specification: https://v1-spec.qualyhq.com/ — the authoritative reference for every endpoint, parameter, and schema. Key operations:

- [Storage](https://v1-spec.qualyhq.com/#post-/v1/storage/files/upload/sign)
- [Settings](https://v1-spec.qualyhq.com/#get-/v1/settings)
- [Payment intents](https://v1-spec.qualyhq.com/#post-/v1/payment-intents/create)
- [Services](https://v1-spec.qualyhq.com/#post-/v1/services/create)
- [Activities](https://v1-spec.qualyhq.com/#post-/v1/activities/create)
- [Orders](https://v1-spec.qualyhq.com/#post-/v1/orders/create)
- [Teams](https://v1-spec.qualyhq.com/#post-/v1/teams/create)
- [Contacts](https://v1-spec.qualyhq.com/#post-/v1/contacts/create)
- [Payment splits](https://v1-spec.qualyhq.com/#post-/v1/payment-splits/create)
- [Partnerships](https://v1-spec.qualyhq.com/#post-/v1/partnerships/create)
- [Bank accounts](https://v1-spec.qualyhq.com/#post-/v1/bank-accounts/create)
- [Tax](https://v1-spec.qualyhq.com/#post-/v1/tax/create)
- [Transactions](https://v1-spec.qualyhq.com/#post-/v1/transactions/create)
- [Payment gateways](https://v1-spec.qualyhq.com/#get-/v1/payment-gateways/payment-options/-paymentIntentId-)
- [Search](https://v1-spec.qualyhq.com/#post-/v1/search/-index-)
- [Subscriptions](https://v1-spec.qualyhq.com/#post-/v1/subscriptions/create)
- [Custom fields](https://v1-spec.qualyhq.com/#post-/v1/fields/create)
- [Disputes](https://v1-spec.qualyhq.com/#get-/v1/disputes)

## Miscellaneous

- [API fees and limits](https://docs.qualyhq.com/docs/fees-limits): Learn about what fees and limits apply for the Qualy API usage.
- [Stress testing](https://docs.qualyhq.com/docs/stress-testing): Important information about stress testing and load testing our API.
- [Product updates](https://changelog.qualyhq.com/)
- [Product training](https://qualyhq.com/training/)
- [System status](https://qualyhq.statuspage.io/)
- [Contact us](https://qualyhq.com/contact-us/)

## Optional

- [Full documentation corpus](https://docs.qualyhq.com/llms-full.txt): every guide and reference page concatenated into one Markdown file for one-fetch deep retrieval.
- [Glossary (JSON)](https://docs.qualyhq.com/glossary.json): machine-readable { term, definition } list of Qualy API terminology.