Getting Started

The External API is how a system integrates with Aloha without a person in front of it: it creates payment requests and card payment links, reads and cancels them, manages the webhook endpoints Aloha notifies, and converts amounts between currencies. Sixteen operations, grouped into four sections in the sidebar, all under /api/external.

This page is written for the operation pages below it. The narrative walkthrough — a key, then a real charge, in four calls — is the Inicio rápido guide.

Two base URLs

The playground on this site calls Sandbox. A key carries its environment in its own prefix, so the two are not interchangeable. Never paste a live key (pay_..._live_...) into a browser.

The key comes from the panel, not from this API

None of the sixteen operations mints an API key. A key is created in the panel of the environment it is for, where it is given a name, the abilities it will carry, and that environment. The full secret is returned once, in the response that creates it, and no later request ever returns it again — a lost key is replaced, not recovered.

Four conventions worth knowing before the first call

Every request carries the key in a header. X-API-KEY or Authorization: Bearer, either one, never in the query string. The key identifies the account by itself, which is why no request in this API carries an account identifier. See Authentication.

Twelve of the sixteen operations require an ability, and the match is exact — payment_links:read does not open payment_links:cancel. The four reference operations declare none, so any valid key of the account reaches them. Each operation page states the ability it requires.

Every id in a path is a UUID. Anything else does not match the route at all and comes back as 404 RESOURCE_NOT_FOUND from the platform, before authentication has run — so a request with no key and a malformed id answers 404, not 401.

A success carries success, message and usually data. The three operations that return no resource of their own — cancelling a payment request, cancelling a card payment link, deleting a webhook endpoint — answer with success and message and no data key at all.

Errors come in two shapes, and the status code does not tell you which

Authentication, origin checking and the per-key rate limit run in middleware, ahead of every controller, and that layer answers with error and code — no success, no message. Everything past that layer answers with success, code and message, plus errors or meta when there is something to put in them.

A 401, a 403 and a 429 each occur in both shapes. Branch on code, never on the status alone, and never on message — the codes are stable, the prose is not. The comparison is case-sensitive: invalid_api_key and INVALID_API_KEY are two different refusals, as are rate_limit_exceeded and RATE_LIMIT_EXCEEDED.

Each operation page lists the refusals it can actually return, past the shared ones. No operation can return every code in the catalogue.