> 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 <access_token>
```

**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` (string): Cursor for pagination
* `company_name` (string): Filter by name
* `created_at` (range): Filter by created date

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/customers \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "data": [
    {
      "id": "cus_123",
      "name": "Acme Inc.",
      "email": "billing@acme.com",
      "created_at": "2024-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "has_next_page": false,
    "end_cursor": null
  }
}
```

### 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

**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"
  }'
```

**Response:**

```json
{
  "id": "cus_123",
  "name": "Acme Inc.",
  "email": "billing@acme.com",
  "external_id": "acme-001",
  "created_at": "2024-01-01T12:00:00Z"
}
```

### Retrieve Customer

**Description**\
Fetches details of a single customer.

**Method & Path**\
`GET /customers/{id}`

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/customers/cus_123 \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "id": "cus_123",
  "name": "Acme Inc.",
  "email": "billing@acme.com",
  "created_at": "2024-01-01T12:00:00Z"
}
```

### 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/cus_123 \
  -H "Authorization: Bearer $TOKEN"
```

### List Customer Users

**Description**\
Retrieves users linked to a customer account.

**Method & Path**\
`GET /customers/{id}/users`

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/customers/cus_123/users \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
[
  {
    "id": "user_001",
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "created_at": "2024-01-02T10:00:00Z"
  }
]
```

### 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/cus_123/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }'
```

**Response:**

```json
{
  "id": "user_001",
  "email": "jane@acme.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "created_at": "2024-01-02T10:00:00Z"
}
```

## 🧾 Invoices

### List Invoices

**Description**\
Returns all invoices filtered by status, customer, or date.

**Method & Path**\
`GET /invoices`

**Input Parameters:**

* `status` (e.g., PAID, OVERDUE)
* `created_at`, `due_date` ranges
* `customer_id`

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/invoices?status=PAID \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "data": [
    {
      "id": "inv_123",
      "customer_id": "cus_123",
      "status": "PAID",
      "amount": 150000,
      "currency": "USD",
      "due_date": "2025-09-01"
    }
  ]
}
```

### Create Invoice

**Description**\
Creates an invoice with line items.

**Method & Path**\
`POST /invoices`

**Input Parameters:**

* `customer_id`
* `currency`
* `due_date`
* `line_items[]` with `description`, `amount`, `quantity`

**Request:**

```bash
curl -X POST https://public-api.alternativepayments.io/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "currency": "USD",
    "due_date": "2025-09-01",
    "line_items": [
      {
        "description": "August MSP Fee",
        "amount": 150000,
        "quantity": 1
      }
    ]
  }'
```

**Response:**

```json
{
  "id": "inv_123",
  "status": "OPEN",
  "customer_id": "cus_123",
  "amount": 150000,
  "currency": "USD",
  "due_date": "2025-09-01"
}
```

### 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/inv_123 \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "id": "inv_123",
  "customer_id": "cus_123",
  "status": "PAID",
  "amount": 150000,
  "due_date": "2025-09-01",
  "currency": "USD"
}
```

### Archive Invoice

**Description**\
Soft-deletes an invoice.

**Method & Path**\
`DELETE /invoices/{id}`

**Request:**

```bash
curl -X DELETE https://public-api.alternativepayments.io/invoices/inv_123 \
  -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/inv_123/payment-link \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "url": "https://checkout.alternativepayments.io/pay/inv_123"
}
```

### Get Invoice PDF

**Description**\
Generates a signed URL to download invoice PDF.

**Method & Path**\
`GET /invoices/{id}/pdf-link`

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/invoices/inv_123/pdf-link \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "url": "https://cdn.ap.com/invoices/inv_123.pdf"
}
```

***

## 💵 Payment Request

### Create Payment Request

**Description**\
Creates a payment request (not tied to invoice).

**Method & Path**\
`POST /payments/request`

**Input Parameters:**

* `amount`, `currency`, `redirect_url`, `reference_id`

**Request:**

```bash
curl -X POST https://public-api.alternativepayments.io/payments/request \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5000",
    "currency": "USD",
    "redirect_url": "https://yourapp.com/success",
    "reference_id": "quote-987"
  }'
```

**Response:**

```json
{
  "id": "preq_123",
  "url": "https://checkout.alternativepayments.io/pay/preq_123",
  "status": "PENDING"
}
```

### Get Payment Request by ID

**Description**\
Returns details for a payment request.

**Method & Path**\
`GET /payments/request/{id}`

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/payments/request/preq_123 \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "id": "preq_123",
  "amount": 5000,
  "currency": "USD",
  "status": "PAID",
  "reference_id": "quote-987"
}
```

***

## 💳 Transactions

### List Transactions

**Description**\
Fetches transactions by filters.

**Method & Path**\
`GET /payments`

**Input Parameters:**

* `status`, `type`, `payment_method`, `invoice_id`, `customer_id`

**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": "txn_001",
      "amount": 5000,
      "currency": "USD",
      "status": "succeeded",
      "payment_method": "standard_ach",
      "created_at": "2024-01-03T08:30:00Z"
    }
  ]
}
```

***

## 💸 Payouts

### List Payouts

**Description**\
Returns list of payout batches.

**Method & Path**\
`GET /payouts`

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/payouts \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "data": [
    {
      "id": "pout_123",
      "status": "succeeded",
      "amount": 100000,
      "currency": "USD",
      "created_at": "2024-01-10T15:00:00Z"
    }
  ]
}
```

### 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/pout_123 \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "id": "pout_123",
  "status": "succeeded",
  "currency": "USD",
  "amount": 100000,
  "created_at": "2024-01-10T15:00:00Z"
}
```

### List Payout Transactions

**Description**\
Returns all transactions for a specific payout.

**Method & Path**\
`GET /payouts/{id}/transactions`

**Request:**

```bash
curl -X GET https://public-api.alternativepayments.io/payouts/pout_123/transactions \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
{
  "transactions": [
    {
      "id": "txn_001",
      "status": "succeeded",
      "amount": 5000,
      "currency": "USD",
      "type": "payment",
      "direction": "inbound"
    }
  ]
}
```

***

## :warning:Error Handling

All errors return standard HTTP status codes plus a JSON body:

```json
{​
  "code": "text",​
  "message": "text"​
}
```

<table><thead><tr><th width="104.99993896484375">Code</th><th>When it happens</th></tr></thead><tbody><tr><td><code>400</code></td><td>Malformed JSON or missing required field</td></tr><tr><td><code>401</code></td><td>Missing or invalid token</td></tr><tr><td><code>403</code></td><td>Token is valid but lacks permission (rare)</td></tr><tr><td><code>404</code></td><td>Object not found</td></tr><tr><td><code>422</code></td><td>Semantic validation error (e.g., unsupported currency)</td></tr><tr><td><code>429</code></td><td>Rate limit exceeded.</td></tr><tr><td><code>500</code></td><td>Unexpected server error; retry later</td></tr></tbody></table>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alternativepayments.io/getting-started/quick-start/guides.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.