Appearance
Payments API Overview
The Payments API allows agencies to intermediate and track payments on behalf of their clients. You can create shareable payment experiences, browse payment history, and claim existing payments as intermediated by your agency.
Resource Map
The diagram below shows every resource in the Payments API and how links connect them. Start at the Root and follow link relations to reach any resource.
Key Concepts
Before diving into the flows, make sure you're comfortable with these building blocks:
| Concept | Why it matters |
|---|---|
| HATEOAS | You navigate by following links — never hardcode URLs |
| Link Relations | Each link's rel tells you what action it represents — see the Payments Relations catalogue |
| Forms | Some endpoints return a schema describing the data they expect |
| Anchoring | Links with anchor belong to a specific item in a collection |
| Pagination | Collections use next / prev / first / last links |
| Profiles | The profile link tells you the type of the current resource — see the Payments Profiles catalogue |
Flows
The Payments API supports three main flows:
1. Create a Payment Experience
Browse payment recipients, select a destination, and generate a shareable payment link for your client.
2. Browse Intermediated Payments
List all payments intermediated by your agency, view details, status history, and amounts.
3. Claim a Payment
Take an existing payment reference and claim it as intermediated by your agency.
Where to start
If you're new to the API, follow the Getting Started guide first, then work through the Create a Payment Experience flow — it touches the most concepts.
Entrypoints
The three flows start from three different links on the root resource. See Entrypoints for the full list of starting URLs and their production / demo counterparts.
Root Relations and Flows
The root response contains these payment-related link relations, each kicking off one of the flows above:
| Root link relation | Flow | Description |
|---|---|---|
payment-recipients | Payment Experience | Browse destinations and create payment links |
intermediated-payments | Browse Payments | List and inspect all intermediated payments |
claim-intermediation-of-payment | Claim a Payment | Claim an existing payment reference |
Reference
For the full catalogue of relations, profiles, and JSON Schemas used by the Payments API, see:
- Payments Relations — the action vocabulary
- Payments Profiles — what each response represents
- Payments Schemas — the data structures
- Common Schemas — shared types (
amount,intermediation,dynamic-data, …)