> For the complete documentation index, see [llms.txt](https://docs.alternativepayments.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alternativepayments.io/getting-started/quick-start/guides.md). # Guides This guide includes full reference and real-world examples for every endpoint listed in this documentation. Each section provides an overview of the endpoint, available fields, their meaning, and a working example. *** ## ๐Ÿ” Authentication ### Get OAuth Token **Description**\ Generates an OAuth 2.0 token using `client_credentials`. Required before making any authenticated requests. **Method & Path**\ `POST /oauth/token` **Input Parameters** * `grant_type` (required): Must be `client_credentials` * Provide `client_id` and `client_secret` using Basic Auth (base64-encoded) **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/oauth/token \ -H "Authorization: Basic BASE64(client_id:client_secret)" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" ``` **Response:** ```json { "access_token": "eyJ0eXAiOiJKV1QiLCJh...", "token_type": "bearer", "expires_in": 3600 } ``` **Header format:** ```http Authorization: Bearer ``` **Note:** There is no refresh token in the client-credentials flow. If the token expires, request a new one. *** ## ๐Ÿ‘ค Customers ### List Customers **Description**\ Retrieves a paginated list of customer records. **Method & Path**\ `GET /customers` **Input Parameters:** * `limit` (integer): Number of records to return * `after` / `before` (string): Pagination cursors * `company_name` (string): Filter by name * `created_at_start` / `created_at_end` (string): Filter by created date List endpoints use cursor pagination. Pass `limit` and the `end_cursor` from the previous page as `after` (or `start_cursor` as `before`) to move between pages. **Request:** ```bash curl -X GET "https://public-api.alternativepayments.io/customers?limit=10" \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "data": [ { "id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "name": "Acme Inc.", "email": "billing@acme.com", "external_id": "acme-001", "created_at": "2024-01-01T12:00:00Z" } ], "has_next_page": false, "has_previous_page": false, "start_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH", "end_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH" } ``` ### Create Customer **Description**\ Creates a new customer in your account. **Method & Path**\ `POST /customers` **Input Parameters:** * `name` (string, required): Customer or company name * `email` (string, required): Billing contact email * `external_id` (string, optional): Your internal reference ID * `legal_name`, `ein`, `street_address`, `sub_premise`, `city`, `state`, `postal_code`, `country` (string, optional): Company details * `tag_ids` (array of strings, optional): IDs of your custom tags to apply to the new customer. See Customer Tags below. **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/customers \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Inc.", "email": "billing@acme.com", "external_id": "acme-001", "tag_ids": ["3f1c2b7e-8a4d-4c1e-9b2f-6d5a7e8c9f01"] }' ``` **Response:** `201 Created` ```json { "id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "name": "Acme Inc.", "email": "billing@acme.com", "external_id": "acme-001", "tag_ids": ["3f1c2b7e-8a4d-4c1e-9b2f-6d5a7e8c9f01"], "created_at": "2024-01-01T12:00:00Z" } ``` {% hint style="info" %} Every tag is checked before the customer is created. An unknown tag, or a tag owned by another partner, returns `422 TAG_NOT_FOUND` (the tag endpoints return `404` with the same code, because there the tag is the resource in the path; branch on `code`, not the status). A system tag returns `422 SYSTEM_TAG_NOT_MUTABLE`. In both cases no customer is created. Tags are applied in the same step as the customer is created: either the customer is created with all requested tags, or nothing is created. If a tag is deleted while the request is in flight, the API returns `422 TAG_NOT_FOUND` and no customer is created, so it is safe to fix the tag list and send the request again. You can send up to 100 distinct tag IDs. {% endhint %} ### Retrieve Customer **Description**\ Fetches details of a single customer. `email` is the customer's primary (earliest-created) user. **Method & Path**\ `GET /customers/{id}` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/customers/8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81 \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "name": "Acme Inc.", "email": "billing@acme.com", "external_id": "acme-001", "city": "New York", "state": "NY", "created_at": "2024-01-01T12:00:00Z" } ``` ### Update Customer **Description**\ Updates company details on a customer. Only the fields you send are changed. **Method & Path**\ `PATCH /customers/{id}` **Input Parameters:** * `name`, `legal_name`, `ein`, `street_address`, `sub_premise`, `city`, `state`, `postal_code`, `country` (string, optional) {% hint style="warning" %} `email` and `external_id` can't be changed with this endpoint. Sending either one with a different value from the stored value returns `400`. Sending the current value (email comparison ignores case and surrounding spaces) is accepted. To add a contact, use [Add User to Customer](#add-user-to-customer). {% endhint %} **Request:** ```bash curl -X PATCH https://public-api.alternativepayments.io/customers/8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81 \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "city": "New York", "state": "NY" }' ``` **Response:** the updated customer, in the same shape as [Retrieve Customer](#retrieve-customer). ### Archive Customer **Description**\ Soft-deletes (archives) a customer from your list. **Method & Path**\ `DELETE /customers/{id}` **Request:** ```bash curl -X DELETE https://public-api.alternativepayments.io/customers/8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81 \ -H "Authorization: Bearer $TOKEN" ``` ### List Customer Users **Description**\ Retrieves a paginated list of users linked to a customer account. **Method & Path**\ `GET /customers/{id}/users` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/customers/8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81/users \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "data": [ { "id": "c20ad4d7-6fe9-4759-aa27-0c5f4e3d2b96", "email": "jane@acme.com", "first_name": "Jane", "last_name": "Doe", "created_at": "2024-01-02T10:00:00Z" } ], "has_next_page": false, "has_previous_page": false, "start_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH", "end_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH" } ``` ### Add User to Customer **Description**\ Adds a new user under the given customer. **Method & Path**\ `POST /customers/{id}/users` **Input Parameters:** * `email` (string) * `first_name` (string) * `last_name` (string) **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/customers/8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81/users \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "jane@acme.com", "first_name": "Jane", "last_name": "Doe" }' ``` **Response:** `201 Created` ```json { "id": "c20ad4d7-6fe9-4759-aa27-0c5f4e3d2b96", "email": "jane@acme.com", "first_name": "Jane", "last_name": "Doe", "created_at": "2024-01-02T10:00:00Z" } ``` ## ๐Ÿท๏ธ Customer Tags Tags group customers, for example by region or service tier. Partners create **custom** tags. **System** tags (such as autopay status) are managed by Alternative Payments: you can see them but can't apply, edit or delete them. Reading tags requires the `tags:read` scope. Creating, changing, deleting and applying tags requires `tags:write`, including sending `tag_ids` on Create Customer (which also needs `customers:write`). API keys created without any scopes can't use the tag endpoints. {% hint style="warning" %} **Existing API keys need replacing to use tags.** Keys created before tags launched don't have `tags:read` or `tags:write`, and a key's scopes can't be changed after it's created. To use tags, create a new API key with the tag scopes you need and rotate your integration to it. A key with `customers:write` but not `tags:write` that sends a non-empty `tag_ids` on Create Customer now gets `403`. Previously the field was ignored. Leave `tag_ids` out, or use a key with both scopes. {% endhint %} Customer responses include `tag_ids`. To filter customers by tag, use `GET /customers?tag_ids=,` (repeated keys such as `?tag_ids=&tag_ids=` also work). It returns customers that have any of the tags, and accepts up to 100 distinct tag IDs. Tag changes send a `customer_updated` webhook that includes the customer's current `tag_ids`. ### List Tags **Description**\ Lists your custom tags and the system tags. **Method & Path**\ `GET /tags` **Query Parameters:** * `name` (string, optional): Filter by tag name * `customer_id` (string, optional): Only return tags applied to this customer * `limit`, `after`, `before` (optional): Cursor pagination, as on the other list endpoints **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/tags \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "data": [ { "id": "3f1c2b7e-8a4d-4c1e-9b2f-6d5a7e8c9f01", "partner_id": "8d2e4f60-1a3b-4c5d-8e9f-0a1b2c3d4e5f", "name": "Enterprise", "description": "Managed enterprise accounts", "color": "purple", "type": "CUSTOM", "customer_count": 12 } ], "has_next_page": false, "has_previous_page": false, "start_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH", "end_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH" } ``` ### Create Tag **Description**\ Creates a custom tag. Use `GET /tags/{id}`, `PUT /tags/{id}` and `DELETE /tags/{id}` to read, update or delete it. `PUT` requires `name`, `description` and `color`. **Method & Path**\ `POST /tags` **Input Parameters:** * `name` (string, required) * `color` (string, required): One of `aqua_blue`, `dark_grey`, `grey`, `green`, `red`, `orange`, `yellow`, `purple` * `description` (string, optional) **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/tags \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Enterprise", "description": "Managed enterprise accounts", "color": "purple" }' ``` ### Tag a Customer **Description**\ Applies a tag to an existing customer. Returns `204 No Content`. Applying a tag the customer already has also returns `204`. **Method & Path**\ `POST /customers/{id}/tags` **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/customers/9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f/tags \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tag_id": "3f1c2b7e-8a4d-4c1e-9b2f-6d5a7e8c9f01" }' ``` ### Remove a Tag from a Customer **Method & Path**\ `DELETE /customers/{id}/tags/{tag_id}` **Request:** ```bash curl -X DELETE https://public-api.alternativepayments.io/customers/9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f/tags/3f1c2b7e-8a4d-4c1e-9b2f-6d5a7e8c9f01 \ -H "Authorization: Bearer $TOKEN" ``` ### Tag Customers in Bulk **Description**\ Adds or removes one tag across many customers. Returns `200` even if some customers fail. Each customer is listed under `applied`, `skipped` (`already_tagged`, `not_tagged`) or `failed` (`customer_archived`, `customer_not_found`). `customer_ids` accepts up to 200 distinct IDs; duplicates are ignored. **Method & Path**\ `POST /customers/tags/batch` **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/customers/tags/batch \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "operation": "add", "tag_id": "3f1c2b7e-8a4d-4c1e-9b2f-6d5a7e8c9f01", "customer_ids": ["9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f", "b7e4a1c2-5d3f-4e6a-9b8c-1d2e3f4a5b6c"] }' ``` **Response:** ```json { "applied": ["9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f"], "skipped": [{ "customer_id": "b7e4a1c2-5d3f-4e6a-9b8c-1d2e3f4a5b6c", "reason": "already_tagged" }], "failed": [] } ``` ## ๐Ÿงพ Invoices ### List Invoices **Description**\ Returns a paginated list of invoices, filtered by status, customer, or date. **Method & Path**\ `GET /invoices` **Input Parameters:** * `status`: `UPCOMING`, `OVERDUE`, `RECEIVED`, `PAID`, or `ARCHIVED` * `created_at_start` / `created_at_end`, `due_date_start` / `due_date_end` * `customer_id`, `invoice_number` * `limit`, `after`, `before` **Request:** ```bash curl -X GET "https://public-api.alternativepayments.io/invoices?status=PAID" \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "data": [ { "id": "c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52", "invoice_number": "INV-0001", "customer_id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "status": "PAID", "currency": "USD", "due_date": "2025-09-01", "sub_total": 0, "total": 1500, "line_items": [ { "description": "August MSP Fee", "amount": 1500, "quantity": 1 } ], "created_at": "2025-08-01T12:00:00Z" } ], "has_next_page": false, "has_previous_page": false, "start_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH", "end_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH" } ``` `total` is the invoice amount and `sub_total` is the balance still outstanding, both in dollars. ### Create Invoice **Description**\ Creates an invoice with line items. **Method & Path**\ `POST /invoices` **Input Parameters:** * `customer_id` * `currency` (optional): only `USD` is supported, in any letter case. Other currencies return `400` * `due_date` (optional, `YYYY-MM-DD`) * `line_items[]` with `description`, `amount` (per item), `quantity` There is no invoice `memo` input. Requests that include `memo` return `400`. {% hint style="info" %} Amounts are in **dollars**, not cents. `"amount": 1500` is a $1,500.00 line item. {% endhint %} **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/invoices \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "currency": "USD", "due_date": "2025-09-01", "line_items": [ { "description": "August MSP Fee", "amount": 1500, "quantity": 1 } ] }' ``` **Response:** `201 Created` ```json { "id": "c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52", "invoice_number": "INV-0001", "customer_id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "status": "UPCOMING", "currency": "USD", "due_date": "2025-09-01", "sub_total": 1500, "total": 1500, "line_items": [ { "description": "August MSP Fee", "amount": 1500, "quantity": 1 } ], "created_at": "2025-08-01T12:00:00Z" } ``` ### Retrieve Invoice **Description**\ Returns full details for a specific invoice. **Method & Path**\ `GET /invoices/{id}` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/invoices/c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52 \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "id": "c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52", "invoice_number": "INV-0001", "customer_id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "status": "PAID", "currency": "USD", "due_date": "2025-09-01", "sub_total": 0, "total": 1500, "line_items": [ { "description": "August MSP Fee", "amount": 1500, "quantity": 1 } ], "created_at": "2025-08-01T12:00:00Z" } ``` ### Archive Invoice **Description**\ Soft-deletes an invoice. **Method & Path**\ `DELETE /invoices/{id}` **Request:** ```bash curl -X DELETE https://public-api.alternativepayments.io/invoices/c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52 \ -H "Authorization: Bearer $TOKEN" ``` ### Get Invoice Payment Link **Description**\ Generates a hosted payment link for an invoice. **Method & Path**\ `GET /invoices/{id}/payment-link` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/invoices/c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52/payment-link \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "url": "https://your-company.alternativepayments.io/c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52" } ``` ### Get Invoice PDF **Description**\ Returns a link to the invoice download page on your payments portal. **Method & Path**\ `GET /invoices/{id}/pdf-link` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/invoices/c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52/pdf-link \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "url": "https://your-company.alternativepayments.io/c9f0f895-fb98-4b91-9c3e-2a1b0c7d6e52/download" } ``` *** ## ๐Ÿ’ต Payment Request ### Create Payment Request **Description**\ Creates a payment request (not tied to invoice). **Method & Path**\ `POST /payments/request` **Input Parameters:** * `amount` (dollars, as a string: `"50.00"` is $50.00), `redirect_url`, `reference_id` * `currency` (optional): only `USD` is supported, in any letter case. Other currencies return `400` **Request:** ```bash curl -X POST https://public-api.alternativepayments.io/payments/request \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "amount": "50.00", "currency": "USD", "redirect_url": "https://yourapp.com/success", "reference_id": "quote-987" }' ``` **Response:** ```json { "id": "45c48cce-2e2d-4fbd-8a6c-1d2e3f4a5b63", "url": "https://your-company.alternativepayments.io/payment-request/45c48cce-2e2d-4fbd-8a6c-1d2e3f4a5b63", "status": "pending", "reference_id": "quote-987", "redirect_url": "https://yourapp.com/success" } ``` ### Get Payment Request by ID **Description**\ Returns details for a payment request. `status` is `pending`, `processing`, or `succeeded`. **Method & Path**\ `GET /payments/request/{id}` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/payments/request/45c48cce-2e2d-4fbd-8a6c-1d2e3f4a5b63 \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "id": "45c48cce-2e2d-4fbd-8a6c-1d2e3f4a5b63", "url": "https://your-company.alternativepayments.io/payment-request/45c48cce-2e2d-4fbd-8a6c-1d2e3f4a5b63", "status": "succeeded", "reference_id": "quote-987", "redirect_url": "https://yourapp.com/success" } ``` If your payments portal URL can't be resolved, `url` is an empty string and the rest of the response is unchanged. *** ## ๐Ÿ’ณ Transactions ### List Transactions **Description**\ Returns a paginated list of payments, filtered by the parameters below. **Method & Path**\ `GET /payments` **Input Parameters:** * `status`: `creating`, `processing`, `scheduled`, `succeeded`, `canceled`, `failed`, or `pending` * `type`: `payment`, `refund`, or `chargeback` * `payment_method`: `card`, `standard_ach`, `same_day_ach`, or `manual` * `invoice_id`, `customer_id`, `created_at_start` / `created_at_end` * `limit`, `after`, `before` **Request:** ```bash curl -X GET "https://public-api.alternativepayments.io/payments?status=succeeded&payment_method=standard_ach" \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "data": [ { "id": "d3d94468-02a4-4c1b-b5e7-9f8a7b6c5d74", "customer_id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "status": "succeeded", "payment_method": "standard_ach", "total": 50, "sub_total": 50, "due_date": "2024-01-03", "created_at": "2024-01-03T08:30:00Z" } ], "has_next_page": false, "has_previous_page": false, "start_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH", "end_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH" } ``` `total` is the payment amount and `sub_total` is the net amount, both in dollars. Payments with fees also include a `fees` array. *** ## ๐Ÿ’ธ Payouts ### List Payouts **Description**\ Returns a paginated list of payouts. **Method & Path**\ `GET /payouts` **Input Parameters:** * `status`, `customer_id`, `invoice_id`, `start_date` / `end_date` * `limit`, `after`, `before` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/payouts \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "data": [ { "id": "6512bd43-d9ca-4a6e-8b1f-0e9d8c7b6a85", "customer_id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "status": "succeeded", "total": 1000, "sub_total": 990, "fees": [ { "name": "Processing fee", "type": "method", "amount": 10, "covered_by_customer": false } ], "arrival_date": "2024-01-12", "created_at": "2024-01-10T15:00:00Z" } ], "has_next_page": false, "has_previous_page": false, "start_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH", "end_cursor": "gaFpxBACEaXBVABEYbHG+X9LyLnH" } ``` `total` is the gross payout and `sub_total` is the net amount after fees, both in dollars. ### Get Payout by ID **Description**\ Returns details for a single payout. **Method & Path**\ `GET /payouts/{id}` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/payouts/6512bd43-d9ca-4a6e-8b1f-0e9d8c7b6a85 \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "id": "6512bd43-d9ca-4a6e-8b1f-0e9d8c7b6a85", "customer_id": "8f14e45f-ceea-4e67-a1b2-3c4d5e6f7a81", "status": "succeeded", "total": 1000, "sub_total": 990, "fees": [ { "name": "Processing fee", "type": "method", "amount": 10, "covered_by_customer": false } ], "arrival_date": "2024-01-12", "created_at": "2024-01-10T15:00:00Z" } ``` ### List Payout Transactions **Description**\ Returns the payout and the transactions included in it. **Method & Path**\ `GET /payouts/{id}/transactions` **Request:** ```bash curl -X GET https://public-api.alternativepayments.io/payouts/6512bd43-d9ca-4a6e-8b1f-0e9d8c7b6a85/transactions \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "payout": { "id": "6512bd43-d9ca-4a6e-8b1f-0e9d8c7b6a85", "status": "succeeded", "total": 1000, "sub_total": 990 }, "transactions": [ { "id": "d3d94468-02a4-4c1b-b5e7-9f8a7b6c5d74", "description": "Invoice INV-0001", "status": "succeeded", "direction": "credit", "method": "standard_ach", "total": 1000, "sub_total": 990 } ] } ``` *** ## :warning:Error Handling API errors return standard HTTP status codes plus a JSON body: ```json {โ€‹ "code": "text",โ€‹ "message": "text"โ€‹ } ```
CodeWhen it happens
400Malformed JSON or missing required field
400Missing Authorization header (gateway returns {"error": "Authorization field missing"})
401Expired token
403Invalid token (gateway returns {"error": "Key not authorised"}) or token lacks the required scope
404Object not found
422Semantic validation error on some endpoints (e.g., uploading a PDF for an API-created invoice). Unsupported currency and negative amounts return 400
429Rate limit exceeded.
500Unexpected server error; retry later
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.alternativepayments.io/getting-started/quick-start/guides.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.