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

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

The question should be specific, self-contained, and written in natural language.
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.