# Introduction

## 👋 Welcome to the Alternative Payments API

The Alternative Payments API lets you create and manage customers, issue invoices, collect payments, track transactions, and reconcile payouts, all through secure, RESTful endpoints. It’s designed for partners, MSPs, and platforms that want to integrate billing and payment operations directly into their own systems.

***

## 🔧 What you can do with the API ?

Use the Alternative Payments API to create and manage customers and invoices, generate one-time payment links, track transactions, and reconcile payouts. It follows a simple OAuth 2.0 client-credentials flow and returns JSON over HTTPS.

* **One-off checkout experiences.** Create a Payment Request, share the hosted link, redirect users back to your app, and poll for status. [Payment Request](https://github.com/getalternative/docs/blob/main/api/broken-reference/README.md)
* **Invoice-based payments.** Create invoices with line items, fetch a hosted payment link for the invoice, and download a signed PDF URL. [Invoices](https://github.com/getalternative/docs/blob/main/api/broken-reference/README.md)
* **Customer management.** Create customers, list and fetch them, archive when needed, list payment methods, and manage customer users. [Customers](https://github.com/getalternative/docs/blob/main/api/broken-reference/README.md)
* **Transaction history.** List payments with filters like type, status, customer, invoice, and method. [Transactions](https://github.com/getalternative/docs/blob/main/api/broken-reference/README.md)
* **Payout reconciliation.** List payouts, fetch a payout by ID, and retrieve the transactions that rolled into a payout. [Payouts](https://github.com/getalternative/docs/blob/main/api/broken-reference/README.md)

***

## :question:How does it work?

* **Protocol:** REST over HTTPS
* **Format:** JSON requests and responses
* **Auth:** OAuth 2.0 client credentials flow using API keys

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>### <mark style="color:$primary;">Authentication</mark></p></div>

1. Generate an [API key in the Partner Dashboard](/getting-started/quick-start/api-keys).
2. Exchange it for an access token using the `client_credentials` grant.
3. Include `Authorization: Bearer <token>` in every request.\
   Tokens expire as indicated by `expires_in` and are scoped per environment.

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>### Pagination &#x26; filters</p></div>

Most list endpoints use **cursor-based pagination** with `after`, `before`, `start_cursor`, and `end_cursor`. Filters vary by endpoint (status, date, type, customer ID, etc.).

{% hint style="warning" %}
\### Errors & limits

* Standard HTTP status codes with JSON error objects
* Rate limit: **5 requests/sec** per API key
* Handle 429s with exponential backoff
  {% endhint %}

***


# Quick Start

## :sparkles:Step by step

Follow these steps and you will have a working payment link in minutes:

{% stepper %}
{% step %}
\### Generate an API Key

Log in to the Partner Dashboard and go to **Team Preferences > API Keys**. Create a new key to identify your integration.

[<mark style="background-color:purple;">API Key</mark>](/getting-started/quick-start/api-keys)
{% endstep %}

{% step %}
\### Authenticate via OAuth 2.0

Use the API Key to obtain an access token using the **client credentials** grant type.

[<mark style="background-color:purple;">OAuth Authentication</mark>](https://github.com/getalternative/docs/blob/main/api/getting-started/quick-start/broken-reference/README.md)
{% endstep %}

{% step %}
\### **Create a payment request**

Use your access token to create a new payment request with the desired amount, currency, and redirect URL.

[<mark style="background-color:purple;">Create a payment request</mark>](https://github.com/getalternative/docs/blob/main/api/getting-started/quick-start/broken-reference/README.md)
{% endstep %}

{% step %}
\### **Check payment status**

Poll the API to retrieve the current status of the payment.

[<mark style="background-color:purple;">Retrieve a Payment Request</mark>](https://github.com/getalternative/docs/blob/main/api/getting-started/quick-start/broken-reference/README.md)
{% endstep %}
{% endstepper %}

\*\*\*

## 🧰 Environments & Base URLs

<table><thead><tr><th width="241">Environment</th><th>Base URL</th></tr></thead><tbody><tr><td>Production (default)</td><td><code>https://public-api.alternativepayments.io</code></td></tr><tr><td>Demo</td><td><code>https://public-api.demo.alternativepayments.io</code></td></tr></tbody></table>

All examples in this guide use production URLs. Switch to the demo when you test. Tokens and requests are isolated per environment.

{% hint style="danger" %}
\#### Caution

Tokens issued in one environment do **NOT** work in the other. Generate separate client credentials for demo and production.
{% endhint %}

{% hint style="warning" %}
\#### API Versioning

The current stable version is **v1**. Backward‑compatible changes (new fields, new statuses) are rolled out without a version bump. Breaking changes, if ever needed, will ship under `/v2`.
{% endhint %}

####


# API Keys

Before making any API calls, you'll need to generate an API key and exchange it for an access token. Here's how:

## 🔑 Generate Your API Key

1. Log into the Partner Dashboard.
2. Go to **Team Preferences → API Keys**.
3. Click **Generate API Key**.
4. Give it a descriptive name (e.g. "Quoting Tool - Production").
5. Use the **scope picker** to select only the permissions this key needs — or click **Select all** for full access.
6. Copy and store the key somewhere safe. This key authenticates your API requests and should be kept secure.

{% embed url="<https://app.arcade.software/share/wgP3Hah7Ed6oup9p5K9v>" %}
Generating an API Key on Partner Dashboard
{% endembed %}

> Treat this key like a password. Do not expose it in client-side code or share it publicly.

### Scoped API Keys

API keys can now be created with only the permissions they need. Limiting scope reduces the blast radius if a credential is ever leaked or misused.

#### Available Scopes

Each scope area supports **read**, **write**, or both, where applicable:

| Scope Area      | Read | Write |
| --------------- | ---- | ----- |
| Invoices        | ✓    | ✓     |
| Payments        | ✓    | ✓     |
| Customers       | ✓    | ✓     |
| Refunds         | ✓    | ✓     |
| Payouts         | ✓    | ✓     |
| Webhooks        | ✓    | ✓     |
| Hosted Checkout | ✓    | ✓     |

#### Scope Picker UI

When you click **Generate API Key**, the dialog includes a scope picker organized by capability area. Select individual read or write permissions for each area, or use the **Select all** shortcut when you need full access.

#### Existing Keys — "Full Access" Label

Every key minted before scoped keys were introduced is automatically labeled **Full access**, so you can spot the highest-blast-radius keys at a glance. There is no forced rotation — migrate those keys to narrower scopes on your own timeline.

#### Inline Scope Auditing

The **API Keys** list shows each key's scopes inline, so you can audit what each integration is allowed to do without opening individual key details.

#### Scopes in the OpenAPI Spec

All scopes are published in the public OpenAPI spec as a scopes catalog, with per-route scope tags — ready for code generators and API clients.

### Example Use Cases

Assign the minimum permissions each integration actually needs:

* **Accountant access** — `Customers: read` + `Invoices: read`
* **Reconciliation tool** — `Payments: read`
* **Refunds operator** — `Refunds: write`

***

## 🗑️ Revoke an API Key

If a key is no longer needed or may be compromised, go to **API Keys** in the dashboard, click **Revoke** next to the key you want to disable, and confirm the action.

> **Important:** Revoking a key is permanent. Make sure your application is updated with a new key before revoking the old one.

## ✏️ Rename an API Key

To update the name of an existing key, go to **API Keys** in the dashboard, click **Edit Key Name** next to the key, enter a new name, and save.

Renaming helps you keep keys organized by usage or environment.


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


# Webhooks

## Overview

Webhooks allow you to receive real-time notifications when events occur in your Alternative Payments account. Instead of continuously polling the API to check for updates, webhooks push event data directly to your server as they happen.

## Available Webhook Topics

Subscribe to the following webhook topics to receive notifications:

| Topic                            | Description                                                                                                                          |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `payout_paid`                    | Confirms that a payout was successfully settled.                                                                                     |
| `payout_processing`              | Indicates the payout has started to be processed                                                                                     |
| `payout_scheduled`               | Indicates the payout is scheduled to be processed                                                                                    |
| `payout_failed`                  | Indicates a failed payout attempt.                                                                                                   |
| `customer_created`               | Triggered when a new customer is onboarded.                                                                                          |
| `customer_updated`               | Triggered when the customer has their information updated.                                                                           |
| `customer_archived`              | Triggered when a customer is archived.                                                                                               |
| `payment_succeeded`              | Confirms that funds were successfully captured.                                                                                      |
| `payment_refunded`               | Triggered when a payment refund request occurs.                                                                                      |
| `payment_chargeback`             | Notifies when a dispute occurs. Impacts reconciliation and may require intervention.                                                 |
| `payment_failed`                 | Indicates a failed payment attempt.                                                                                                  |
| `invoice_created`                | Triggered when a new invoice is created.                                                                                             |
| `invoice_updated`                | Triggered when invoice information is updated.                                                                                       |
| `invoice_paid`                   | Confirms the invoice has been fully paid. Closes the accounts receivable lifecycle and links the payment to the customer obligation. |
| `invoice_archived`               | Triggered when the invoice is archived.                                                                                              |
| `payment_method_added`           | Indicates a payment method was added. Useful for enabling Autopay.                                                                   |
| `default_payment_method_changed` | Triggered when the customer default payment method change.                                                                           |
| `payment_method_deleted`         | Indicates a payment method was removed. Also relevant for managing Autopay.                                                          |

## Managing Webhook Subscriptions

### Subscribe to a Webhook

Create a new webhook subscription to start receiving event notifications.

**Endpoint:** `POST /webhooks`

**Request Body:**

```json
{
  "endpoint_url": "https://your-server.com/webhooks",
  "secret_key": "your_secret_key",
  "topic": "invoice_paid"
}
```

**Parameters:**

* `endpoint_url` (required) - Your HTTPS endpoint that will receive webhook events
* `secret_key` (optional) - A secret key for authentication. If provided, it will be sent as a Bearer token in the `Authorization` header
* `topic` (required) - The event type you want to subscribe to (see available topics above)

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Authentication:</strong> If you provide a <code>secret_key</code>, all webhook requests to your endpoint will include it in the <code>Authorization</code> header as a Bearer token. Use this to verify the authenticity of webhook requests.</p></div>

  \### List Webhook Subscriptions

View all your active and inactive webhook subscriptions.

**Endpoint:** `GET /webhooks`

**Query Parameters:**

* `limit` (optional, default: 100) - Number of items to return
* `after` (optional) - Cursor for forward pagination
* `before` (optional) - Cursor for backward pagination
* `topic` (optional) - Filter by webhook topic
* `is_active` (optional) - Filter by active status (true/false)

### Unsubscribe from a Webhook

Remove a webhook subscription when you no longer want to receive notifications.

**Endpoint:** `DELETE /webhooks/{subscription_id}`

**Parameters:**

* `subscription_id` (required) - The ID of the subscription to remove

## Webhook Events

### List Webhook Events

View the history of webhook events sent to your endpoints.

**Endpoint:** `GET /webhooks/events`

**Query Parameters:**

* `limit` (optional, default: 100) - Number of items to return
* `after` (optional) - Cursor for forward pagination
* `before` (optional) - Cursor for backward pagination
* `topic` (optional) - Filter by webhook topic
* `status` (optional) - Filter by status: `pending`, `sent`, or `failed`
* `from_date` (optional) - Filter events created after this date (ISO 8601)
* `to_date` (optional) - Filter events created before this date (ISO 8601)

## Webhook Payload Structure

All webhooks are sent as HTTP POST requests with a JSON payload containing the following fields:

```json
{
  "entity_id": "5cbcf9c3-9378-4633-91f0-886fa172f360",
  "idempotency_key": "066a3fd0-b849-494f-87ba-d186a6e4b2cc",
  "timestamp": "2025-09-29T21:01:36Z",
  "topic": "invoice_paid",
  "data": {
    "customer_id": "170d05e3-b498-4547-af7c-985f1e85d9f7",
    "invoice_id": "5cbcf9c3-9378-4633-91f0-886fa172f360",
    "status": "paid"
  }
}
```

### Payload Fields

* **`entity_id`** - The ID of the primary resource related to this event
  * For `invoice_paid` → Invoice ID
  * For `payment_method_added` → Payment Method ID
  * For `customer_created` → Customer ID
  * For `payout_paid` → Payout ID
* **`idempotency_key`** - A unique identifier for this webhook event. Use this to prevent processing duplicate webhooks
* **`timestamp`** - ISO 8601 timestamp of when the event occurred
* **`topic`** - The event type (see Available Webhook Topics)
* **`data`** - Additional context about the event. The structure varies by topic but typically includes:
  * Related entity IDs (customer\_id, invoice\_id, etc.)
  * Current status of the resource
  * Other relevant information specific to the event type

    <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p><strong>Important:</strong> The <code>entity_id</code> field always contains the ID of the primary subject of the webhook. Use this field to quickly identify which resource triggered the event, then use the additional fields in <code>data</code> for complete context.</p></div>

    \## Webhook Ordering

Webhooks are delivered **in order**. This means:

* All webhooks for your account are sent sequentially based on when they were created
* A webhook will not be sent until all previous webhooks have been successfully delivered
* This ensures you receive events in the correct chronological order

## Retry Logic

If your endpoint is temporarily unavailable or returns an error, Alternative Payments will automatically retry webhook delivery.

### Retry Behavior

* **Maximum attempts:** 5 retries
* **Backoff strategy:** Exponential backoff with a 30-second base delay
* **Retry intervals:** 1:30m, 4:30m, 13:30m, 40:30m, 2:02hrs (attempts 1-5)

The retry delay is calculated using the formula:

```
delay = 30 seconds × (3 ^ attempt_number)
```

### What Happens After Max Retries

After reaching the maximum number of retry attempts:

1. The webhook delivery is **permanently paused** for your account
2. All pending and failed webhooks remain in queue but won't be automatically retried
3. **You must manually trigger a retry** to resume webhook delivery

### Manually Retrying Failed Webhooks

When webhooks reach max retry attempts, use this endpoint to resume delivery:

**Endpoint:** `POST /webhooks/retry`

**Request:** No body required

**Response:**

```json
{
  "message": "success"
}
```

This endpoint will:

* Reset the retry counter
* Resume processing all pending and failed webhooks in order
* Attempt to deliver webhooks again with the full retry logic

  <div data-gb-custom-block data-tag="hint" data-style="danger" class="hint hint-danger"><p><strong>Critical:</strong> If webhook delivery fails repeatedly, you must fix the underlying issue with your endpoint before manually retrying. Otherwise, webhooks will fail again and enter the same paused state.</p></div>

## Processing Limits

To protect your endpoint from being overwhelmed:

* The retry process sends a maximum of **10 webhooks per run**
* If more than 10 webhooks are pending, they will be processed in subsequent retry cycles
* All webhooks are still delivered in order

## Best Practices

### Endpoint Requirements

* **Use HTTPS** - Webhook endpoints must use HTTPS (not HTTP)
* **Return 2xx status codes** - Your endpoint should return a 200-299 status code to indicate successful receipt
* **Respond quickly** - Process webhooks asynchronously if possible. Acknowledge receipt immediately and process the event in the background
* **Handle timeouts** - Implement proper timeout handling on your server

### Security

1. **Verify webhook authenticity:**
   * Set a `secret_key` when subscribing
   * Validate the `Authorization` header on incoming webhook requests
   * Check that the Bearer token matches your secret
2. **Use idempotency keys:**
   * Store the `idempotency_key` from each webhook
   * Check for duplicate keys before processing to prevent double-processing
3. **Validate payload structure:**
   * Always validate the JSON structure before processing
   * Check that required fields are present
   * Verify the `topic` matches your expected event type

### Error Handling

* **Return proper status codes:**
  * `200-299`: Successfully received and will process
  * `300-599`: Error (we will retry)
* **Monitor webhook events:**
  * Use `GET /webhooks/events` to monitor delivery status
  * Set up alerts for failed webhooks
  * Check your webhook endpoint logs regularly

### Testing

Before going live:

1. Subscribe to a webhook topic in your staging/test environment
2. Trigger test events (create a customer, pay an invoice, etc.)
3. Verify your endpoint receives and processes the webhooks correctly
4. Test your retry logic by returning error status codes temporarily
5. Confirm your secret key validation works correctly

***

## Example Implementation

Here's a basic example of a webhook endpoint handler:

```typescript
import express, { Request, Response } from "express";
import crypto from "crypto";

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = "your_secret_key";
const processedWebhooks = new Set<string>();

interface WebhookPayload {
  idempotency_key: string;
  topic: "invoice_paid" | "payment_failed" | string;
  entity_id: string;
  data?: Record<string, any>;
}

app.post("/webhooks", (req: Request, res: Response) => {
  // Verify authentication
  const authHeader = req.headers.authorization ?? "";
  if (!authHeader.startsWith("Bearer ")) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  const token = authHeader.replace("Bearer ", "");
  if (token !== WEBHOOK_SECRET) {
    return res.status(401).json({ error: "Invalid token" });
  }

  // Parse webhook payload
  const payload = req.body as WebhookPayload;
  const { idempotency_key, topic, entity_id, data = {} } = payload;

  if (!idempotency_key) {
    return res.status(400).json({ error: "Missing idempotency key" });
  }

  // Check for duplicates
  if (processedWebhooks.has(idempotency_key)) {
    return res.json({ message: "Already processed" });
  }

  // Handle topics
  switch (topic) {
    case "invoice_paid": {
      const invoiceId = entity_id;
      const customerId = data.customer_id;
      console.log(`Invoice ${invoiceId} paid by customer ${customerId}`);
      break;
    }
    case "payment_failed": {
      const paymentId = entity_id;
      console.log(`Payment ${paymentId} failed`);
      break;
    }
    default:
      console.log(`Unhandled topic: ${topic}`);
  }

  // Mark as processed
  processedWebhooks.add(idempotency_key);

  return res.json({ message: "Webhook received" });
});

const PORT = 5000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

```

***

## Troubleshooting

<details>

<summary><strong>My webhooks are not being delivered</strong></summary>

Check the following:

1. Verify your endpoint is publicly accessible via HTTPS
2. Confirm your endpoint returns a 2xx status code
3. Check `GET /webhooks/events` to see webhook status
4. Ensure your subscription is active (`is_active: true`)
5. Verify your server isn't blocking incoming requests

</details>

<details>

<summary><strong>Webhooks stopped after reaching max retries</strong></summary>

1. Fix the issue preventing webhook delivery (check your server logs)
2. Call `POST /webhooks/retry` to resume delivery
3. Monitor the webhook events to confirm successful delivery

</details>

<details>

<summary><strong>Receiving duplicate webhooks</strong></summary>

This can happen during retries. Always:

* Check the `idempotency_key` before processing
* Store processed keys in your database
* Skip processing if the key was already handled

</details>

<details>

<summary><strong>How do I test webhooks locally?</strong></summary>

Use a tool like [ngrok](https://ngrok.com/) to expose your local server:

1. Run `ngrok http 5000` (or your local port)
2. Use the HTTPS URL provided by ngrok as your `endpoint_url`
3. Subscribe to a webhook with the ngrok URL
4. Trigger events in your test environment

</details>

***

For additional help, refer to the FAQ or contact our support team.


# FAQ

## :book:Questions & Answers

Have a question about using the API? This section covers the most common issues, tips, and answers to help you integrate faster and avoid common pitfalls. If you don’t find what you’re looking for here, reach out to our support team.

<details>

<summary><strong>Which OAuth grant type is supported?</strong></summary>

`client_credentials` only. Include `grant_type=client_credentials` in the form data.

</details>

<details>

<summary><strong>Where do I obtain <code>client_id</code> and <code>client_secret</code>?</strong></summary>

Generate them in the Partner Dashboard under **API Keys**.

</details>

<details>

<summary><strong>How long is an <code>access_token</code> valid?</strong></summary>

Exactly the value of `expires_in` returned by the token call—currently **3600 seconds (60 minutes)**.

</details>

<details>

<summary><strong>What is the minimal body for <code>POST /payment/request</code>?</strong></summary>

```
{
  "amount": "100",
  "currency": "USD",
  "redirect_url": "https://yourapp.com/thanks"
}
```

</details>

<details>

<summary><strong>Can I tag requests for internal tracking?</strong></summary>

Yes, pass a `reference_id` string. It is returned unchanged in all responses.

</details>

<details>

<summary><strong>What is the API rate limit?</strong></summary>

The API enforces a rate limit of **5 requests per second per API key**.

If you exceed this limit, you will receive an HTTP 429 “Too Many Requests” response. To avoid hitting the rate limit:

* Space out your requests evenly
* Implement exponential backoff and retry logic when you receive a 429 error
* Monitor your request volume to stay within limits

If your use case requires a higher rate limit, please contact our support team to discuss your integration needs.

</details>

<details>

<summary><strong>How do I confirm payment completion?</strong></summary>

Poll `GET /payment/request/{id}` until `status` equals `paid`.

</details>

<details>

<summary><strong>What statuses can a payment request have?</strong></summary>

`pending`, `paid`, `expired`, or `cancelled`.

</details>

<details>

<summary><strong>What happens if required fields are missing?</strong></summary>

The API returns `400 Bad Request` with details in the `error.message` field.

</details>

<details>

<summary><strong>Does the API support recurring or partial payments?</strong></summary>

No. Each Payment Request is a one‑off charge for a fixed amount.

</details>

***


# Troubleshooting

## :x:Errors

Things don’t always go as planned. This section lists the most common errors you might encounter when using the API, what they mean, and how to resolve them. Use it as a quick reference during development and debugging.

<table><thead><tr><th width="164">HTTP Code</th><th width="219.79998779296875">Endepoint</th><th width="150.5999755859375">Typical Cause</th><th>Quick Check</th></tr></thead><tbody><tr><td><strong>400 Bad Request</strong></td><td><code>POST /payment/request</code></td><td>Missing or malformed JSON; required field omitted</td><td>Ensure body includes <code>amount</code>, <code>currency</code>, and <code>redirect_url</code> exactly as documented</td></tr><tr><td><strong>401 Unauthorized</strong></td><td>Any</td><td>Missing or expired <code>access_token</code></td><td>Call <code>POST /oauth/token</code> again and set <code>Authorization: Bearer &#x3C;token></code></td></tr><tr><td><strong>403 Forbidden</strong></td><td><code>POST /oauth/token</code></td><td>Wrong <code>client_id</code> / <code>client_secret</code> or bad Basic Auth header</td><td>Re‑encode credentials and retry</td></tr><tr><td><strong>404 Not Found</strong></td><td><code>GET /payment/ request/{id}</code></td><td>ID not present in environment</td><td>Confirm the ID and that you are using the correct base URL (sandbox vs. production)</td></tr><tr><td><strong>422 Validation Exception</strong></td><td><code>POST /payment/request</code></td><td>Business‑rule failure (e.g., unsupported currency, negative amount)</td><td>Use a valid ISO 4217 code; amount must be a positive integer</td></tr><tr><td><strong>500 Server Error</strong></td><td>Any</td><td>Unexpected internal condition</td><td>Retry with back‑off; contact support if persistent</td></tr><tr><td><strong>429 Too Many Requests</strong></td><td>Any</td><td>Rate limit exceeded (more than 5 requests per second per API key)</td><td>Slow down requests, implement retry with exponential backoff, and ensure you stay within rate limits</td></tr></tbody></table>

***

## :books:Glossary

The glossary breaks down key concepts, technical terms, and acronyms used throughout the API and dashboard. It’s a handy reference to help you stay on the same page while building your integration.

<table><thead><tr><th width="198.59991455078125">Term</th><th>Definition</th></tr></thead><tbody><tr><td><strong>access_token</strong></td><td>Bearer credential returned by <code>POST /oauth/token</code> used to authorize further requests</td></tr><tr><td><strong>amount</strong></td><td>Smallest currency unit (e.g., <code>"100"</code> = $100 USD)</td></tr><tr><td><strong>client_id / client_secret</strong></td><td>Credentials created in the dashboard; used with Basic Auth to obtain a token</td></tr><tr><td><strong>currency</strong></td><td>Three‑letter code such as <code>USD</code></td></tr><tr><td><strong>grant_type</strong></td><td>OAuth field indicating the authentication flow; always <code>client_credentials</code> here</td></tr><tr><td><strong>Payment Request</strong></td><td>Resource representing a one‑time charge and hosted checkout link</td></tr><tr><td><strong>redirect_url</strong></td><td>HTTPS location where the payer is sent after checkout</td></tr><tr><td><strong>reference_id</strong></td><td>Optional string you supply for internal correlation</td></tr><tr><td><strong>status</strong></td><td>Lifecycle stage of a Payment Request: <code>pending</code>, <code>paid</code>, <code>expired</code>, <code>cancelled</code></td></tr><tr><td><strong>token_type</strong></td><td>Value identifying the auth scheme, always <code>Bearer</code></td></tr><tr><td><strong>UUID</strong></td><td>Universally Unique Identifier used for resource IDs</td></tr></tbody></table>


# 3rd Party Tools


# Rewst

Many MSPs use **Rewst** to automate workflows across PSA tools, billing systems, and third-party platforms. To enable automated invoice payments and customer operations via **Alternative Payments**, you’ll need to authenticate and interact with our API directly through Rewst using HTTP Request blocks.

This guide walks you through how to **authenticate with the Alternative Payments API** inside Rewst, so you can securely trigger additional API calls from your workflows.

<figure><img src="/files/xrDrHPlcFHTSWZunjqCU" alt=""><figcaption></figcaption></figure>

***

## :notebook\_with\_decorative\_cover:How It Works

Rewst supports HTTP requests through its workflow automation engine, allowing you to interact directly with external APIs like Alternative Payments.

To integrate with our API:

* **Authenticate using OAuth 2.0:** This authentication method is used to obtain secure, server-to-server access without user interaction.
* **Obtain an access token:** Upon successful authentication, the API returns an `access_token` that is valid for a limited time.
* **Authorize future requests:** Use this token in the `Authorization` header (`Bearer` format) to securely access other endpoints.
* **Follow standard REST practices:** All API interactions are based on REST conventions, using JSON payloads, HTTP methods, and header-based authentication.

***

## :sparkles:Step-by-Step### :closed\_lock\_with\_key: Step 1: Authenticate using HTTP Request Block

1. In your **Rewst workflow**, click **+** to add a new **HTTP Request** block.
2. Set **Request method** to `POST`.
3. Set **URL** to:

<table><thead><tr><th width="180.22222900390625">Environment</th><th>URL</th></tr></thead><tbody><tr><td><strong>Demo</strong></td><td><code>https://public-api.demo.alternativepayments.io/oauth/token</code></td></tr><tr><td><strong>Production</strong></td><td><code>https://public-api.alternativepayments.io/oauth/token</code></td></tr></tbody></table>

<figure><img src="/files/5npkj9PS8qDVIq0jrBsW" alt=""><figcaption></figcaption></figure>

\
In the **Body** section, use:

```
grant_type=client_credentials
```

<figure><img src="/files/nDN1CsI1HG2MG3jlEuyd" alt=""><figcaption></figcaption></figure>

Set the following **Headers**:

<table><thead><tr><th width="159.77783203125">Header</th><th>Value</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td><code>application/x-www-form-urlencoded</code></td></tr><tr><td><code>Authorization</code></td><td><code>Basic </code><strong><code>your_base64_credentials</code></strong></td></tr></tbody></table>

<figure><img src="/files/2vnJx0Q9OhLzrQvroLEn" alt=""><figcaption></figcaption></figure>

#### :key: Base64 Credentials

To generate the **base64** credentials:

* Format your credentials as `clientId:clientSecret`

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>You can find your <code>clientId</code> and <code>clientSecret</code> in the <strong>Partner Dashboard</strong> under the <a data-mention href="/pages/6sbv7bokaxdRfklInL3v">/pages/6sbv7bokaxdRfklInL3v</a> section.</p></div>
* Go to [https://www.base64encode.org](https://www.base64encode.org/).
* Paste the string and click **Encode**.\\

**Example**

<figure><img src="/files/bkIHTkrOYfXpqPhkHLpg" alt=""><figcaption></figcaption></figure>

Copy the result:

<figure><img src="/files/NDHy8I3B1nrYbx8qs8uT" alt=""><figcaption></figcaption></figure>

and paste it in the Authorization header as:

```
Basic base64_encoded_value
```

***

### 🧪 Step 3: Test the Request

1. Click **Test** in the HTTP Request block.
2. Then click **View Result**.

✅ If successful, you will receive a JSON response containing:

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "access_token": "xxxxx",
  "token_type": "Bearer",
  ...
}
</code></pre>

Copy the `access_token`.

***

### 🔁 Step 4: Use the Token in Future Requests

For any additional API calls (e.g., Listing customers, fetching invoices), include Authorization as a header:

```
Authorization: Bearer access_token
```

<figure><img src="/files/fxx9UNFFjg0LjSufGO2V" alt=""><figcaption></figcaption></figure>

#### **📌 Example endpoint:**

**Request**

```
GET https://public-api.demo.alternativepayments.io/customers
```

**Response**

<figure><img src="/files/P8YGW9PQHLIX8QUcBi6Y" alt=""><figcaption></figcaption></figure>

***

## :map:Flow

<figure><img src="/files/kqtIcoNGK8eis9QkHBuX" alt=""><figcaption></figcaption></figure>


# Overview

## Overview

The Alternative Payments Web SDK (`@getalternative/partner-sdk`) provides pre-built, embeddable UI components for collecting payments in web applications. It handles the complete payment flow including invoice display, payment method management, and secure card collection.

***

## Key Features

* **Pre-built UI Components** - Drop-in components for invoices, payment methods, and checkout
* **Full Payment Flow** - Orchestrated end-to-end payment experience
* **PCI Compliance** - Secure card collection via Evervault (no PCI scope for your app)
* **ACH Support** - Bank account collection
* **Customizable Theming** - Match your brand colors and styling
* **TypeScript Support** - Full type definitions included
* **Secure Authentication** - Token-based auth keeps credentials on your server

***

## Quick Example

```typescript
import { AlternativeClient } from '@getalternative/partner-sdk';

// Token is generated by your backend (keeps credentials secure)
const client = await AlternativeClient.create({
  accessToken: tokenFromYourBackend,
  environment: 'production',
  onAccessTokenExpired: async () => {
    // Fetch new token from your backend when expired
    const response = await fetch('/api/checkout-token');
    const { token } = await response.json();
    return token;
  },
});

// Create a full payment flow
const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  onPaymentSuccess: (payment) => {
    console.log('Payment successful:', payment.id);
  },
});
```

***

## Installation

```bash
npm install @getalternative/partner-sdk
```

Or with yarn:

```bash
yarn add @getalternative/partner-sdk
```

Or with pnpm:

```bash
pnpm add @getalternative/partner-sdk
```

{% hint style="info" %}
The SDK requires a modern browser with ES2020 support. It works with React, Vue, Angular, or vanilla JavaScript.
{% endhint %}

***

## Architecture

The SDK provides two ways to integrate payments:

### 1. Full Payment Flow

Use `createPaymentFlow()` for a complete, orchestrated payment experience. The SDK handles all navigation between screens automatically.

### 2. Individual Components

Use individual components via `client.components.*` for granular control over the payment experience. Build custom flows by composing components.

| Component             | Description                          |
| --------------------- | ------------------------------------ |
| `invoiceDetail`       | Show invoice details with line items |
| `paymentMethodSelect` | List and select payment methods      |
| `addPaymentMethod`    | Add new card or bank account         |
| `paymentConfirmation` | Review and confirm payment           |
| `paymentResult`       | Display payment success/error        |

***

## Next Steps

{% content-ref url="/pages/SYm8q4g8AyfhO7rLF2Mb" %}
[Authentication](/web-sdk/authentication)
{% endcontent-ref %}

{% content-ref url="/pages/4eJ6ZeKXY0t3vDOVFVpU" %}
[Getting Started](/web-sdk/getting-started)
{% endcontent-ref %}

{% content-ref url="/pages/cgGDbmEVTDDAfg4BWzF2" %}
[Payment Flow](/web-sdk/payment-flow)
{% endcontent-ref %}

{% content-ref url="/pages/v9Oy98re8K8KPpjh799e" %}
[Components](/web-sdk/components)
{% endcontent-ref %}

{% content-ref url="/pages/HAhpMja1SCRewZLwvu7p" %}
[Theming](/web-sdk/theming)
{% endcontent-ref %}


# Authentication

## Overview

The SDK uses JWT token-based authentication to keep your API credentials secure. Instead of exposing your Client ID and Secret in browser code, tokens are generated server-side by your backend.

***

## Why Token-Based Authentication?

{% hint style="success" %}
**Security Benefits:**

* API credentials (Client ID/Secret) never leave your server
* Tokens are scoped to specific customers and invoices
* Tokens have limited lifetime, reducing exposure risk
* Token refresh is handled automatically by the SDK
  {% endhint %}

***

## Authentication Flow

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your           │     │  Your           │     │  Alternative    │
│  Backend        │     │  Frontend       │     │  API            │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  1. POST /v1/checkout-auth/init              │
         │  (with OAuth2 client credentials)            │
         │──────────────────────────────────────────────>│
         │                       │                       │
         │  2. Returns JWT token                        │
         │<──────────────────────────────────────────────│
         │                       │                       │
         │  3. Pass token to frontend                   │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │  4. SDK uses token    │
         │                       │  for all API calls    │
         │                       │──────────────────────>│
         │                       │                       │
         │                       │  5. Token expires     │
         │                       │  onAccessTokenExpired │
         │                       │  callback triggered   │
         │                       │<─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│
         │                       │                       │
         │  6. Frontend requests │                       │
         │  new token            │                       │
         │<──────────────────────│                       │
         │                       │                       │
         │  7. New token returned│                       │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │  8. SDK continues     │
         │                       │  with new token       │
         │                       │──────────────────────>│
```

***

## Backend Implementation

### Step 1: Get OAuth Token

First, exchange your Client ID and Secret for an OAuth access token:

```bash
curl -X POST https://public-api.alternativepayments.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -d "grant_type=client_credentials"
```

Response:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

### Step 2: Generate Checkout Token

Use the OAuth token to generate a checkout token for a specific customer and invoice:

```bash
curl -X POST https://public-api.alternativepayments.io/v1/checkout-auth/init \
  -H "Authorization: Bearer {oauth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xxx",
    "invoice_id": "inv_xxx"
  }'
```

Response:

```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1703980800
}
```

### Complete Backend Example

{% tabs %}
{% tab title="Node.js (Express)" %}

```typescript
import express from 'express';

const router = express.Router();

const CLIENT_ID = process.env.ALTERNATIVE_CLIENT_ID;
const CLIENT_SECRET = process.env.ALTERNATIVE_CLIENT_SECRET;
const API_BASE = 'https://public-api.alternativepayments.io';

// Cache OAuth token
let oauthToken: { token: string; expiresAt: number } | null = null;

async function getOAuthToken(): Promise<string> {
  // Return cached token if valid
  if (oauthToken && oauthToken.expiresAt > Date.now() + 60000) {
    return oauthToken.token;
  }

  const response = await fetch(`${API_BASE}/oauth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`,
    },
    body: 'grant_type=client_credentials',
  });

  const data = await response.json();
  oauthToken = {
    token: data.access_token,
    expiresAt: Date.now() + data.expires_in * 1000,
  };

  return data.access_token;
}

router.post('/api/checkout-token', async (req, res) => {
  try {
    const { customerId, invoiceId } = req.body;

    // Validate inputs
    if (!customerId || !invoiceId) {
      return res.status(400).json({ error: 'customerId and invoiceId are required' });
    }

    // Get OAuth token
    const accessToken = await getOAuthToken();

    // Generate checkout token
    const response = await fetch(`${API_BASE}/v1/checkout-auth/init`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        customer_id: customerId,
        invoice_id: invoiceId,
      }),
    });

    if (!response.ok) {
      const error = await response.json();
      return res.status(response.status).json(error);
    }

    const data = await response.json();
    res.json({
      token: data.token,
      expiresAt: data.expires_at,
    });
  } catch (error) {
    console.error('Failed to generate checkout token:', error);
    res.status(500).json({ error: 'Failed to generate token' });
  }
});

export default router;
```

{% endtab %}

{% tab title="Python (FastAPI)" %}

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import httpx
import os
import base64
import time

app = FastAPI()

CLIENT_ID = os.environ["ALTERNATIVE_CLIENT_ID"]
CLIENT_SECRET = os.environ["ALTERNATIVE_CLIENT_SECRET"]
API_BASE = "https://public-api.alternativepayments.io"

# Token cache
oauth_token = {"token": None, "expires_at": 0}


async def get_oauth_token() -> str:
    global oauth_token

    # Return cached token if valid
    if oauth_token["token"] and oauth_token["expires_at"] > time.time() + 60:
        return oauth_token["token"]

    credentials = base64.b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()

    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{API_BASE}/oauth/token",
            headers={
                "Content-Type": "application/x-www-form-urlencoded",
                "Authorization": f"Basic {credentials}",
            },
            data="grant_type=client_credentials",
        )

    data = response.json()
    oauth_token = {
        "token": data["access_token"],
        "expires_at": time.time() + data["expires_in"],
    }

    return data["access_token"]


class TokenRequest(BaseModel):
    customer_id: str
    invoice_id: str


@app.post("/api/checkout-token")
async def generate_checkout_token(request: TokenRequest):
    try:
        access_token = await get_oauth_token()

        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{API_BASE}/v1/checkout-auth/init",
                headers={
                    "Authorization": f"Bearer {access_token}",
                    "Content-Type": "application/json",
                },
                json={
                    "customer_id": request.customer_id,
                    "invoice_id": request.invoice_id,
                },
            )

        if response.status_code != 200:
            raise HTTPException(status_code=response.status_code, detail=response.json())

        data = response.json()
        return {"token": data["token"], "expiresAt": data["expires_at"]}

    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
```

{% endtab %}
{% endtabs %}

***

## Frontend Implementation

### Initialize with Token

```typescript
import { AlternativeClient } from '@getalternative/partner-sdk';

// Fetch token from your backend
const { token } = await fetch('/api/checkout-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ customerId: 'cus_xxx', invoiceId: 'inv_xxx' }),
}).then(res => res.json());

// Initialize SDK
const client = await AlternativeClient.create({
  accessToken: token,
  environment: 'production',
});
```

### Handle Token Expiration

Provide an `onAccessTokenExpired` callback to automatically refresh tokens:

```typescript
const client = await AlternativeClient.create({
  accessToken: token,
  environment: 'production',
  onAccessTokenExpired: async () => {
    // This is called when the SDK receives a 401 response
    console.log('Token expired, fetching new one...');

    const response = await fetch('/api/checkout-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ customerId: 'cus_xxx', invoiceId: 'inv_xxx' }),
    });
    const { token } = await response.json();

    return token; // Return the new token
  },
});
```

{% hint style="warning" %}
If `onAccessTokenExpired` is not provided and the token expires, the SDK will throw an `AccessTokenExpiredError`.
{% endhint %}

***

## Error Handling

```typescript
import { AccessTokenExpiredError } from '@getalternative/partner-sdk';

try {
  // SDK operations
} catch (error) {
  if (error instanceof AccessTokenExpiredError) {
    // Token expired and no refresh callback was provided
    // Redirect user to re-authenticate or show error
    console.error('Session expired. Please refresh the page.');
  }
}
```

***

## Security Best Practices

1. **Never expose credentials in frontend code** - Always generate tokens on your backend
2. **Use HTTPS** - Ensure all communication is encrypted
3. **Validate on your backend** - Verify the customer/invoice belongs to the authenticated user
4. **Set appropriate token lifetimes** - Shorter lifetimes reduce exposure risk
5. **Implement the refresh callback** - Provide a smooth experience when tokens expire

***

## Token Contents

The checkout token is a JWT that contains:

| Claim         | Description                          |
| ------------- | ------------------------------------ |
| `partner_id`  | Your partner identifier              |
| `client_id`   | Your API client ID                   |
| `customer_id` | The customer this token is scoped to |
| `invoice_id`  | The invoice this token is scoped to  |
| `exp`         | Token expiration timestamp           |

{% hint style="info" %}
The SDK automatically extracts customer and invoice information from the token, so you don't need to pass these separately to components.
{% endhint %}


# Getting Started

## Prerequisites

Before using the SDK, you'll need:

1. **API Credentials** - Client ID and Client Secret from the Partner Dashboard (for your backend)
2. **A backend endpoint** - To generate checkout tokens for your frontend
3. **Invoice ID** - The invoice the customer will be paying
4. **A container element** - An HTML element where the SDK will render

{% hint style="warning" %}
**Important:** API credentials (Client ID and Secret) should only be used on your backend server. The frontend SDK uses access tokens generated by your backend to keep credentials secure.
{% endhint %}

***

## Step-by-Step Setup

{% stepper %}
{% step %}

### Install the SDK

```bash
npm install @getalternative/partner-sdk
```

{% endstep %}

{% step %}

### Create a Backend Token Endpoint

Your backend generates checkout tokens using your API credentials:

```typescript
// backend/routes/checkout.ts (example with Express)
import express from 'express';

const router = express.Router();

router.post('/api/checkout-token', async (req, res) => {
  const { customerId, invoiceId } = req.body;

  // 1. Get OAuth token using client credentials
  const oauthResponse = await fetch('https://public-api.alternativepayments.io/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`,
    },
    body: 'grant_type=client_credentials',
  });
  const { access_token } = await oauthResponse.json();

  // 2. Generate checkout token
  const checkoutResponse = await fetch('https://public-api.alternativepayments.io/v1/checkout-auth/init', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${access_token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ customer_id: customerId, invoice_id: invoiceId }),
  });
  const { token, expires_at } = await checkoutResponse.json();

  res.json({ token, expiresAt: expires_at });
});
```

{% endstep %}

{% step %}

### Add a Container Element

```html
<div id="payment-container"></div>
```

{% endstep %}

{% step %}

### Initialize the SDK

```typescript
import { AlternativeClient } from '@getalternative/partner-sdk';

// Fetch token from your backend
const { token } = await fetch('/api/checkout-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ customerId: 'cus_xxx', invoiceId: 'inv_xxx' }),
}).then(res => res.json());

// Initialize SDK
const client = await AlternativeClient.create({
  accessToken: token,
  environment: 'production',
  onAccessTokenExpired: async () => {
    // Re-fetch token when expired
    const response = await fetch('/api/checkout-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ customerId: 'cus_xxx', invoiceId: 'inv_xxx' }),
    });
    const { token } = await response.json();
    return token;
  },
});
```

{% endstep %}

{% step %}

### Create the Payment Flow

```typescript
const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  onPaymentSuccess: (payment) => {
    console.log('Payment completed:', payment.id);
  },
  onPaymentError: (error) => {
    console.error('Payment failed:', error.message);
  },
});
```

{% endstep %}
{% endstepper %}

***

## Configuration Options

### AlternativeClientConfig

| Property               | Type                                  | Required | Description                                 |
| ---------------------- | ------------------------------------- | -------- | ------------------------------------------- |
| `accessToken`          | `string`                              | Yes      | JWT access token from your backend          |
| `environment`          | `'production' \| 'staging' \| 'demo'` | No       | API environment (default: production)       |
| `baseUrl`              | `string`                              | No       | Custom API base URL (overrides environment) |
| `timeout`              | `number`                              | No       | Request timeout in ms (default: 30000)      |
| `retries`              | `number`                              | No       | Number of retry attempts (default: 3)       |
| `onAccessTokenExpired` | `() => Promise<string>`               | No       | Callback to fetch new token when expired    |
| `theme`                | `ThemeConfig`                         | No       | Default theme for all components            |

***

## Environments

<table><thead><tr><th width="200">Environment</th><th>Description</th></tr></thead><tbody><tr><td><code>production</code></td><td>Live environment for real payments</td></tr><tr><td><code>staging</code></td><td>Test environment for development</td></tr><tr><td><code>demo</code></td><td>Demo environment for showcasing and testing</td></tr></tbody></table>

{% hint style="danger" %}
**Important:** Use separate API credentials for each environment. Production credentials will not work in staging and vice versa.
{% endhint %}

***

## Full Example

```html
<!DOCTYPE html>
<html>
<head>
  <title>Payment Page</title>
</head>
<body>
  <h1>Complete Your Payment</h1>
  <div id="payment-container"></div>

  <script type="module">
    import { AlternativeClient } from '@getalternative/partner-sdk';

    // Fetch token from your backend
    const { token } = await fetch('/api/checkout-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        customerId: 'cus_abc123',
        invoiceId: 'inv_abc123'
      }),
    }).then(res => res.json());

    const client = await AlternativeClient.create({
      accessToken: token,
      environment: 'staging',
      onAccessTokenExpired: async () => {
        const response = await fetch('/api/checkout-token', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            customerId: 'cus_abc123',
            invoiceId: 'inv_abc123'
          }),
        });
        const { token } = await response.json();
        return token;
      },
    });

    const flow = client.createPaymentFlow({
      containerId: 'payment-container',
      onPaymentSuccess: (payment) => {
        alert('Payment successful!');
        window.location.href = '/thank-you';
      },
      onPaymentError: (error) => {
        alert('Payment failed: ' + error.message);
      },
      onClose: () => {
        console.log('Payment flow closed');
      },
    });

    // Cleanup when navigating away
    window.addEventListener('beforeunload', () => {
      flow.unmount();
    });
  </script>
</body>
</html>
```

***

## React Integration

```tsx
import { useEffect, useRef } from 'react';
import { AlternativeClient } from '@getalternative/partner-sdk';

interface PaymentWidgetProps {
  customerId: string;
  invoiceId: string;
}

function PaymentWidget({ customerId, invoiceId }: PaymentWidgetProps) {
  const flowRef = useRef<ReturnType<typeof AlternativeClient.prototype.createPaymentFlow> | null>(null);

  useEffect(() => {
    let mounted = true;

    async function initPayment() {
      // Fetch token from your backend
      const { token } = await fetch('/api/checkout-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ customerId, invoiceId }),
      }).then(res => res.json());

      if (!mounted) return;

      const client = await AlternativeClient.create({
        accessToken: token,
        environment: 'staging',
        onAccessTokenExpired: async () => {
          const response = await fetch('/api/checkout-token', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ customerId, invoiceId }),
          });
          const { token } = await response.json();
          return token;
        },
      });

      if (!mounted) return;

      flowRef.current = client.createPaymentFlow({
        containerId: 'payment-container',
        onPaymentSuccess: (payment) => {
          console.log('Success:', payment);
        },
      });
    }

    initPayment();

    return () => {
      mounted = false;
      flowRef.current?.unmount();
    };
  }, [customerId, invoiceId]);

  return <div id="payment-container" />;
}
```

***

## Next Steps

{% content-ref url="/pages/SYm8q4g8AyfhO7rLF2Mb" %}
[Authentication](/web-sdk/authentication)
{% endcontent-ref %}

{% content-ref url="/pages/cgGDbmEVTDDAfg4BWzF2" %}
[Payment Flow](/web-sdk/payment-flow)
{% endcontent-ref %}

{% content-ref url="/pages/HAhpMja1SCRewZLwvu7p" %}
[Theming](/web-sdk/theming)
{% endcontent-ref %}


# Payment Flow

## Overview

The `createPaymentFlow()` method provides a complete, orchestrated payment experience. It handles navigation between all screens automatically, making it the easiest way to integrate payments.

***

## Flow Screens

The payment flow progresses through these screens:

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Invoice Detail │ ──▶ │ Payment Method  │ ──▶ │   Confirmation  │
│                 │     │    Selection    │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                ┌───────▼─────────┐
                                                │ Payment Result  │
                                                │                 │
                                                └─────────────────┘
```

1. **Invoice Detail** - Displays invoice information and line items
2. **Payment Method Selection** - Choose existing or add new payment method
3. **Add Payment Method** - Card or bank account form (if adding new)
4. **Confirmation** - Review payment details before submitting
5. **Result** - Success or error screen

***

## Basic Usage

```typescript
const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  invoiceId: 'inv_xxx', // Required
  onPaymentSuccess: (payment) => {
    console.log('Payment successful:', payment);
  },
  onPaymentError: (error) => {
    console.error('Payment failed:', error);
  },
  onClose: () => {
    console.log('Flow closed');
  },
});
```

***

## Configuration

### PaymentFlowConfig

<table><thead><tr><th width="165.09765625">Property</th><th width="249.75390625">Type</th><th width="107.11328125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>containerId</code></td><td><code>string</code></td><td>Yes</td><td>ID of the container element</td></tr><tr><td><code>invoiceId</code></td><td><code>string</code></td><td>Yes</td><td>Invoice ID to pay</td></tr><tr><td><code>theme</code></td><td><code>ThemeConfig</code></td><td>No</td><td>Custom theme configuration</td></tr><tr><td><code>onPaymentSuccess</code></td><td><code>(payment: Payment) => void</code></td><td>No</td><td>Called when payment succeeds</td></tr><tr><td><code>onPaymentError</code></td><td><code>(error: Error) => void</code></td><td>No</td><td>Called when payment fails</td></tr><tr><td><code>onClose</code></td><td><code>() => void</code></td><td>No</td><td>Called when flow is closed</td></tr><tr><td><code>onGoBack</code></td><td><code>() => void</code></td><td>No</td><td>Called when user clicks "Go back" on success screen</td></tr></tbody></table>

***

## Common Use Cases

### Basic Payment Flow

```typescript
const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  invoiceId: 'inv_xxx',
  onPaymentSuccess: (payment) => {
    window.location.href = '/payment-success';
  },
  onGoBack: () => {
    window.location.href = '/dashboard';
  },
});
```

### Handle Payment Results

```typescript
const flow = client.createPaymentFlow({
  containerId: 'payment-container',
  invoiceId: 'inv_xxx',
  onPaymentSuccess: (payment) => {
    // Payment completed successfully
    console.log('Payment ID:', payment.id);
    console.log('Amount:', payment.amount);
    console.log('Status:', payment.status);

    // Redirect to success page
    window.location.href = `/success?payment=${payment.id}`;
  },
  onPaymentError: (error) => {
    // Payment failed
    console.error('Error:', error.message);

    // Show error to user or retry
    showNotification('Payment failed. Please try again.');
  },
  onClose: () => {
    // User closed the flow without completing
    // Navigate back or show message
  },
  onGoBack: () => {
    // User clicked "Go back" on success screen
    window.location.href = '/dashboard';
  },
});
```

***

## Component Instance Methods

The flow returns a `ComponentInstance` with these methods:

### mount()

Mounts the component to the DOM. Called automatically on creation.

```typescript
flow.mount();
```

### unmount()

Removes the component from the DOM. Call this when navigating away or cleaning up.

```typescript
flow.unmount();
```

### refresh()

Refreshes the component data. Useful after external changes.

```typescript
await flow.refresh();
```

***

## Cleanup

Always unmount the flow when the user navigates away to prevent memory leaks:

```typescript
// Vanilla JS
window.addEventListener('beforeunload', () => {
  flow.unmount();
});

// React
useEffect(() => {
  const flow = client.createPaymentFlow({ ... });
  return () => flow.unmount();
}, []);

// Vue
onUnmounted(() => {
  flow.unmount();
});
```

***

## Already Paid Invoices

If an invoice is already paid (status: `RECEIVED`), the flow will skip directly to the success screen, showing the payment details without requiring any user action.

***

## Related

{% content-ref url="/pages/v9Oy98re8K8KPpjh799e" %}
[Components](/web-sdk/components)
{% endcontent-ref %}

{% content-ref url="/pages/HAhpMja1SCRewZLwvu7p" %}
[Theming](/web-sdk/theming)
{% endcontent-ref %}


# Components

## Overview

The SDK provides individual components that can be used to build custom payment experiences. Access them via `client.components.*`.

***

## Available Components

| Component                                                          | Description                       |
| ------------------------------------------------------------------ | --------------------------------- |
| [Invoice Detail](/web-sdk/components/invoice-detail)               | Show detailed invoice information |
| [Payment Method Select](/web-sdk/components/payment-method-select) | List and select payment methods   |
| [Add Payment Method](/web-sdk/components/add-payment-method)       | Add new card or bank account      |
| [Payment Confirmation](/web-sdk/components/payment-confirmation)   | Review and confirm payment        |
| [Payment Result](/web-sdk/components/payment-result)               | Display payment outcome           |

***

## Using Components

All components share a common pattern:

```typescript
// 1. Initialize the client
const client = new AlternativeClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

// 2. Create a component
const component = client.components.invoiceList({
  containerId: 'my-container',
  customerId: 'cus_xxx',
  onSelect: (invoice) => {
    console.log('Selected:', invoice);
  },
});

// 3. Later: cleanup
component.unmount();
```

***

## Common Configuration

All components accept these base properties:

| Property      | Type          | Required | Description                             |
| ------------- | ------------- | -------- | --------------------------------------- |
| `containerId` | `string`      | Yes      | ID of the HTML element to mount into    |
| `theme`       | `ThemeConfig` | No       | Custom theme (overrides client default) |

***

## Component Instance

Each component returns a `ComponentInstance` with these methods:

```typescript
interface ComponentInstance {
  mount(): void;      // Mount to DOM (auto-called on creation)
  unmount(): void;    // Remove from DOM
  refresh(): Promise<void>;  // Refresh data
}
```

***

## Building Custom Flows

Compose components to create custom payment experiences:

```typescript
const client = new AlternativeClient({ ... });

let selectedPaymentMethod: PaymentMethod | null = null;
const invoiceId = 'inv_xxx';

// Step 1: Show payment method selection
const paymentSelect = client.components.paymentMethodSelect({
  containerId: 'container',
  customerId: 'cus_xxx',
  onSelect: (pm) => {
    selectedPaymentMethod = pm;
    paymentSelect.unmount();
    showConfirmation();
  },
  onAddNew: () => {
    paymentSelect.unmount();
    showAddPaymentMethod();
  },
});

// Step 2: Confirm and process
function showConfirmation() {
  const confirmation = client.components.paymentConfirmation({
    containerId: 'container',
    invoiceId: invoiceId,
    paymentMethodId: selectedPaymentMethod!.id,
    customerId: 'cus_xxx',
    onPaymentSuccess: (payment) => {
      confirmation.unmount();
      showResult('success', payment);
    },
    onPaymentError: (error) => {
      confirmation.unmount();
      showResult('error', undefined, error);
    },
  });
}
```

***

## Next Steps

Explore individual component documentation for detailed configuration options and examples.


# Invoice Detail

Displays detailed information about a specific invoice, including line items, amounts, and due date.

***

## Usage

```typescript
const invoiceDetail = client.components.invoiceDetail({
  containerId: 'invoice-detail',
  invoiceId: 'inv_xxx',
  onPayNow: (invoice) => {
    console.log('Pay now clicked for:', invoice.id);
  },
  onBack: () => {
    console.log('Back clicked');
  },
});
```

***

## Configuration

### InvoiceDetailConfig

<table><thead><tr><th width="139.50390625">Property</th><th>Type</th><th width="108.53125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>containerId</code></td><td><code>string</code></td><td>Yes</td><td>ID of the container element</td></tr><tr><td><code>invoiceId</code></td><td><code>string</code></td><td>Yes</td><td>Invoice ID to display</td></tr><tr><td><code>theme</code></td><td><code>ThemeConfig</code></td><td>No</td><td>Custom theme configuration</td></tr><tr><td><code>onPayNow</code></td><td><code>(invoice: Invoice) => void</code></td><td>No</td><td>Called when "Pay Now" is clicked</td></tr><tr><td><code>onBack</code></td><td><code>() => void</code></td><td>No</td><td>Called when "Back" is clicked</td></tr><tr><td><code>onError</code></td><td><code>(error: Error) => void</code></td><td>No</td><td>Called on fetch errors</td></tr></tbody></table>

***

## Features

The Invoice Detail component displays:

* Invoice number with download button
* Customer information
* Due date and status
* Line items with descriptions and amounts
* Subtotal, taxes, and total amount
* Payment scheduling option (if applicable)

***

## Example

```html
<div id="invoice-detail"></div>

<script type="module">
  import { AlternativeClient } from '@getalternative/partner-sdk';

  const client = new AlternativeClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  });

  // Get invoice ID from URL
  const invoiceId = new URLSearchParams(window.location.search).get('id');

  const detail = client.components.invoiceDetail({
    containerId: 'invoice-detail',
    invoiceId: invoiceId,
    onPayNow: (invoice) => {
      // Navigate to payment selection
      window.location.href = `/pay?invoice=${invoice.id}`;
    },
    onBack: () => {
      window.history.back();
    },
  });
</script>
```

***

## Invoice Download

The component includes a download button next to the invoice number that allows users to download the invoice as a PDF.


# Payment Method Select

Displays the customer's saved payment methods and allows selection or adding new ones.

***

## Usage

```typescript
const paymentSelect = client.components.paymentMethodSelect({
  containerId: 'payment-methods',
  customerId: 'cus_xxx',
  onSelect: (paymentMethod) => {
    console.log('Selected:', paymentMethod.id);
  },
  onAddNew: (type) => {
    console.log('Add new payment method:', type);
  },
});
```

***

## Configuration

### PaymentMethodSelectConfig

<table><thead><tr><th width="159.6875">Property</th><th width="240.33203125">Type</th><th width="113.19921875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>containerId</code></td><td><code>string</code></td><td>Yes</td><td>ID of the container element</td></tr><tr><td><code>customerId</code></td><td><code>string</code></td><td>Yes</td><td>Customer ID to fetch payment methods for</td></tr><tr><td><code>selectedPaymentMethodId</code></td><td><code>string</code></td><td>No</td><td>Pre-select a payment method</td></tr><tr><td><code>theme</code></td><td><code>ThemeConfig</code></td><td>No</td><td>Custom theme configuration</td></tr><tr><td><code>onSelect</code></td><td><code>(pm: PaymentMethod) => void</code></td><td>No</td><td>Called when a payment method is selected</td></tr><tr><td><code>onAddNew</code></td><td><code>(type: PaymentMethodType) => void</code></td><td>No</td><td>Called when "Add New" is clicked</td></tr><tr><td><code>onBack</code></td><td><code>() => void</code></td><td>No</td><td>Called when "Back" is clicked</td></tr><tr><td><code>onError</code></td><td><code>(error: Error) => void</code></td><td>No</td><td>Called on errors</td></tr></tbody></table>

***

## Payment Method Types

The component supports these payment method types:

| Type   | Description                 |
| ------ | --------------------------- |
| `CARD` | Credit or debit card        |
| `ACH`  | Bank account (ACH transfer) |

***

## PaymentMethod Object

The `onSelect` callback receives a `PaymentMethod` object:

```typescript
interface PaymentMethod {
  id: string;
  type: 'CARD' | 'ACH';
  customer_id: string;
  is_default: boolean;
  card?: {
    brand: string;
    last_four: string;
    exp_month: number;
    exp_year: number;
  };
  ach?: {
    bank_name: string;
    last_four: string;
    account_type: 'checking' | 'savings';
  };
}
```

***

## Example

```html
<div id="payment-methods"></div>

<script type="module">
  import { AlternativeClient } from '@getalternative/partner-sdk';

  const client = new AlternativeClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  });

  const select = client.components.paymentMethodSelect({
    containerId: 'payment-methods',
    customerId: 'cus_abc123',
    onSelect: (pm) => {
      // Proceed to confirmation with selected method
      proceedToConfirmation(pm.id);
    },
    onAddNew: (type) => {
      // Show add payment method form
      showAddPaymentMethodForm(type);
    },
  });
</script>
```

***

## Display

The component shows:

* List of saved payment methods with icons
* Card brand and last 4 digits for cards
* Bank name and last 4 digits for ACH
* Radio buttons for selection
* "Add Credit Card" and "Add Bank Account" buttons
* "Continue to Payment" button when a method is selected


# Add Payment Method

Form for adding a new payment method (credit card or bank account).

***

## Usage

```typescript
const addPayment = client.components.addPaymentMethod({
  containerId: 'add-payment',
  customerId: 'cus_xxx',
  defaultType: 'CARD',
  onSuccess: (paymentMethod) => {
    console.log('Added:', paymentMethod.id);
  },
  onCancel: () => {
    console.log('Cancelled');
  },
});
```

***

## Configuration

### AddPaymentMethodConfig

| Property      | Type                          | Required | Description                           |
| ------------- | ----------------------------- | -------- | ------------------------------------- |
| `containerId` | `string`                      | Yes      | ID of the container element           |
| `customerId`  | `string`                      | Yes      | Customer ID to add payment method for |
| `defaultType` | `'CARD' \| 'ACH'`             | No       | Default tab to show                   |
| `currency`    | `'usd' \| 'cad'`              | No       | Currency context                      |
| `theme`       | `ThemeConfig`                 | No       | Custom theme configuration            |
| `onSuccess`   | `(pm: PaymentMethod) => void` | No       | Called when payment method is created |
| `onCancel`    | `() => void`                  | No       | Called when "Cancel" is clicked       |
| `onError`     | `(error: Error) => void`      | No       | Called on errors                      |

***

## Card Form

The card form uses Evervault for PCI-compliant card collection. Your application never touches raw card data.

**Fields collected:**

* Card number
* Expiration date (MM/YY)
* Cardholder name
* Billing address (street, city, state, postal code, country)

***

## Bank Account Form (ACH)

The ACH form uses Plaid for secure bank account linking.

**Process:**

1. User clicks "Connect Bank Account"
2. Plaid Link opens in a modal
3. User selects their bank and authenticates
4. Account details are securely captured

***

## Example

```html
<div id="add-payment"></div>

<script type="module">
  import { AlternativeClient } from '@getalternative/partner-sdk';

  const client = new AlternativeClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  });

  const form = client.components.addPaymentMethod({
    containerId: 'add-payment',
    customerId: 'cus_abc123',
    defaultType: 'CARD',
    onSuccess: (paymentMethod) => {
      // Payment method added successfully
      console.log('New payment method:', paymentMethod);

      // Navigate back to selection
      window.location.href = '/payment-methods';
    },
    onCancel: () => {
      window.history.back();
    },
    onError: (error) => {
      console.error('Failed to add payment method:', error);
    },
  });
</script>
```

***

## Security

{% hint style="success" %}
**PCI Compliance**

Card data is collected directly by Evervault and never touches your servers. This keeps your application out of PCI scope.
{% endhint %}

{% hint style="info" %}
**Bank Security**

Bank credentials are handled entirely by Plaid. Your application only receives a secure token for the linked account.
{% endhint %}

***

## Credit Card Support & Evervault

### The SDK component is the only supported path for collecting card details

The `addPaymentMethod` component is the only supported way to add a credit card payment method. There is no REST API endpoint that accepts raw card numbers — the REST API's `POST /customers/{id}/payment-methods/card` endpoint requires a `card_provider_token` that has already been encrypted by Evervault. Obtaining that token requires the Evervault iframe, which the SDK component hosts on your behalf.

Partners building custom portals must use this SDK component for card collection. Attempting to call the card endpoint directly without a valid Evervault token will result in a `400 Bad Request` with `card_provider_token is required`.

### How the Evervault iframe works

When the card form renders, the SDK fetches Evervault credentials from the API and initializes a secure iframe hosted by Evervault. The customer enters their card details inside that iframe. Evervault encrypts the data and returns an opaque token; the SDK then passes that token — with `provider: "evervault"` — to `POST /customers/{id}/payment-methods/card`. At no point does plain-text card data pass through your application or Alternative Payments' servers.

This architecture keeps your integration out of PCI scope for card data handling.

### Customization scope

You can customize the appearance of the `addPaymentMethod` component using the `theme` configuration (see [Theming](/web-sdk/theming)). The `ThemeConfig` properties — colors, typography, border radius, and so on — apply to the surrounding SDK component shell.

The Evervault iframe itself is rendered and controlled by Evervault. Its internal appearance cannot be customized through the SDK's `theme` configuration.

### Bank accounts vs. credit cards

Bank account payment methods behave differently. The REST API endpoint `POST /customers/{id}/payment-methods/bank` accepts account details directly (routing number, account number, institution name, and so on) and does not require the SDK or an iframe. Partners can call this endpoint from their own server-side code independently of the Web SDK.

| Method             | SDK required?                                       | REST API endpoint                                                            |
| ------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------- |
| Credit card        | **Yes** — SDK component obtains the Evervault token | `POST /customers/{id}/payment-methods/card` (requires `card_provider_token`) |
| Bank account (ACH) | No                                                  | `POST /customers/{id}/payment-methods/bank`                                  |

Both endpoints require the `payments:write` OAuth scope.

{% hint style="warning" %}
**Custom portal integrations**

If you have built a custom payment portal using the checkout APIs, card collection still requires the `addPaymentMethod` SDK component. There is no path to add a card payment method without the Evervault iframe.
{% endhint %}


# Payment Confirmation

Review screen before submitting a payment. Shows invoice details, selected payment method, and payment amount.

***

## Usage

```typescript
const confirmation = client.components.paymentConfirmation({
  containerId: 'confirmation',
  invoiceId: 'inv_xxx',
  paymentMethodId: 'pm_xxx',
  customerId: 'cus_xxx',
  onPaymentSuccess: (payment) => {
    console.log('Payment successful:', payment.id);
  },
  onPaymentError: (error) => {
    console.error('Payment failed:', error);
  },
  onBack: () => {
    console.log('Back clicked');
  },
});
```

***

## Configuration

### PaymentConfirmationConfig

<table><thead><tr><th width="166.33203125">Property</th><th>Type</th><th width="106.58203125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>containerId</code></td><td><code>string</code></td><td>Yes</td><td>ID of the container element</td></tr><tr><td><code>invoiceId</code></td><td><code>string</code></td><td>Yes</td><td>Invoice being paid</td></tr><tr><td><code>paymentMethodId</code></td><td><code>string</code></td><td>Yes</td><td>Selected payment method</td></tr><tr><td><code>customerId</code></td><td><code>string</code></td><td>Yes</td><td>Customer making the payment</td></tr><tr><td><code>theme</code></td><td><code>ThemeConfig</code></td><td>No</td><td>Custom theme configuration</td></tr><tr><td><code>onConfirm</code></td><td><code>() => void</code></td><td>No</td><td>Called when payment is initiated</td></tr><tr><td><code>onBack</code></td><td><code>() => void</code></td><td>No</td><td>Called when "Back" is clicked</td></tr><tr><td><code>onPaymentSuccess</code></td><td><code>(payment: Payment) => void</code></td><td>No</td><td>Called when payment succeeds</td></tr><tr><td><code>onPaymentError</code></td><td><code>(error: Error) => void</code></td><td>No</td><td>Called when payment fails</td></tr><tr><td><code>onError</code></td><td><code>(error: Error) => void</code></td><td>No</td><td>Called on other errors</td></tr></tbody></table>

***

## Payment Object

The `onPaymentSuccess` callback receives a `Payment` object:

```typescript
interface Payment {
  id: string;
  status: 'PENDING' | 'COMPLETED' | 'FAILED';
  amount: number;
  currency: string;
  invoice_id: string;
  payment_method_id: string;
  created_at: string;
  // ... additional fields
}
```

***

## Example

```html
<div id="confirmation"></div>

<script type="module">
  import { AlternativeClient } from '@getalternative/partner-sdk';

  const client = new AlternativeClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  });

  // Get IDs from URL or state
  const params = new URLSearchParams(window.location.search);

  const confirm = client.components.paymentConfirmation({
    containerId: 'confirmation',
    invoiceId: params.get('invoice'),
    paymentMethodId: params.get('payment_method'),
    customerId: params.get('customer'),
    onPaymentSuccess: (payment) => {
      // Redirect to success page
      window.location.href = `/success?payment=${payment.id}`;
    },
    onPaymentError: (error) => {
      // Show error or retry
      alert('Payment failed: ' + error.message);
    },
    onBack: () => {
      window.history.back();
    },
  });
</script>
```

***

## Display

The confirmation screen shows:

* Invoice summary (number, amount, due date)
* Selected payment method details
* Total amount to be charged
* "Pay Now" button to submit payment
* "Back" button to return to previous screen


# Payment Result

Displays the outcome of a payment attempt (success, error, or processing).

***

## Usage

```typescript
const result = client.components.paymentResult({
  containerId: 'result',
  status: 'success',
  payment: paymentObject,
  onDone: () => {
    console.log('Done clicked');
  },
});
```

***

## Configuration

### PaymentResultConfig

<table><thead><tr><th width="132.30078125">Property</th><th>Type</th><th width="106.38671875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>containerId</code></td><td><code>string</code></td><td>Yes</td><td>ID of the container element</td></tr><tr><td><code>status</code></td><td><code>'success' | 'error' | 'processing'</code></td><td>Yes</td><td>Payment outcome</td></tr><tr><td><code>payment</code></td><td><code>Payment</code></td><td>No</td><td>Payment details (for success)</td></tr><tr><td><code>error</code></td><td><code>Error</code></td><td>No</td><td>Error details (for error status)</td></tr><tr><td><code>theme</code></td><td><code>ThemeConfig</code></td><td>No</td><td>Custom theme configuration</td></tr><tr><td><code>onDone</code></td><td><code>() => void</code></td><td>No</td><td>Called when "Done" is clicked</td></tr><tr><td><code>onRetry</code></td><td><code>() => void</code></td><td>No</td><td>Called when "Retry" is clicked (errors)</td></tr></tbody></table>

***

## Status Types

### Success

Shows a success message with payment details.

```typescript
const result = client.components.paymentResult({
  containerId: 'result',
  status: 'success',
  payment: {
    id: 'pay_xxx',
    amount: 150.00,
    currency: 'USD',
    // ...
  },
  onDone: () => {
    window.location.href = '/dashboard';
  },
});
```

### Error

Shows an error message with retry option.

```typescript
const result = client.components.paymentResult({
  containerId: 'result',
  status: 'error',
  error: new Error('Card declined'),
  onRetry: () => {
    // Go back to payment method selection
    showPaymentMethods();
  },
  onDone: () => {
    window.location.href = '/dashboard';
  },
});
```

### Processing

Shows a processing indicator for async payments.

```typescript
const result = client.components.paymentResult({
  containerId: 'result',
  status: 'processing',
  onDone: () => {
    window.location.href = '/dashboard';
  },
});
```

***

## Example

```html
<div id="result"></div>

<script type="module">
  import { AlternativeClient } from '@getalternative/partner-sdk';

  const client = new AlternativeClient({
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  });

  // Get payment result from previous step
  const paymentResult = getPaymentResult();

  const result = client.components.paymentResult({
    containerId: 'result',
    status: paymentResult.success ? 'success' : 'error',
    payment: paymentResult.payment,
    error: paymentResult.error,
    onDone: () => {
      // Return to main application
      window.location.href = '/';
    },
    onRetry: () => {
      // Try again
      window.location.href = '/pay';
    },
  });
</script>
```

***

## Display

**Success screen shows:**

* Success icon and message
* Payment confirmation number
* Amount paid
* "Done" button

**Error screen shows:**

* Error icon and message
* Error details
* "Retry" button
* "Done" button

**Processing screen shows:**

* Loading indicator
* Processing message
* "Done" button (to continue anyway)


# Theming

## Overview

Customize the appearance of SDK components to match your brand. Themes can be applied globally or per-component.

***

## Theme Configuration

```typescript
interface ThemeConfig {
  primaryColor?: string;      // Primary brand color
  secondaryColor?: string;    // Secondary/accent color
  backgroundColor?: string;   // Background color
  textColor?: string;         // Primary text color
  borderColor?: string;       // Border color
  errorColor?: string;        // Error state color
  successColor?: string;      // Success state color
  fontFamily?: string;        // Font family
  borderRadius?: string;      // Border radius
}
```

***

## Applying Themes

### Global Theme (Client Level)

Apply a theme to all components created by the client:

```typescript
const client = new AlternativeClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  theme: {
    primaryColor: '#0066cc',
    successColor: '#22c55e',
    errorColor: '#ef4444',
    fontFamily: 'Inter, system-ui, sans-serif',
    borderRadius: '8px',
  },
});
```

### Per-Component Theme

Override the global theme for a specific component:

```typescript
const invoiceList = client.components.invoiceList({
  containerId: 'invoices',
  customerId: 'cus_xxx',
  theme: {
    primaryColor: '#8b5cf6', // Override just this property
  },
});
```

***

## Theme Properties

### Colors

| Property          | Description                     | Default   |
| ----------------- | ------------------------------- | --------- |
| `primaryColor`    | Buttons, links, primary actions | `#0066cc` |
| `secondaryColor`  | Secondary elements, accents     | `#6b7280` |
| `backgroundColor` | Component background            | `#ffffff` |
| `textColor`       | Primary text color              | `#1a1a1a` |
| `borderColor`     | Borders and dividers            | `#e5e7eb` |
| `errorColor`      | Error states, validation        | `#ef4444` |
| `successColor`    | Success states                  | `#22c55e` |

### Typography

<table><thead><tr><th>Property</th><th width="194.86328125">Description</th><th>Default</th></tr></thead><tbody><tr><td><code>fontFamily</code></td><td>Font stack</td><td><code>Inter, system-ui, sans-serif</code></td></tr></tbody></table>

### Spacing & Shape

| Property       | Description   | Default |
| -------------- | ------------- | ------- |
| `borderRadius` | Corner radius | `8px`   |

***

## Preset Themes

### Default

```typescript
const defaultTheme = {
  primaryColor: '#0066cc',
  successColor: '#22c55e',
  errorColor: '#ef4444',
  textColor: '#1a1a1a',
  secondaryColor: '#6b7280',
  backgroundColor: '#ffffff',
  borderColor: '#e5e7eb',
  borderRadius: '8px',
  fontFamily: 'Inter, system-ui, sans-serif',
};
```

### Dark Mode

```typescript
const darkTheme = {
  primaryColor: '#3b82f6',
  successColor: '#10b981',
  errorColor: '#f87171',
  textColor: '#f9fafb',
  secondaryColor: '#9ca3af',
  backgroundColor: '#1f2937',
  borderColor: '#374151',
  borderRadius: '8px',
  fontFamily: 'Inter, system-ui, sans-serif',
};
```

### Purple

```typescript
const purpleTheme = {
  primaryColor: '#8b5cf6',
  successColor: '#34d399',
  errorColor: '#f87171',
  textColor: '#1e1b4b',
  secondaryColor: '#6366f1',
  backgroundColor: '#faf5ff',
  borderColor: '#ddd6fe',
  borderRadius: '12px',
  fontFamily: "'SF Pro Display', system-ui, sans-serif",
};
```

***

## Example: Custom Branded Theme

```typescript
const client = new AlternativeClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  theme: {
    // Your brand colors
    primaryColor: '#FF5722',      // Orange primary
    successColor: '#4CAF50',      // Green success
    errorColor: '#F44336',        // Red error

    // Text and backgrounds
    textColor: '#212121',
    backgroundColor: '#FAFAFA',
    borderColor: '#E0E0E0',

    // Typography
    fontFamily: "'Roboto', sans-serif",

    // Shape
    borderRadius: '4px',          // Square corners
  },
});
```

***

## CSS Custom Properties

The SDK uses CSS custom properties internally. You can also override styles using CSS:

```css
/* Override SDK styles */
.alt-widget {
  --alt-primary: #FF5722;
  --alt-success: #4CAF50;
  --alt-danger: #F44336;
  --alt-text: #212121;
  --alt-background: #FAFAFA;
  --alt-border: #E0E0E0;
  --alt-font-family: 'Roboto', sans-serif;
  --alt-border-radius: 4px;
}
```

{% hint style="warning" %}
CSS overrides may break in future SDK versions. Prefer using the `theme` configuration when possible.
{% endhint %}

***

## Live Theme Editor

The SDK examples include a live theme editor for testing different color combinations. Run the examples locally to experiment with themes before implementing.

```bash
cd partner-sdk/examples
npm install
npm run dev
```

Then visit `http://localhost:5173/custom-theme.html` to use the interactive theme editor.


# Address

## Address autocomplete

> Returns address suggestions from Google Places API

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"address_api.AutocompleteResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/address_api.Prediction"},"type":"array"}},"type":"object"},"address_api.Prediction":{"properties":{"description":{"type":"string"},"place_id":{"type":"string"},"structured_formatting":{"$ref":"#/components/schemas/address_api.StructuredFormating"}},"type":"object"},"address_api.StructuredFormating":{"properties":{"main_text":{"type":"string"},"secondary_text":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"address_api.AutocompleteRequest":{"properties":{"country":{"type":"string"},"q":{"type":"string"},"sessiontoken":{"type":"string"}},"type":"object"}}},"paths":{"/address/autocomplete":{"post":{"description":"Returns address suggestions from Google Places API","operationId":"addressAutocomplete","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/address_api.AutocompleteResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Address autocomplete","tags":["Address"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/address_api.AutocompleteRequest"}}},"description":"Autocomplete request","required":true}}}}}
```

## Get address details

> Returns full address details from Google Places API

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"address_api.DetailsResponse":{"properties":{"data":{"$ref":"#/components/schemas/address_api.PlaceDetails"}},"type":"object"},"address_api.PlaceDetails":{"properties":{"result":{"$ref":"#/components/schemas/address_api.AddressResult"}},"type":"object"},"address_api.AddressResult":{"properties":{"address_components":{"items":{"$ref":"#/components/schemas/address_api.AddressComponent"},"type":"array"},"name":{"type":"string"}},"type":"object"},"address_api.AddressComponent":{"properties":{"long_name":{"type":"string"},"short_name":{"type":"string"},"types":{"items":{"type":"string"},"type":"array"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"address_api.DetailsRequest":{"properties":{"id":{"type":"string"},"sessiontoken":{"type":"string"}},"type":"object"}}},"paths":{"/address/details":{"post":{"description":"Returns full address details from Google Places API","operationId":"addressDetails","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/address_api.DetailsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get address details","tags":["Address"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/address_api.DetailsRequest"}}},"description":"Details request","required":true}}}}}
```


# Bills

## List bills

> Get a paginated list of bills with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-BillReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/BillReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"}}},"paths":{"/bills":{"get":{"description":"Get a paginated list of bills with optional filtering","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"string"},"description":"Filter by vendor ID","in":"query","name":"vendor_id"},{"schema":{"type":"string"},"description":"Filter by bill status (draft, needs_approval, processing, paid, deleted, failed)","in":"query","name":"status"},{"schema":{"type":"string"},"description":"Filter by bill number","in":"query","name":"bill_number"},{"schema":{"type":"string"},"description":"Filter by bill source (manual, quickbooks, ocr)","in":"query","name":"source"},{"schema":{"type":"boolean"},"description":"Include soft-deleted bills","in":"query","name":"include_deleted"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-BillReply"}}}}},"summary":"List bills","tags":["Bills"]}}}}
```

## Create a bill

> Create a new bill. Optionally set status to "needs\_approval" to skip draft and submit directly for approval.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateBillInput":{"description":"Bill creation request","properties":{"amount":{"type":"number"},"description":{"type":"string"},"due_date":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/BillLineItemInput"},"type":"array"},"number":{"type":"string"},"status":{"type":"string"},"vendor_id":{"type":"string"}},"type":"object"},"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}},"paths":{"/bills":{"post":{"description":"Create a new bill. Optionally set status to \"needs_approval\" to skip draft and submit directly for approval.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a bill","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBillInput"}}},"description":"Bill information","required":true}}}}}
```

## Get a bill

> Get bill details by ID, including line items, payment status, and status history

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}":{"get":{"description":"Get bill details by ID, including line items, payment status, and status history","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get a bill","tags":["Bills"]}}}}
```

## Delete a bill

> Soft-delete a bill. Cannot delete bills in PROCESSING or PAID status.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"DeleteBillReply":{"description":"Bill deletion result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}":{"delete":{"description":"Soft-delete a bill. Cannot delete bills in PROCESSING or PAID status.","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteBillReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Delete a bill","tags":["Bills"]}}}}
```

## Update a bill

> Partially update bill details. Cannot update bills in PROCESSING or PAID status.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"PatchBillInput":{"description":"Bill patch request (partial update)","properties":{"amount":{"type":"number"},"description":{"type":"string"},"due_date":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"$ref":"#/components/schemas/LineItemsUpdateInput"},"vendor_id":{"type":"string"}},"type":"object"},"LineItemsUpdateInput":{"description":"Line items update with optional replacement","properties":{"items":{"items":{"$ref":"#/components/schemas/BillLineItemInput"},"type":"array"},"replace":{"type":"boolean"}},"type":"object"},"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}},"paths":{"/bills/{id}":{"patch":{"description":"Partially update bill details. Cannot update bills in PROCESSING or PAID status.","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Update a bill","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchBillInput"}}},"description":"Bill patch information","required":true}}}}}
```

## Get bill document

> Get the download URL for a bill's attached document

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillDocumentReply":{"description":"Bill document download details","properties":{"download_url":{"type":"string"},"filename":{"type":"string"},"mime_type":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}/document":{"get":{"description":"Get the download URL for a bill's attached document","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillDocumentReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get bill document","tags":["Bills"]}}}}
```

## Update bill pay date

> Set or update the scheduled payment date for a bill

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"UpdatePayDateReply":{"description":"Pay date update result","properties":{"bill_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"UpdatePayDateInput":{"description":"Pay date update request","properties":{"pay_date":{"type":"string"}},"type":"object"}}},"paths":{"/bills/{id}/pay-date":{"post":{"description":"Set or update the scheduled payment date for a bill","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePayDateReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Update bill pay date","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePayDateInput"}}},"description":"Pay date","required":true}}}}}
```

## Reject a bill

> Reject a bill in NEEDS\_APPROVAL status, transitioning it back to DRAFT

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"RejectBillReply":{"description":"Bill rejection result","properties":{"bill_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"RejectBillInput":{"description":"Bill rejection request","properties":{"reason":{"type":"string"}},"type":"object"}}},"paths":{"/bills/{id}/reject":{"post":{"description":"Reject a bill in NEEDS_APPROVAL status, transitioning it back to DRAFT","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectBillReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Reject a bill","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectBillInput"}}},"description":"Rejection reason","required":true}}}}}
```

## Submit bill for approval

> Transition a bill from DRAFT to NEEDS\_APPROVAL status

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"SubmitBillReply":{"description":"Bill submission result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}/submit":{"post":{"description":"Transition a bill from DRAFT to NEEDS_APPROVAL status","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitBillReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Submit bill for approval","tags":["Bills"]}}}}
```

## Bulk delete bills

> Soft-delete multiple bills in a single request

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BulkOperationReply":{"description":"Bulk operation results","properties":{"results":{"items":{"$ref":"#/components/schemas/BulkResultReply"},"type":"array"}},"type":"object"},"BulkResultReply":{"description":"Bulk operation per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"BulkDeleteBillsInput":{"description":"Bulk bill deletion request","properties":{"bill_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"}}},"paths":{"/bills/bulk-delete":{"post":{"description":"Soft-delete multiple bills in a single request","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Bulk delete bills","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteBillsInput"}}},"description":"Bill IDs to delete","required":true}}}}}
```

## Bulk submit bills for approval

> Submit multiple bills for approval in a single request

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BulkOperationReply":{"description":"Bulk operation results","properties":{"results":{"items":{"$ref":"#/components/schemas/BulkResultReply"},"type":"array"}},"type":"object"},"BulkResultReply":{"description":"Bulk operation per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"BulkSubmitBillsInput":{"description":"Bulk bill submission request","properties":{"bill_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"}}},"paths":{"/bills/bulk-submit":{"post":{"description":"Submit multiple bills for approval in a single request","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Bulk submit bills for approval","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSubmitBillsInput"}}},"description":"Bill IDs to submit","required":true}}}}}
```

## Upload bill document with OCR

> Upload a document (PDF, PNG, JPEG), extract data via OCR, and create a bill

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"UploadBillDocumentReply":{"description":"Bill upload result with OCR data","properties":{"bill_id":{"type":"string"},"bill_number":{"type":"string"},"document_path":{"type":"string"},"extracted_data":{"$ref":"#/components/schemas/ExtractedBillDataReply"},"warnings":{"items":{"type":"string"},"type":"array"}},"type":"object"},"ExtractedBillDataReply":{"description":"Extracted bill data from OCR","properties":{"description":{"type":"string"},"due_date":{"type":"string"},"invoice_number":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/ExtractedLineItemReply"},"type":"array"},"total":{"type":"number"},"vendor_email":{"type":"string"},"vendor_name":{"type":"string"}},"type":"object"},"ExtractedLineItemReply":{"description":"Extracted line item from OCR","properties":{"description":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"UploadBillDocumentInput":{"description":"Bill document upload request","properties":{"content":{"type":"string"},"content_type":{"type":"string"},"filename":{"type":"string"}},"type":"object"}}},"paths":{"/bills/upload":{"post":{"description":"Upload a document (PDF, PNG, JPEG), extract data via OCR, and create a bill","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadBillDocumentReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Upload bill document with OCR","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadBillDocumentInput"}}},"description":"Document to upload (base64-encoded content)","required":true}}}}}
```


# Card Form

## Get card form credentials

> Returns the Evervault credentials required to initialize the secure card form

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["checkout:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CardFormCredentials":{"properties":{"app_id":{"type":"string"},"team_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/card-form/credentials":{"get":{"description":"Returns the Evervault credentials required to initialize the secure card form","operationId":"getCardFormCredentials","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardFormCredentials"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get card form credentials","tags":["Card Form"]}}}}
```


# Checkout Auth

## Generate a token for checkout flow

> Generate a token for checkout flow

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["checkout:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"GenerateTokenResponse":{"properties":{"expires_at":{"type":"integer"},"token":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/checkout-auth/init":{"post":{"description":"Generate a token for checkout flow","operationId":"initCheckoutAuth","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTokenResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Generate a token for checkout flow","tags":["CheckoutAuth"]}}}}
```


# Checkout

## Get invoice from checkout token

> Retrieves the invoice associated with the checkout token

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutInvoiceReply":{"description":"Invoice response","properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/checkout/v1/invoice":{"get":{"description":"Retrieves the invoice associated with the checkout token","operationId":"checkoutGetInvoice","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutInvoiceReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get invoice from checkout token","tags":["Checkout"]}}}}
```

## Get invoice PDF link from checkout token

> Retrieves the PDF download link for the invoice associated with the checkout token

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutGetPdfLinkReply":{"description":"PDF link response","properties":{"url":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/checkout/v1/invoice/pdf-link":{"get":{"description":"Retrieves the PDF download link for the invoice associated with the checkout token","operationId":"checkoutGetInvoicePdfLink","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutGetPdfLinkReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get invoice PDF link from checkout token","tags":["Checkout"]}}}}
```

## Get payment methods from checkout token

> Retrieves all payment methods for the customer associated with the checkout token

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutGetPaymentMethodsReply":{"description":"List of payment methods response","properties":{"data":{"items":{"$ref":"#/components/schemas/CheckoutPaymentMethod"},"type":"array"}},"type":"object"},"CheckoutPaymentMethod":{"description":"Payment method information","properties":{"brand":{"type":"string"},"created_at":{"type":"string"},"default":{"type":"boolean"},"exp_month":{"type":"string"},"exp_year":{"type":"string"},"id":{"type":"string"},"last4":{"type":"string"},"type":{"$ref":"#/components/schemas/checkout_api.MethodType"}},"type":"object"},"checkout_api.MethodType":{"enum":["card","ach"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/checkout/v1/payment-methods":{"get":{"description":"Retrieves all payment methods for the customer associated with the checkout token","operationId":"checkoutListPaymentMethods","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutGetPaymentMethodsReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get payment methods from checkout token","tags":["Checkout"]}}}}
```

## Register CVV for a card payment from checkout token

> Register an encrypted CVV token for a specific card. Uses customer\_id and invoice\_id from checkout token.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutCreateCardCvvResponse":{"description":"Create card CVV response","properties":{"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CheckoutCreateCardCvvInput":{"description":"CVV registration information","properties":{"cvv_secret":{"type":"string"},"provider":{"allOf":[{"$ref":"#/components/schemas/checkout_api.CardProvider"}],"enum":["evervault"]}},"type":"object"},"checkout_api.CardProvider":{"enum":["evervault"],"type":"string"}}},"paths":{"/checkout/v1/payment-methods/{card_id}/cvv":{"post":{"description":"Register an encrypted CVV token for a specific card. Uses customer_id and invoice_id from checkout token.","operationId":"checkoutVerifyCvv","parameters":[{"schema":{"type":"string"},"description":"Card ID","in":"path","name":"card_id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateCardCvvResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Register CVV for a card payment from checkout token","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateCardCvvInput"}}},"description":"CVV registration information","required":true}}}}}
```

## Calculate card payment fees

> Calculate payment fees for a specific card payment method using checkout token

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutGetCardPaymentFeesResponse":{"description":"Response containing calculated payment fees for card payments","properties":{"fee_percentage_for_customer":{"type":"string"},"fee_percentage_for_partner":{"type":"string"},"fixed_fee_amount_customer":{"type":"string"},"fixed_fee_amount_partner":{"type":"string"},"relative_fee_amount_customer":{"type":"string"},"relative_fee_amount_partner":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CheckoutGetCardPaymentFeesRequest":{"description":"Request body for calculating card payment fees","properties":{"amount":{"type":"string"},"currency":{"enum":["USD","CAD"],"type":"string"}},"type":"object"}}},"paths":{"/checkout/v1/payment-methods/{card_id}/fees":{"post":{"description":"Calculate payment fees for a specific card payment method using checkout token","operationId":"checkoutGetCardFees","parameters":[{"schema":{"type":"string"},"description":"Card ID","in":"path","name":"card_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutGetCardPaymentFeesResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Calculate card payment fees","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutGetCardPaymentFeesRequest"}}},"description":"Fee calculation request","required":true}}}}}
```

## Create a bank account payment method from checkout token

> Creates a new bank account payment method for the customer associated with the checkout token. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutCreateBankAccountResponse":{"description":"Create bank account response","properties":{"id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CheckoutCreateBankAccountInput":{"description":"Create bank account payment method request body. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.","properties":{"account_data_type":{"enum":["us","ca"],"type":"string"},"ca_account_data":{"$ref":"#/components/schemas/CheckoutCAAccountData"},"custom_name":{"type":"string"},"institution_name":{"type":"string"},"receiver_name":{"type":"string"},"subtype":{"allOf":[{"$ref":"#/components/schemas/checkout_api.AccountSubtype"}],"enum":["checkings","savings"]},"type":{"allOf":[{"$ref":"#/components/schemas/checkout_api.AccountType"}],"enum":["depository"]},"us_account_data":{"$ref":"#/components/schemas/CheckoutUSAccountData"}},"type":"object"},"CheckoutCAAccountData":{"description":"Canadian bank account data","properties":{"account_number":{"type":"string"},"institution_code":{"type":"string"},"transit_number":{"type":"string"}},"type":"object"},"checkout_api.AccountSubtype":{"enum":["checkings","savings"],"type":"string"},"checkout_api.AccountType":{"enum":["depository"],"type":"string"},"CheckoutUSAccountData":{"description":"US bank account data","properties":{"account_number":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}},"paths":{"/checkout/v1/payment-methods/bank":{"post":{"description":"Creates a new bank account payment method for the customer associated with the checkout token. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.","operationId":"checkoutCreateBank","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateBankAccountResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a bank account payment method from checkout token","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateBankAccountInput"}}},"description":"Bank account information","required":true}}}}}
```

## Create a card payment method from checkout token

> Creates a new card payment method for the customer associated with the checkout token

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutCreateCardResponse":{"description":"Create card response","properties":{"id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CheckoutCreateCardInput":{"description":"Create card payment method request body","properties":{"address":{"$ref":"#/components/schemas/CheckoutAddressInput"},"card_provider_token":{"type":"string"},"custom_name":{"type":"string"},"provider":{"allOf":[{"$ref":"#/components/schemas/checkout_api.CardProvider"}],"enum":["evervault"]}},"type":"object"},"CheckoutAddressInput":{"description":"Billing address information","properties":{"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"state_code":{"type":"string"},"street_address":{"type":"string"},"subpremise":{"type":"string"}},"type":"object"},"checkout_api.CardProvider":{"enum":["evervault"],"type":"string"}}},"paths":{"/checkout/v1/payment-methods/card":{"post":{"description":"Creates a new card payment method for the customer associated with the checkout token","operationId":"checkoutCreateCard","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateCardResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a card payment method from checkout token","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateCardInput"}}},"description":"Card information","required":true}}}}}
```

## Create a payment from checkout token

> Creates a payment for the invoice associated with the checkout token. Customer ID and invoice ID are extracted from the token.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer token authentication for checkout endpoints. Pass the token as \"Bearer {token}\" in the Authorization header.","in":"header","name":"Authorization","type":"apiKey"}},"schemas":{"CheckoutCreatePaymentResponse":{"description":"Create payment response","properties":{"message":{"type":"string"},"status":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CheckoutCreatePaymentInput":{"description":"Create payment request body","properties":{"amount":{"type":"string"},"idempotency_key":{"type":"string"},"payment_date":{"type":"string"},"payment_method":{"enum":["card","standard_ach"],"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"}}},"paths":{"/checkout/v1/payments":{"post":{"description":"Creates a payment for the invoice associated with the checkout token. Customer ID and invoice ID are extracted from the token.","operationId":"checkoutCreatePayment","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreatePaymentResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a payment from checkout token","tags":["Checkout"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreatePaymentInput"}}},"description":"Payment information","required":true}}}}}
```


# Customers

## List customers

> Get a paginated list of customers with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-CustomerReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CustomerReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"}}},"paths":{"/customers":{"get":{"description":"Get a paginated list of customers with optional filtering","operationId":"listCustomers","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Specifies the cursor after which to start returning results. For the first page, this should be left empty. For subsequent pages, use the value of the end_cursor field from the previous response.","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Specifies the cursor before which to return results. Use this to paginate backwards. For example, to load the previous page, provide the value of the start_cursor field from the last response.","in":"query","name":"before"},{"schema":{"type":"string"},"description":"Filter by creation date start (RFC3339 format)","in":"query","name":"created_at_start"},{"schema":{"type":"string"},"description":"Filter by creation date end (RFC3339 format)","in":"query","name":"created_at_end"},{"schema":{"type":"string"},"description":"Filter by customer name","in":"query","name":"company_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-CustomerReply"}}}}},"summary":"List customers","tags":["Customers"]}}}}
```

## Create a customer

> Create a new customer with the provided information

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateCustomerInput":{"description":"Customer information","properties":{"city":{"type":"string"},"country":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"}}},"paths":{"/customers":{"post":{"description":"Create a new customer with the provided information","operationId":"createCustomer","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a customer","tags":["Customers"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerInput"}}},"description":"Customer information","required":true}}}}}
```

## Get a customer

> Get customer details by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/customers/{id}":{"get":{"description":"Get customer details by ID","operationId":"getCustomer","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get a customer","tags":["Customers"]}}}}
```

## Archive a customer

> Archive a customer

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/customers/{id}":{"delete":{"description":"Archive a customer","operationId":"archiveCustomer","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Archive a customer","tags":["Customers"]}}}}
```

## Patch customer

> Patch customer information (company, legal name, EIN, street address, sub-premise, city, state, postal code, country)

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"PatchCustomerRequest":{"description":"Request body for patching customer information","properties":{"city":{"type":"string"},"country":{"type":"string"},"ein":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"}}},"paths":{"/customers/{id}":{"patch":{"description":"Patch customer information (company, legal name, EIN, street address, sub-premise, city, state, postal code, country)","operationId":"updateCustomer","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Patch customer","tags":["Customers"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchCustomerRequest"}}},"description":"Customer patch information","required":true}}}}}
```

## List payment methods

> Get payment methods associated with a customer

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"GetPaymentMethodsReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PaymentMethod"},"type":"array"}},"type":"object"},"PaymentMethod":{"properties":{"brand":{"type":"string"},"created_at":{"type":"string"},"default":{"type":"boolean"},"exp_month":{"type":"string"},"exp_year":{"type":"string"},"id":{"type":"string"},"last4":{"type":"string"},"type":{"$ref":"#/components/schemas/MethodType"}},"type":"object"},"MethodType":{"enum":["card","ach"],"type":"string"}}},"paths":{"/customers/{id}/payment-methods":{"get":{"description":"Get payment methods associated with a customer","operationId":"listPaymentMethods","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentMethodsReply"}}}}},"summary":"List payment methods","tags":["Customers"]}}}}
```

## Get payment method by ID

> Get a specific payment method associated with a customer by payment method ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaymentMethod":{"properties":{"brand":{"type":"string"},"created_at":{"type":"string"},"default":{"type":"boolean"},"exp_month":{"type":"string"},"exp_year":{"type":"string"},"id":{"type":"string"},"last4":{"type":"string"},"type":{"$ref":"#/components/schemas/MethodType"}},"type":"object"},"MethodType":{"enum":["card","ach"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/customers/{id}/payment-methods/{method_id}":{"get":{"description":"Get a specific payment method associated with a customer by payment method ID","operationId":"getPaymentMethod","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true},{"schema":{"type":"string"},"description":"Payment Method ID","in":"path","name":"method_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethod"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get payment method by ID","tags":["Customers"]}}}}
```

## Restore a customer

> Restore a customer

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/customers/{id}/restore":{"post":{"description":"Restore a customer","operationId":"restoreCustomer","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Restore a customer","tags":["Customers"]}}}}
```

## List customer users

> Get a paginated list of users from a customer

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-CustomerUser":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CustomerUser"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"CustomerUser":{"properties":{"created_at":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string"},"job_title":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"}},"type":"object"}}},"paths":{"/customers/{id}/users":{"get":{"description":"Get a paginated list of users from a customer","operationId":"listCustomerUsers","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Specifies the cursor after which to start returning results. For the first page, this should be left empty. For subsequent pages, use the value of the end_cursor field from the previous response.","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Specifies the cursor before which to return results. Use this to paginate backwards. For example, to load the previous page, provide the value of the start_cursor field from the last response.","in":"query","name":"before"},{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-CustomerUser"}}}}},"summary":"List customer users","tags":["Customers"]}}}}
```

## Create a customer user

> Create a new customer user with the provided information

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CustomerUser":{"properties":{"created_at":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string"},"job_title":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateCustomerUserInput":{"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}},"type":"object"}}},"paths":{"/customers/{id}/users":{"post":{"description":"Create a new customer user with the provided information","operationId":"createCustomerUser","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUser"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a customer user","tags":["Customers"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerUserInput"}}},"description":"Customer user information","required":true}}}}}
```


# Payment Methods

## Register CVV for a card payment

> Register an encrypted CVV token for a specific card and invoice

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CreateCardCvvResponse":{"description":"Create card CVV response","properties":{"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateCardCvvInput":{"description":"CVV registration information","properties":{"cvv_secret":{"type":"string"},"product_id":{"type":"string"},"product_type":{"enum":["invoice"],"type":"string"},"provider":{"enum":["evervault"],"type":"string"}},"type":"object"}}},"paths":{"/customers/{id}/payment-methods/{card_id}/cvv":{"post":{"description":"Register an encrypted CVV token for a specific card and invoice","operationId":"verifyCardCvv","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true},{"schema":{"type":"string"},"description":"Card ID","in":"path","name":"card_id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardCvvResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Register CVV for a card payment","tags":["PaymentMethods"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardCvvInput"}}},"description":"CVV registration information","required":true}}}}}
```

## Calculate card payment fees

> Calculate payment fees for a specific card payment method

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["customers:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"GetCardPaymentFeesResponse":{"description":"Response containing calculated payment fees for card payments","properties":{"fee_percentage_for_customer":{"type":"string"},"fee_percentage_for_partner":{"type":"string"},"fixed_fee_amount_customer":{"type":"string"},"fixed_fee_amount_partner":{"type":"string"},"relative_fee_amount_customer":{"type":"string"},"relative_fee_amount_partner":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"GetCardPaymentFeesRequest":{"description":"Request body for calculating card payment fees","properties":{"amount":{"type":"string"},"currency":{"enum":["USD","CAD"],"type":"string"}},"type":"object"}}},"paths":{"/customers/{id}/payment-methods/{card_id}/fees":{"post":{"description":"Calculate payment fees for a specific card payment method","operationId":"getCardPaymentFees","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true},{"schema":{"type":"string"},"description":"Card ID","in":"path","name":"card_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCardPaymentFeesResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Calculate card payment fees","tags":["PaymentMethods"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCardPaymentFeesRequest"}}},"description":"Fee calculation request","required":true}}}}}
```

## Delete a customer's payment method

> Delete this payment method

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"DeletePaymentMethodResponse":{"description":"Delete a payment method","properties":{"response":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/customers/{id}/payment-methods/{method_id}":{"delete":{"description":"Delete this payment method","operationId":"deletePaymentMethod","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true},{"schema":{"type":"string"},"description":"Payment Method ID","in":"path","name":"method_id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePaymentMethodResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Delete a customer's payment method","tags":["PaymentMethods"]}}}}
```

## Change a customer's default payment method

> Change the customer's default payment method to this one

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"ChangeDefaultResponse":{"description":"Change default method response","properties":{"response":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/customers/{id}/payment-methods/{method_id}/default":{"patch":{"description":"Change the customer's default payment method to this one","operationId":"setDefaultPaymentMethod","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true},{"schema":{"type":"string"},"description":"Payment Method ID","in":"path","name":"method_id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeDefaultResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Change a customer's default payment method","tags":["PaymentMethods"]}}}}
```

## Create a customer bank account

> Create a new bank account with the provided information. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CreateBankAccountResponse":{"description":"Create bank account response","properties":{"id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateBankAccountInput":{"description":"Bank account information. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.","properties":{"account_data_type":{"enum":["us","ca"],"type":"string"},"ca_account_data":{"$ref":"#/components/schemas/payment_methods_api.CAAccountData"},"custom_name":{"type":"string"},"institution_name":{"type":"string"},"receiver_name":{"type":"string"},"subtype":{"enum":["checkings","savings"],"type":"string"},"type":{"enum":["depository"],"type":"string"},"us_account_data":{"$ref":"#/components/schemas/payment_methods_api.USAccountData"}},"type":"object"},"payment_methods_api.CAAccountData":{"properties":{"account_number":{"type":"string"},"institution_code":{"type":"string"},"transit_number":{"type":"string"}},"type":"object"},"payment_methods_api.USAccountData":{"properties":{"account_number":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}},"paths":{"/customers/{id}/payment-methods/bank":{"post":{"description":"Create a new bank account with the provided information. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.","operationId":"createBankPaymentMethod","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBankAccountResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a customer bank account","tags":["PaymentMethods"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBankAccountInput"}}},"description":"BankAccount information","required":true}}}}}
```

## Create a customer card

> Create a new card with the provided tokenized information

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CreateCardResponse":{"description":"Create card response","properties":{"id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateCardInput":{"description":"Tokenized card information","properties":{"address":{"$ref":"#/components/schemas/AddressInput"},"card_provider_token":{"type":"string"},"custom_name":{"type":"string"},"provider":{"enum":["evervault"],"type":"string"}},"type":"object"},"AddressInput":{"description":"Address information","properties":{"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"state_code":{"type":"string"},"street_address":{"type":"string"},"subpremise":{"type":"string"}},"type":"object"}}},"paths":{"/customers/{id}/payment-methods/card":{"post":{"description":"Create a new card with the provided tokenized information","operationId":"createCardPaymentMethod","parameters":[{"schema":{"type":"string"},"description":"Customer ID","in":"path","name":"id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a customer card","tags":["PaymentMethods"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCardInput"}}},"description":"Card information","required":true}}}}}
```


# Invoices

## List invoices

> Get a paginated list of invoices with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-Invoice":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Invoice"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"Invoice":{"properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"last_notification_at":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"},"memo":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/invoices":{"get":{"description":"Get a paginated list of invoices with optional filtering","operationId":"listInvoices","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Specifies the cursor after which to start returning results. For the first page, this should be left empty. For subsequent pages, use the value of the end_cursor field from the previous response.","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Specifies the cursor before which to return results. Use this to paginate backwards. For example, to load the previous page, provide the value of the start_cursor field from the last response.","in":"query","name":"before"},{"schema":{"type":"string"},"description":"Filter by creation date start (RFC3339 format)","in":"query","name":"created_at_start"},{"schema":{"type":"string"},"description":"Filter by creation date end (RFC3339 format)","in":"query","name":"created_at_end"},{"schema":{"type":"string"},"description":"Filter by due date start (RFC3339 format)","in":"query","name":"due_date_start"},{"schema":{"type":"string"},"description":"Filter by due date end (RFC3339 format)","in":"query","name":"due_date_end"},{"schema":{"type":"string"},"description":"Filter by customer ID","in":"query","name":"customer_id"},{"schema":{"type":"string"},"description":"Filter by invoice number","in":"query","name":"invoice_number"},{"schema":{"type":"string","enum":["UPCOMING","OVERDUE","RECEIVED","PAID","ARCHIVED"]},"description":"Filter by invoice status","in":"query","name":"status"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-Invoice"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"List invoices","tags":["Invoices"]}}}}
```

## Create an invoice

> Create a new invoice with line items

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"Invoice":{"properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"last_notification_at":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"},"memo":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateInvoiceInput":{"properties":{"customer_id":{"type":"string"},"due_date":{"description":"Due date in YYYY-MM-DD format. If omitted, defaults to the current date from invoice creation.","type":"string"},"exclude_from_autopay":{"description":"When true, this invoice is excluded from Autopay at creation time. Use this\nwhen your integration pays the invoice synchronously via API and you want to\nguarantee Autopay never charges the same invoice. Defaults to false.","type":"boolean"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"}},"type":"object"}}},"paths":{"/invoices":{"post":{"description":"Create a new invoice with line items","operationId":"createInvoice","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create an invoice","tags":["Invoices"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceInput"}}},"description":"Invoice information","required":true}}}}}
```

## Get an invoice

> Get invoice details by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"Invoice":{"properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"last_notification_at":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"},"memo":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/invoices/{id}":{"get":{"description":"Get invoice details by ID","operationId":"getInvoice","parameters":[{"schema":{"type":"string"},"description":"Invoice ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get an invoice","tags":["Invoices"]}}}}
```

## Archive an invoice

> Archive an invoice

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"Invoice":{"properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"last_notification_at":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"},"memo":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/invoices/{id}":{"delete":{"description":"Archive an invoice","operationId":"archiveInvoice","parameters":[{"schema":{"type":"string"},"description":"Invoice ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Archive an invoice","tags":["Invoices"]}}}}
```

## Get hosted payment link for invoice

> Get a payment link for the specified invoice

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"GetPaymentLinkData":{"properties":{"url":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/invoices/{id}/payment-link":{"get":{"description":"Get a payment link for the specified invoice","operationId":"getInvoicePaymentLink","parameters":[{"schema":{"type":"string"},"description":"Invoice ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPaymentLinkData"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get hosted payment link for invoice","tags":["Invoices"]}}}}
```

## Upload invoice PDF

> Upload the original invoice PDF (max 10 MB). Provide exactly one of \`content\` (base64-encoded bytes) or \`url\` (a public HTTPS link we download once, at upload time). Both variants behave identically once accepted: we store our own copy of the bytes and never read the link again, so the document keeps serving even if your host later goes away, and an unreachable link fails this request outright rather than degrading for a customer later. \*\*Updates are push-only:\*\* we never re-read the link or poll for changes, so a PDF updated in your system is not reflected here until you send this request again — with fresh \`content\`, or with the \`url\` (the same url is fine; we re-download it at that moment). Each upload replaces the previous PDF; last write wins. Only invoices synced from an accounting integration accept a PDF: an invoice created through \`POST /invoices\` has no original document from your system, and returns \`422 unsupported\_invoice\`.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"UploadInvoicePdfReply":{"properties":{"path":{"description":"Path is the stored location of the PDF, for both the content and url\nvariants. It is an opaque identifier, not a downloadable link — to retrieve\nthe document, call GET /invoices/{id}/pdf-link for a signed URL.","type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"UploadInvoicePdfInput":{"description":"Invoice PDF upload request. Provide exactly one of content (base64-encoded bytes) or url (public HTTPS link to the PDF, downloaded once at upload time and stored). Either way we keep our own copy and never read the link again, so send the request again to publish an updated document.","properties":{"content":{"description":"The PDF document as standard base64 (RFC 4648). Must decode to a valid PDF\n(the file must start with the PDF header) of at most 10 MB. Mutually\nexclusive with url.","type":"string"},"url":{"description":"A public, absolute HTTPS link to the PDF. Fetched exactly once, at upload\ntime; we store our own copy and never read the link again — if the document\nbehind it changes, re-send this request to publish the new version. HTTP links,\nredirects to non-HTTPS locations, and links resolving to private addresses\nare rejected. The response must be a PDF of at most 10 MB. Mutually\nexclusive with content.","type":"string"}},"type":"object"}}},"paths":{"/invoices/{id}/pdf":{"post":{"description":"Upload the original invoice PDF (max 10 MB). Provide exactly one of `content` (base64-encoded bytes) or `url` (a public HTTPS link we download once, at upload time). Both variants behave identically once accepted: we store our own copy of the bytes and never read the link again, so the document keeps serving even if your host later goes away, and an unreachable link fails this request outright rather than degrading for a customer later. **Updates are push-only:** we never re-read the link or poll for changes, so a PDF updated in your system is not reflected here until you send this request again — with fresh `content`, or with the `url` (the same url is fine; we re-download it at that moment). Each upload replaces the previous PDF; last write wins. Only invoices synced from an accounting integration accept a PDF: an invoice created through `POST /invoices` has no original document from your system, and returns `422 unsupported_invoice`.","operationId":"uploadInvoicePdf","parameters":[{"schema":{"type":"string"},"description":"Invoice ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"`path` is the stored location of the PDF, for both variants. It is an opaque identifier — retrieve the document via GET /invoices/{id}/pdf-link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadInvoicePdfReply"}}}},"400":{"description":"Invalid request: both or neither of `content`/`url` provided; `content` is not valid base64 or does not decode to a PDF; `url` is not HTTPS, redirects to a non-HTTPS location, is unreachable (non-2xx), resolves to a blocked address, exceeds the redirect limit, times out, or does not return a PDF","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Invoice not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"413":{"description":"The PDF exceeds the 10 MB limit (applies to both the decoded `content` bytes and the `url` response body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"The invoice is not synced from an accounting integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Upload invoice PDF","tags":["Invoices"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadInvoicePdfInput"}}},"description":"PDF to upload: exactly one of content (base64-encoded bytes) or url (public HTTPS link, downloaded once at upload time)","required":true}}}}}
```

## Get invoice PDF link

> Get a signed PDF URL for the specified invoice

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"GetPdfLinkData":{"properties":{"url":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/invoices/{id}/pdf-link":{"get":{"description":"Get a signed PDF URL for the specified invoice","operationId":"getInvoicePdfLink","parameters":[{"schema":{"type":"string"},"description":"Invoice ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPdfLinkData"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get invoice PDF link","tags":["Invoices"]}}}}
```

## Restore an invoice

> Restore an invoice

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["invoices:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"Invoice":{"properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"last_notification_at":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"},"memo":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/invoices/{id}/restore":{"post":{"description":"Restore an invoice","operationId":"restoreInvoice","parameters":[{"schema":{"type":"string"},"description":"Invoice ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Restore an invoice","tags":["Invoices"]}}}}
```


# OAuth

## Get OAuth2 access token

> OAuth2 client credentials flow endpoint. Generate a new access token using client credentials. The "client\_id" (username) and "client\_secret" (password) must be passed as Basic Auth credentials. Ex: Authorization: Basic Base64Encode(client\_id:client\_secret). The returned access token should be used as Bearer token for subsequent API calls: Authorization: Bearer {access\_token}

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic"}},"schemas":{"TokenResponse":{"description":"OAuth2 access token response structure containing the bearer token and expiration details","properties":{"access_token":{"description":"@Description The OAuth2 access token for API authentication - use as Bearer token in Authorization header\n@Example 580defdbe1d21e0001c67e5c2a0a6c98ba8b4a059dc5825388501574","type":"string"},"expires_in":{"description":"@Description Token expiration time in seconds from issuance\n@Example 3600","type":"integer"},"token_type":{"description":"@Description OAuth2 token type - always \"bearer\" for this implementation\n@Example bearer","type":"string"}},"type":"object"}}},"paths":{"/oauth/token":{"post":{"description":"OAuth2 client credentials flow endpoint. Generate a new access token using client credentials. The \"client_id\" (username) and \"client_secret\" (password) must be passed as Basic Auth credentials. Ex: Authorization: Basic Base64Encode(client_id:client_secret). The returned access token should be used as Bearer token for subsequent API calls: Authorization: Bearer {access_token}","operationId":"createOAuthToken","responses":{"200":{"description":"Successfully generated OAuth2 access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"403":{"description":"Invalid credentials","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object"}}}}},"summary":"Get OAuth2 access token","tags":["OAuth"],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"grant_type":{"type":"string","description":"OAuth2 grant type - must be 'client_credentials'"}},"required":["grant_type"]}}}}}}}}
```


# Payments

## List payments

> Get a paginated list of payments with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-Payment":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Payment"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"Payment":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PaymentFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PaymentFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/payments":{"get":{"description":"Get a paginated list of payments with optional filtering","operationId":"listPayments","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Specifies the cursor after which to start returning results. For the first page, this should be left empty. For subsequent pages, use the value of the end_cursor field from the previous response.","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Specifies the cursor before which to return results. Use this to paginate backwards. For example, to load the previous page, provide the value of the start_cursor field from the last response.","in":"query","name":"before"},{"schema":{"type":"string","enum":["payment","refund","chargeback"]},"description":"Filter by payment type","in":"query","name":"type"},{"schema":{"type":"string","enum":["creating","processing","scheduled","succeeded","canceled","failed","pending"]},"description":"Filter by payment status","in":"query","name":"status"},{"schema":{"type":"string"},"description":"Filter by customer ID","in":"query","name":"customer_id"},{"schema":{"type":"string"},"description":"Filter by invoice ID","in":"query","name":"invoice_id"},{"schema":{"type":"string","enum":["card","standard_ach","same_day_ach","manual"]},"description":"Filter by payment method","in":"query","name":"payment_method"},{"schema":{"type":"string"},"description":"Filter by creation date start (RFC3339 format)","in":"query","name":"created_at_start"},{"schema":{"type":"string"},"description":"Filter by creation date end (RFC3339 format)","in":"query","name":"created_at_end"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-Payment"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"List payments","tags":["Payments"]}}}}
```

## Create payment

> Create a single payment to charge an invoice.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreatePaymentRequest":{"description":"Request body for creating a payment","properties":{"amount":{"type":"string"},"customer_id":{"type":"string"},"idempotency_key":{"type":"string"},"invoice_id":{"type":"string"},"payment_date":{"type":"string"},"payment_method":{"description":"@enum card,standard_ach","enum":["card","standard_ach"],"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"}}},"paths":{"/payments":{"post":{"description":"Create a single payment to charge an invoice.","operationId":"createPayment","responses":{"201":{"description":"Payment is being processed!","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create payment","tags":["Payments"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}},"description":"Payment request details","required":true}}}}}
```

## Get payment by ID

> Retrieve detailed information about a specific payment

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"Payment":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PaymentFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PaymentFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/payments/{id}":{"get":{"description":"Retrieve detailed information about a specific payment","operationId":"getPayment","parameters":[{"schema":{"type":"string"},"description":"Payment ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get payment by ID","tags":["Payments"]}}}}
```


# Payment Request

## Generate a new payment request

> Create a new payment request with a specified amount, redirecting to the given url

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaymentRequest":{"properties":{"id":{"type":"string"},"redirect_url":{"type":"string"},"reference_id":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"PaymentRequestInput":{"properties":{"amount":{"type":"string"},"redirect_url":{"type":"string"},"reference_id":{"type":"string"}},"type":"object"}}},"paths":{"/payments/request":{"post":{"description":"Create a new payment request with a specified amount, redirecting to the given url","operationId":"createPaymentRequest","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Generate a new payment request","tags":["Payment request"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestInput"}}},"description":"Payment request information","required":true}}}}}
```

## Retrieve a payment request by id

> Retrieves a payment request, together with its current status

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payments:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaymentRequest":{"properties":{"id":{"type":"string"},"redirect_url":{"type":"string"},"reference_id":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/payments/request/{id}":{"get":{"description":"Retrieves a payment request, together with its current status","operationId":"getPaymentRequest","parameters":[{"schema":{"type":"string"},"description":"ID of the payment request","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Retrieve a payment request by id","tags":["Payment request"]}}}}
```


# Payouts

## List payouts

> Get a paginated list of payouts with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payouts:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-Payout":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Payout"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"Payout":{"properties":{"arrival_date":{"type":"string"},"created_at":{"type":"string"},"customer_id":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PayoutFee"},"type":"array"},"id":{"type":"string"},"status":{"$ref":"#/components/schemas/PayoutStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PayoutFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/PayoutFeeType"}},"type":"object"},"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"},"PayoutStatus":{"enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/payouts":{"get":{"description":"Get a paginated list of payouts with optional filtering","operationId":"listPayouts","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Specifies the cursor after which to start returning results. For the first page, this should be left empty. For subsequent pages, use the value of the end_cursor field from the previous response.","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Specifies the cursor before which to return results. Use this to paginate backwards. For example, to load the previous page, provide the value of the start_cursor field from the last response.","in":"query","name":"before"},{"schema":{"type":"string","enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"]},"description":"Filter by payout status","in":"query","name":"status"},{"schema":{"type":"string"},"description":"Filter by customer ID","in":"query","name":"customer_id"},{"schema":{"type":"string"},"description":"Filter by invoice ID","in":"query","name":"invoice_id"},{"schema":{"type":"string"},"description":"Filter by start date (RFC3339 format)","in":"query","name":"start_date"},{"schema":{"type":"string"},"description":"Filter by end date (RFC3339 format)","in":"query","name":"end_date"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-Payout"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"List payouts","tags":["Payouts"]}}}}
```

## Get a payout

> Get payout details by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payouts:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"Payout":{"properties":{"arrival_date":{"type":"string"},"created_at":{"type":"string"},"customer_id":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PayoutFee"},"type":"array"},"id":{"type":"string"},"status":{"$ref":"#/components/schemas/PayoutStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PayoutFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/PayoutFeeType"}},"type":"object"},"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"},"PayoutStatus":{"enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/payouts/{id}":{"get":{"description":"Get payout details by ID","operationId":"getPayout","parameters":[{"schema":{"type":"string"},"description":"Payout ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get a payout","tags":["Payouts"]}}}}
```

## Get a payout transactions

> Get payout transactions by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["payouts:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"GetTransactionsReply":{"properties":{"payout":{"$ref":"#/components/schemas/Payout"},"transactions":{"items":{"$ref":"#/components/schemas/Transaction"},"type":"array"}},"type":"object"},"Payout":{"properties":{"arrival_date":{"type":"string"},"created_at":{"type":"string"},"customer_id":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PayoutFee"},"type":"array"},"id":{"type":"string"},"status":{"$ref":"#/components/schemas/PayoutStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PayoutFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/PayoutFeeType"}},"type":"object"},"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"},"PayoutStatus":{"enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"],"type":"string"},"Transaction":{"properties":{"description":{"type":"string"},"direction":{"$ref":"#/components/schemas/TransactionDirection"},"failure_reason":{"type":"string"},"id":{"type":"string"},"method":{"$ref":"#/components/schemas/TransactionMethod"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"TransactionDirection":{"enum":["credit","debit"],"type":"string"},"TransactionMethod":{"enum":["standard_ach","same_day_ach","manual","card","wire","rtp"],"type":"string"},"TransactionStatus":{"enum":["created","processing","succeeded","canceled","charged","failed","chargeback","refunded"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/payouts/{id}/transactions":{"get":{"description":"Get payout transactions by ID","operationId":"listPayoutTransactions","parameters":[{"schema":{"type":"string"},"description":"Payout ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTransactionsReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get a payout transactions","tags":["Payouts"]}}}}
```


# Preferences

## Get partner theme preferences

> Get the partner's theme customization including colors and logo

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":[]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"GetThemeReply":{"properties":{"partner_name":{"type":"string"},"theme":{"$ref":"#/components/schemas/ThemePreferences"}},"type":"object"},"ThemePreferences":{"properties":{"color":{"type":"string"},"logo_url":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/preferences/theme":{"get":{"description":"Get the partner's theme customization including colors and logo","operationId":"getPartnerTheme","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetThemeReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get partner theme preferences","tags":["Preferences"]}}}}
```


# Refunds

## List refunds

> Get a paginated list of refunds with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["refunds:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-RefundReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RefundReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"RefundReply":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/RefundFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"RefundFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/refunds":{"get":{"description":"Get a paginated list of refunds with optional filtering","operationId":"listRefunds","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Specifies the cursor after which to start returning results. For the first page, this should be left empty. For subsequent pages, use the value of the end_cursor field from the previous response.","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Specifies the cursor before which to return results. Use this to paginate backwards. For example, to load the previous page, provide the value of the start_cursor field from the last response.","in":"query","name":"before"},{"schema":{"type":"string"},"description":"Filter by customer ID","in":"query","name":"customer_id"},{"schema":{"type":"string"},"description":"Filter by invoice ID","in":"query","name":"invoice_id"},{"schema":{"type":"string","enum":["card","standard_ach","same_day_ach","manual"]},"description":"Filter by payment method","in":"query","name":"payment_method"},{"schema":{"type":"string"},"description":"Filter by creation date start (RFC3339 format)","in":"query","name":"created_at_start"},{"schema":{"type":"string"},"description":"Filter by creation date end (RFC3339 format)","in":"query","name":"created_at_end"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-RefundReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"List refunds","tags":["Refunds"]}}}}
```

## Create refund

> Create a full refund for a payment. Partial refunds are not supported.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["refunds:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateRefundRequest":{"description":"Request body for creating a refund","properties":{"amount":{"type":"string"},"idempotency_key":{"type":"string"},"payment_id":{"type":"string"},"reason":{"$ref":"#/components/schemas/RefundReasonDetail"}},"type":"object"},"RefundReasonDetail":{"description":"The reason for the refund. If 'Other', please specify the reason in more detail.","properties":{"description":{"type":"string"},"type":{"allOf":[{"$ref":"#/components/schemas/refunds_api.RefundType"}],"description":"@enum Customer Request, Duplicate, Fraud, Other"}},"type":"object"},"refunds_api.RefundType":{"enum":["Customer Request","Duplicate","Fraud","Other"],"type":"string"}}},"paths":{"/refunds":{"post":{"description":"Create a full refund for a payment. Partial refunds are not supported.","operationId":"createRefund","responses":{"201":{"description":"Refund is being processed!","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create refund","tags":["Refunds"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundRequest"}}},"description":"Refund details","required":true}}}}}
```

## Get refund by ID

> Retrieve detailed information about a specific refund

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["refunds:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"RefundReply":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/RefundFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"RefundFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/refunds/{id}":{"get":{"description":"Retrieve detailed information about a specific refund","operationId":"getRefund","parameters":[{"schema":{"type":"string"},"description":"Refund ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get refund by ID","tags":["Refunds"]}}}}
```


# Vendor Payments

## Initiate vendor payment

> Initiate payment for one or more bills. Bills must have pay\_date set (422 if null).

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CreateVendorPaymentReply":{"description":"Vendor payment creation results","properties":{"results":{"items":{"$ref":"#/components/schemas/CreateVendorPaymentResultReply"},"type":"array"}},"type":"object"},"CreateVendorPaymentResultReply":{"description":"Vendor payment creation per-item result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateVendorPaymentInput":{"description":"Vendor payment creation request","properties":{"idempotency_key":{"type":"string"},"items":{"items":{"$ref":"#/components/schemas/PaymentItemInput"},"type":"array"}},"type":"object"},"PaymentItemInput":{"description":"Payment item for vendor payment creation","properties":{"bill_id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedInput"}},"type":"object"},"PaymentSpeedInput":{"description":"Payment speed enum: standard, next_day, same_day, instant","enum":["standard","next_day","same_day","instant"],"type":"string"}}},"paths":{"/vendor-payments":{"post":{"description":"Initiate payment for one or more bills. Bills must have pay_date set (422 if null).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendorPaymentReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Initiate vendor payment","tags":["Vendor Payments"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendorPaymentInput"}}},"description":"Payment items","required":true}}}}}
```

## Retry failed vendor payment

> Retry the last failed funding attempt for a bill

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"RetryVendorPaymentReply":{"description":"Vendor payment retry result","properties":{"bill_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendor-payments/{bill_id}/retry":{"post":{"description":"Retry the last failed funding attempt for a bill","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"bill_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryVendorPaymentReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Retry failed vendor payment","tags":["Vendor Payments"]}}}}
```

## Bulk cancel vendor payments

> Cancel multiple vendor payments in a single request

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BulkCancelVendorPaymentsReply":{"description":"Bulk vendor payment cancellation results","properties":{"results":{"items":{"$ref":"#/components/schemas/BulkCancelResultReply"},"type":"array"}},"type":"object"},"BulkCancelResultReply":{"description":"Bulk cancel per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"BulkCancelVendorPaymentsInput":{"description":"Bulk vendor payment cancellation request","properties":{"items":{"items":{"$ref":"#/components/schemas/BulkCancelItemInput"},"type":"array"}},"type":"object"},"BulkCancelItemInput":{"description":"Bulk cancel item","properties":{"bill_id":{"type":"string"},"payment_id":{"type":"string"}},"type":"object"}}},"paths":{"/vendor-payments/bulk-cancel":{"post":{"description":"Cancel multiple vendor payments in a single request","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCancelVendorPaymentsReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Bulk cancel vendor payments","tags":["Vendor Payments"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCancelVendorPaymentsInput"}}},"description":"Payments to cancel","required":true}}}}}
```

## Cancel vendor payment

> Cancel a single vendor payment

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CancelVendorPaymentReply":{"description":"Vendor payment cancellation result","properties":{"payment_id":{"type":"string"},"status":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CancelVendorPaymentInput":{"description":"Vendor payment cancellation request","properties":{"bill_id":{"type":"string"},"payment_id":{"type":"string"}},"type":"object"}}},"paths":{"/vendor-payments/cancel":{"post":{"description":"Cancel a single vendor payment","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelVendorPaymentReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Cancel vendor payment","tags":["Vendor Payments"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelVendorPaymentInput"}}},"description":"Payment to cancel","required":true}}}}}
```


# Vendors

## List vendors

> Get a paginated list of vendors with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-VendorReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/VendorReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"}}},"paths":{"/vendors":{"get":{"description":"Get a paginated list of vendors with optional filtering","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"boolean"},"description":"Filter by active status","in":"query","name":"is_active"},{"schema":{"type":"string"},"description":"Filter by origin (manual, quickbooks, ocr)","in":"query","name":"origin"},{"schema":{"type":"string"},"description":"Filter by vendor name","in":"query","name":"vendor_name"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-VendorReply"}}}}},"summary":"List vendors","tags":["Vendors"]}}}}
```

## Create a vendor

> Create a new vendor with the provided information. Optionally include bank account details.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateVendorInput":{"description":"Vendor creation request","properties":{"bank_account":{"$ref":"#/components/schemas/BankAccountInput"},"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"}},"type":"object"},"BankAccountInput":{"description":"Bank account details for vendor creation","properties":{"account_number":{"type":"string"},"account_type":{"type":"string"},"bank_name":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}},"paths":{"/vendors":{"post":{"description":"Create a new vendor with the provided information. Optionally include bank account details.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a vendor","tags":["Vendors"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendorInput"}}},"description":"Vendor information","required":true}}}}}
```

## Get a vendor

> Get vendor details by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}":{"get":{"description":"Get vendor details by ID","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get a vendor","tags":["Vendors"]}}}}
```

## Update a vendor

> Partially update vendor details

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"PatchVendorInput":{"description":"Vendor patch request (partial update)","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"}},"type":"object"}}},"paths":{"/vendors/{id}":{"patch":{"description":"Partially update vendor details","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Update a vendor","tags":["Vendors"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchVendorInput"}}},"description":"Vendor patch information","required":true}}}}}
```

## Get vendor bank account

> Get the vendor's bank account details (masked)

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BankAccountReply":{"description":"Vendor bank account details (masked)","properties":{"account_mask":{"type":"string"},"account_type":{"$ref":"#/components/schemas/AccountTypeEnum"},"bank_name":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"},"AccountTypeEnum":{"description":"Bank account type enum","enum":["checking","savings"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/bank-account":{"get":{"description":"Get the vendor's bank account details (masked)","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccountReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get vendor bank account","tags":["Vendors"]}}}}
```

## Add or update vendor bank account

> Create or replace the vendor's bank account

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BankAccountReply":{"description":"Vendor bank account details (masked)","properties":{"account_mask":{"type":"string"},"account_type":{"$ref":"#/components/schemas/AccountTypeEnum"},"bank_name":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"},"AccountTypeEnum":{"description":"Bank account type enum","enum":["checking","savings"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"UpsertBankAccountInput":{"description":"Bank account upsert request","properties":{"account_number":{"type":"string"},"account_type":{"type":"string"},"bank_name":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}},"paths":{"/vendors/{id}/bank-account":{"post":{"description":"Create or replace the vendor's bank account","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankAccountReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Add or update vendor bank account","tags":["Vendors"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertBankAccountInput"}}},"description":"Bank account details","required":true}}}}}
```

## Create vendor data request

> Send a self-service data collection link to the vendor

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"CreateVendorDataRequestReply":{"description":"Vendor data request creation result","properties":{"id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/data-request":{"post":{"description":"Send a self-service data collection link to the vendor","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendorDataRequestReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create vendor data request","tags":["Vendors"]}}}}
```

## List vendor data requests

> Get all data requests for a vendor

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"ListVendorDataRequestsReply":{"description":"List of vendor data requests","properties":{"data":{"items":{"$ref":"#/components/schemas/VendorDataRequestReply"},"type":"array"}},"type":"object"},"VendorDataRequestReply":{"description":"Vendor data request details","properties":{"created_at":{"type":"string"},"expires_at":{"type":"string"},"id":{"type":"string"},"status":{"type":"string"},"submitted_at":{"type":"string"},"vendor_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/data-requests":{"get":{"description":"Get all data requests for a vendor","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListVendorDataRequestsReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"List vendor data requests","tags":["Vendors"]}}}}
```

## Resend vendor data request

> Resend the data collection email for a vendor data request

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"ResendVendorDataRequestReply":{"description":"Data request resend confirmation","properties":{"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/data-requests/{request_id}/resend":{"post":{"description":"Resend the data collection email for a vendor data request","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true},{"schema":{"type":"string"},"description":"Data Request ID","in":"path","name":"request_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendVendorDataRequestReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Resend vendor data request","tags":["Vendors"]}}}}
```

## Deactivate a vendor

> Deactivate a vendor, setting is\_active to false

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"DeactivateVendorReply":{"description":"Vendor deactivation result","properties":{"affected_bill_count":{"type":"integer"},"vendor_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/deactivate":{"post":{"description":"Deactivate a vendor, setting is_active to false","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateVendorReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Deactivate a vendor","tags":["Vendors"]}}}}
```

## Reactivate a vendor

> Reactivate a previously deactivated vendor

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"ReactivateVendorReply":{"description":"Vendor reactivation result","properties":{"affected_bill_count":{"type":"integer"},"vendor_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/vendors/{id}/reactivate":{"post":{"description":"Reactivate a previously deactivated vendor","parameters":[{"schema":{"type":"string"},"description":"Vendor ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReactivateVendorReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Reactivate a vendor","tags":["Vendors"]}}}}
```


# Webhooks

## List webhook subscriptions

> Get a paginated list of webhook subscriptions with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["webhooks:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-WebhookSubscription":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookSubscription"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}},"paths":{"/webhooks":{"get":{"description":"Get a paginated list of webhook subscriptions with optional filtering","operationId":"listWebhookSubscriptions","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"string","enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"]},"description":"Filter by webhook topic","in":"query","name":"topic"},{"schema":{"type":"boolean"},"description":"Filter by active status","in":"query","name":"is_active"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-WebhookSubscription"}}}}},"summary":"List webhook subscriptions","tags":["Webhooks"]}}}}
```

## Subscribe to a webhook

> Subscribe to a webhook with the provided information

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["webhooks:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"SubscribeWebhookInput":{"description":"Subscribe to a webhook","properties":{"endpoint_url":{"type":"string"},"secret_key":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"}},"type":"object"}}},"paths":{"/webhooks":{"post":{"description":"Subscribe to a webhook with the provided information","operationId":"createWebhookSubscription","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Subscribe to a webhook","tags":["Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeWebhookInput"}}},"description":"Webhook information","required":true}}}}}
```

## Unsubscribe from a webhook

> Remove a webhook subscription by ID

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["webhooks:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/webhooks/{subscription_id}":{"delete":{"description":"Remove a webhook subscription by ID","operationId":"deleteWebhookSubscription","parameters":[{"schema":{"type":"string"},"description":"Subscription ID","in":"path","name":"subscription_id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Unsubscribe from a webhook","tags":["Webhooks"]}}}}
```

## List webhook events

> Get a paginated list of webhook events with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["webhooks:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-WebhookEvent":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"WebhookEvent":{"description":"Webhook event information","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"idempotency_key":{"type":"string"},"partner_id":{"type":"string"},"payload":{},"sent_at":{"type":"string"},"sort_key":{"type":"integer"},"status":{"$ref":"#/components/schemas/WebhookEventStatus"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookEventStatus":{"enum":["pending","sent","failed"],"type":"string"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}},"paths":{"/webhooks/events":{"get":{"description":"Get a paginated list of webhook events with optional filtering","operationId":"listWebhookEvents","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"string","enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"]},"description":"Filter by webhook topic","in":"query","name":"topic"},{"schema":{"type":"string","enum":["pending","sent","failed"]},"description":"Filter by event status","in":"query","name":"status"},{"schema":{"type":"string"},"description":"Filter events created after this date (ISO 8601)","in":"query","name":"from_date"},{"schema":{"type":"string"},"description":"Filter events created before this date (ISO 8601)","in":"query","name":"to_date"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-WebhookEvent"}}}}},"summary":"List webhook events","tags":["Webhooks"]}}}}
```

## Retry failed webhooks

> Retry all failed webhook events for the partner

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["webhooks:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"RetryWebhooksResponse":{"description":"Response from retrying webhooks","properties":{"message":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/webhooks/retry":{"post":{"description":"Retry all failed webhook events for the partner","operationId":"retryWebhookEvent","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryWebhooksResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Retry failed webhooks","tags":["Webhooks"]}}}}
```


# Models

## The AccountTypeEnum object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"AccountTypeEnum":{"description":"Bank account type enum","enum":["checking","savings"],"type":"string"}}}}
```

## The AddressInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"AddressInput":{"description":"Address information","properties":{"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"state_code":{"type":"string"},"street_address":{"type":"string"},"subpremise":{"type":"string"}},"type":"object"}}}}
```

## The BankAccountInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BankAccountInput":{"description":"Bank account details for vendor creation","properties":{"account_number":{"type":"string"},"account_type":{"type":"string"},"bank_name":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}}}
```

## The BankAccountReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BankAccountReply":{"description":"Vendor bank account details (masked)","properties":{"account_mask":{"type":"string"},"account_type":{"$ref":"#/components/schemas/AccountTypeEnum"},"bank_name":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"},"AccountTypeEnum":{"description":"Bank account type enum","enum":["checking","savings"],"type":"string"}}}}
```

## The BillDocumentReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BillDocumentReply":{"description":"Bill document download details","properties":{"download_url":{"type":"string"},"filename":{"type":"string"},"mime_type":{"type":"string"}},"type":"object"}}}}
```

## The BillLineItemInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}}}
```

## The BillReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"}}}}
```

## The BillSource object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"}}}}
```

## The BillStatus object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"}}}}
```

## The BillStatusReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"}}}}
```

## The BulkCancelItemInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkCancelItemInput":{"description":"Bulk cancel item","properties":{"bill_id":{"type":"string"},"payment_id":{"type":"string"}},"type":"object"}}}}
```

## The BulkCancelResultReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkCancelResultReply":{"description":"Bulk cancel per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The BulkCancelVendorPaymentsInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkCancelVendorPaymentsInput":{"description":"Bulk vendor payment cancellation request","properties":{"items":{"items":{"$ref":"#/components/schemas/BulkCancelItemInput"},"type":"array"}},"type":"object"},"BulkCancelItemInput":{"description":"Bulk cancel item","properties":{"bill_id":{"type":"string"},"payment_id":{"type":"string"}},"type":"object"}}}}
```

## The BulkCancelVendorPaymentsReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkCancelVendorPaymentsReply":{"description":"Bulk vendor payment cancellation results","properties":{"results":{"items":{"$ref":"#/components/schemas/BulkCancelResultReply"},"type":"array"}},"type":"object"},"BulkCancelResultReply":{"description":"Bulk cancel per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The BulkDeleteBillsInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkDeleteBillsInput":{"description":"Bulk bill deletion request","properties":{"bill_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"}}}}
```

## The BulkOperationReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkOperationReply":{"description":"Bulk operation results","properties":{"results":{"items":{"$ref":"#/components/schemas/BulkResultReply"},"type":"array"}},"type":"object"},"BulkResultReply":{"description":"Bulk operation per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The BulkResultReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkResultReply":{"description":"Bulk operation per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The BulkSubmitBillsInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"BulkSubmitBillsInput":{"description":"Bulk bill submission request","properties":{"bill_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"}}}}
```

## The CancelVendorPaymentInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CancelVendorPaymentInput":{"description":"Vendor payment cancellation request","properties":{"bill_id":{"type":"string"},"payment_id":{"type":"string"}},"type":"object"}}}}
```

## The CancelVendorPaymentReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CancelVendorPaymentReply":{"description":"Vendor payment cancellation result","properties":{"payment_id":{"type":"string"},"status":{"type":"string"}},"type":"object"}}}}
```

## The CardFormCredentials object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CardFormCredentials":{"properties":{"app_id":{"type":"string"},"team_id":{"type":"string"}},"type":"object"}}}}
```

## The ChangeDefaultResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"ChangeDefaultResponse":{"description":"Change default method response","properties":{"response":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutAddressInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutAddressInput":{"description":"Billing address information","properties":{"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"state_code":{"type":"string"},"street_address":{"type":"string"},"subpremise":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutCAAccountData object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCAAccountData":{"description":"Canadian bank account data","properties":{"account_number":{"type":"string"},"institution_code":{"type":"string"},"transit_number":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutCreateBankAccountInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreateBankAccountInput":{"description":"Create bank account payment method request body. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.","properties":{"account_data_type":{"enum":["us","ca"],"type":"string"},"ca_account_data":{"$ref":"#/components/schemas/CheckoutCAAccountData"},"custom_name":{"type":"string"},"institution_name":{"type":"string"},"receiver_name":{"type":"string"},"subtype":{"allOf":[{"$ref":"#/components/schemas/checkout_api.AccountSubtype"}],"enum":["checkings","savings"]},"type":{"allOf":[{"$ref":"#/components/schemas/checkout_api.AccountType"}],"enum":["depository"]},"us_account_data":{"$ref":"#/components/schemas/CheckoutUSAccountData"}},"type":"object"},"CheckoutCAAccountData":{"description":"Canadian bank account data","properties":{"account_number":{"type":"string"},"institution_code":{"type":"string"},"transit_number":{"type":"string"}},"type":"object"},"checkout_api.AccountSubtype":{"enum":["checkings","savings"],"type":"string"},"checkout_api.AccountType":{"enum":["depository"],"type":"string"},"CheckoutUSAccountData":{"description":"US bank account data","properties":{"account_number":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutCreateBankAccountResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreateBankAccountResponse":{"description":"Create bank account response","properties":{"id":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutCreateCardCvvInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreateCardCvvInput":{"description":"CVV registration information","properties":{"cvv_secret":{"type":"string"},"provider":{"allOf":[{"$ref":"#/components/schemas/checkout_api.CardProvider"}],"enum":["evervault"]}},"type":"object"},"checkout_api.CardProvider":{"enum":["evervault"],"type":"string"}}}}
```

## The CheckoutCreateCardCvvResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreateCardCvvResponse":{"description":"Create card CVV response","properties":{"success":{"type":"boolean"}},"type":"object"}}}}
```

## The CheckoutCreateCardInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreateCardInput":{"description":"Create card payment method request body","properties":{"address":{"$ref":"#/components/schemas/CheckoutAddressInput"},"card_provider_token":{"type":"string"},"custom_name":{"type":"string"},"provider":{"allOf":[{"$ref":"#/components/schemas/checkout_api.CardProvider"}],"enum":["evervault"]}},"type":"object"},"CheckoutAddressInput":{"description":"Billing address information","properties":{"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"state_code":{"type":"string"},"street_address":{"type":"string"},"subpremise":{"type":"string"}},"type":"object"},"checkout_api.CardProvider":{"enum":["evervault"],"type":"string"}}}}
```

## The CheckoutCreateCardResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreateCardResponse":{"description":"Create card response","properties":{"id":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutCreatePaymentInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreatePaymentInput":{"description":"Create payment request body","properties":{"amount":{"type":"string"},"idempotency_key":{"type":"string"},"payment_date":{"type":"string"},"payment_method":{"enum":["card","standard_ach"],"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutCreatePaymentResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutCreatePaymentResponse":{"description":"Create payment response","properties":{"message":{"type":"string"},"status":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutGetCardPaymentFeesRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutGetCardPaymentFeesRequest":{"description":"Request body for calculating card payment fees","properties":{"amount":{"type":"string"},"currency":{"enum":["USD","CAD"],"type":"string"}},"type":"object"}}}}
```

## The CheckoutGetCardPaymentFeesResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutGetCardPaymentFeesResponse":{"description":"Response containing calculated payment fees for card payments","properties":{"fee_percentage_for_customer":{"type":"string"},"fee_percentage_for_partner":{"type":"string"},"fixed_fee_amount_customer":{"type":"string"},"fixed_fee_amount_partner":{"type":"string"},"relative_fee_amount_customer":{"type":"string"},"relative_fee_amount_partner":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutGetPaymentMethodsReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutGetPaymentMethodsReply":{"description":"List of payment methods response","properties":{"data":{"items":{"$ref":"#/components/schemas/CheckoutPaymentMethod"},"type":"array"}},"type":"object"},"CheckoutPaymentMethod":{"description":"Payment method information","properties":{"brand":{"type":"string"},"created_at":{"type":"string"},"default":{"type":"boolean"},"exp_month":{"type":"string"},"exp_year":{"type":"string"},"id":{"type":"string"},"last4":{"type":"string"},"type":{"$ref":"#/components/schemas/checkout_api.MethodType"}},"type":"object"},"checkout_api.MethodType":{"enum":["card","ach"],"type":"string"}}}}
```

## The CheckoutGetPdfLinkReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutGetPdfLinkReply":{"description":"PDF link response","properties":{"url":{"type":"string"}},"type":"object"}}}}
```

## The CheckoutInvoiceReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutInvoiceReply":{"description":"Invoice response","properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"}}}}
```

## The CheckoutPaymentMethod object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutPaymentMethod":{"description":"Payment method information","properties":{"brand":{"type":"string"},"created_at":{"type":"string"},"default":{"type":"boolean"},"exp_month":{"type":"string"},"exp_year":{"type":"string"},"id":{"type":"string"},"last4":{"type":"string"},"type":{"$ref":"#/components/schemas/checkout_api.MethodType"}},"type":"object"},"checkout_api.MethodType":{"enum":["card","ach"],"type":"string"}}}}
```

## The CheckoutUSAccountData object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CheckoutUSAccountData":{"description":"US bank account data","properties":{"account_number":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}}}
```

## The CreateBankAccountInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateBankAccountInput":{"description":"Bank account information. Only one of USAccountData or CAAccountData must be sent, matching AccountDataType.","properties":{"account_data_type":{"enum":["us","ca"],"type":"string"},"ca_account_data":{"$ref":"#/components/schemas/payment_methods_api.CAAccountData"},"custom_name":{"type":"string"},"institution_name":{"type":"string"},"receiver_name":{"type":"string"},"subtype":{"enum":["checkings","savings"],"type":"string"},"type":{"enum":["depository"],"type":"string"},"us_account_data":{"$ref":"#/components/schemas/payment_methods_api.USAccountData"}},"type":"object"},"payment_methods_api.CAAccountData":{"properties":{"account_number":{"type":"string"},"institution_code":{"type":"string"},"transit_number":{"type":"string"}},"type":"object"},"payment_methods_api.USAccountData":{"properties":{"account_number":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}}}
```

## The CreateBankAccountResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateBankAccountResponse":{"description":"Create bank account response","properties":{"id":{"type":"string"}},"type":"object"}}}}
```

## The CreateBillInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateBillInput":{"description":"Bill creation request","properties":{"amount":{"type":"number"},"description":{"type":"string"},"due_date":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/BillLineItemInput"},"type":"array"},"number":{"type":"string"},"status":{"type":"string"},"vendor_id":{"type":"string"}},"type":"object"},"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}}}
```

## The CreateCardCvvInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateCardCvvInput":{"description":"CVV registration information","properties":{"cvv_secret":{"type":"string"},"product_id":{"type":"string"},"product_type":{"enum":["invoice"],"type":"string"},"provider":{"enum":["evervault"],"type":"string"}},"type":"object"}}}}
```

## The CreateCardCvvResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateCardCvvResponse":{"description":"Create card CVV response","properties":{"success":{"type":"boolean"}},"type":"object"}}}}
```

## The CreateCardInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateCardInput":{"description":"Tokenized card information","properties":{"address":{"$ref":"#/components/schemas/AddressInput"},"card_provider_token":{"type":"string"},"custom_name":{"type":"string"},"provider":{"enum":["evervault"],"type":"string"}},"type":"object"},"AddressInput":{"description":"Address information","properties":{"city":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"state_code":{"type":"string"},"street_address":{"type":"string"},"subpremise":{"type":"string"}},"type":"object"}}}}
```

## The CreateCardResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateCardResponse":{"description":"Create card response","properties":{"id":{"type":"string"}},"type":"object"}}}}
```

## The CreateCustomerInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateCustomerInput":{"description":"Customer information","properties":{"city":{"type":"string"},"country":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"}}}}
```

## The CreateCustomerUserInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateCustomerUserInput":{"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}},"type":"object"}}}}
```

## The CreateInvoiceInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateInvoiceInput":{"properties":{"customer_id":{"type":"string"},"due_date":{"description":"Due date in YYYY-MM-DD format. If omitted, defaults to the current date from invoice creation.","type":"string"},"exclude_from_autopay":{"description":"When true, this invoice is excluded from Autopay at creation time. Use this\nwhen your integration pays the invoice synchronously via API and you want to\nguarantee Autopay never charges the same invoice. Defaults to false.","type":"boolean"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"}}}}
```

## The CreatePaymentRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreatePaymentRequest":{"description":"Request body for creating a payment","properties":{"amount":{"type":"string"},"customer_id":{"type":"string"},"idempotency_key":{"type":"string"},"invoice_id":{"type":"string"},"payment_date":{"type":"string"},"payment_method":{"description":"@enum card,standard_ach","enum":["card","standard_ach"],"type":"string"},"payment_method_id":{"type":"string"}},"type":"object"}}}}
```

## The CreateRefundRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateRefundRequest":{"description":"Request body for creating a refund","properties":{"amount":{"type":"string"},"idempotency_key":{"type":"string"},"payment_id":{"type":"string"},"reason":{"$ref":"#/components/schemas/RefundReasonDetail"}},"type":"object"},"RefundReasonDetail":{"description":"The reason for the refund. If 'Other', please specify the reason in more detail.","properties":{"description":{"type":"string"},"type":{"allOf":[{"$ref":"#/components/schemas/refunds_api.RefundType"}],"description":"@enum Customer Request, Duplicate, Fraud, Other"}},"type":"object"},"refunds_api.RefundType":{"enum":["Customer Request","Duplicate","Fraud","Other"],"type":"string"}}}}
```

## The CreateVendorDataRequestReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateVendorDataRequestReply":{"description":"Vendor data request creation result","properties":{"id":{"type":"string"}},"type":"object"}}}}
```

## The CreateVendorInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateVendorInput":{"description":"Vendor creation request","properties":{"bank_account":{"$ref":"#/components/schemas/BankAccountInput"},"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"}},"type":"object"},"BankAccountInput":{"description":"Bank account details for vendor creation","properties":{"account_number":{"type":"string"},"account_type":{"type":"string"},"bank_name":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}}}
```

## The CreateVendorPaymentInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateVendorPaymentInput":{"description":"Vendor payment creation request","properties":{"idempotency_key":{"type":"string"},"items":{"items":{"$ref":"#/components/schemas/PaymentItemInput"},"type":"array"}},"type":"object"},"PaymentItemInput":{"description":"Payment item for vendor payment creation","properties":{"bill_id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedInput"}},"type":"object"},"PaymentSpeedInput":{"description":"Payment speed enum: standard, next_day, same_day, instant","enum":["standard","next_day","same_day","instant"],"type":"string"}}}}
```

## The CreateVendorPaymentReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateVendorPaymentReply":{"description":"Vendor payment creation results","properties":{"results":{"items":{"$ref":"#/components/schemas/CreateVendorPaymentResultReply"},"type":"array"}},"type":"object"},"CreateVendorPaymentResultReply":{"description":"Vendor payment creation per-item result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The CreateVendorPaymentResultReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CreateVendorPaymentResultReply":{"description":"Vendor payment creation per-item result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The CustomerReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"}}}}
```

## The CustomerUser object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"CustomerUser":{"properties":{"created_at":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string"},"job_title":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"}},"type":"object"}}}}
```

## The DeactivateVendorReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"DeactivateVendorReply":{"description":"Vendor deactivation result","properties":{"affected_bill_count":{"type":"integer"},"vendor_id":{"type":"string"}},"type":"object"}}}}
```

## The DeleteBillReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"DeleteBillReply":{"description":"Bill deletion result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The DeletePaymentMethodResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"DeletePaymentMethodResponse":{"description":"Delete a payment method","properties":{"response":{"type":"string"}},"type":"object"}}}}
```

## The ExtractedBillDataReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"ExtractedBillDataReply":{"description":"Extracted bill data from OCR","properties":{"description":{"type":"string"},"due_date":{"type":"string"},"invoice_number":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/ExtractedLineItemReply"},"type":"array"},"total":{"type":"number"},"vendor_email":{"type":"string"},"vendor_name":{"type":"string"}},"type":"object"},"ExtractedLineItemReply":{"description":"Extracted line item from OCR","properties":{"description":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"}},"type":"object"}}}}
```

## The ExtractedLineItemReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"ExtractedLineItemReply":{"description":"Extracted line item from OCR","properties":{"description":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"}},"type":"object"}}}}
```

## The GenerateTokenResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GenerateTokenResponse":{"properties":{"expires_at":{"type":"integer"},"token":{"type":"string"}},"type":"object"}}}}
```

## The GetCardPaymentFeesRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GetCardPaymentFeesRequest":{"description":"Request body for calculating card payment fees","properties":{"amount":{"type":"string"},"currency":{"enum":["USD","CAD"],"type":"string"}},"type":"object"}}}}
```

## The GetCardPaymentFeesResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GetCardPaymentFeesResponse":{"description":"Response containing calculated payment fees for card payments","properties":{"fee_percentage_for_customer":{"type":"string"},"fee_percentage_for_partner":{"type":"string"},"fixed_fee_amount_customer":{"type":"string"},"fixed_fee_amount_partner":{"type":"string"},"relative_fee_amount_customer":{"type":"string"},"relative_fee_amount_partner":{"type":"string"}},"type":"object"}}}}
```

## The GetPaymentLinkData object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GetPaymentLinkData":{"properties":{"url":{"type":"string"}},"type":"object"}}}}
```

## The GetPaymentMethodsReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GetPaymentMethodsReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PaymentMethod"},"type":"array"}},"type":"object"},"PaymentMethod":{"properties":{"brand":{"type":"string"},"created_at":{"type":"string"},"default":{"type":"boolean"},"exp_month":{"type":"string"},"exp_year":{"type":"string"},"id":{"type":"string"},"last4":{"type":"string"},"type":{"$ref":"#/components/schemas/MethodType"}},"type":"object"},"MethodType":{"enum":["card","ach"],"type":"string"}}}}
```

## The GetPdfLinkData object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GetPdfLinkData":{"properties":{"url":{"type":"string"}},"type":"object"}}}}
```

## The GetThemeReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GetThemeReply":{"properties":{"partner_name":{"type":"string"},"theme":{"$ref":"#/components/schemas/ThemePreferences"}},"type":"object"},"ThemePreferences":{"properties":{"color":{"type":"string"},"logo_url":{"type":"string"}},"type":"object"}}}}
```

## The GetTransactionsReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"GetTransactionsReply":{"properties":{"payout":{"$ref":"#/components/schemas/Payout"},"transactions":{"items":{"$ref":"#/components/schemas/Transaction"},"type":"array"}},"type":"object"},"Payout":{"properties":{"arrival_date":{"type":"string"},"created_at":{"type":"string"},"customer_id":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PayoutFee"},"type":"array"},"id":{"type":"string"},"status":{"$ref":"#/components/schemas/PayoutStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PayoutFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/PayoutFeeType"}},"type":"object"},"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"},"PayoutStatus":{"enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"],"type":"string"},"Transaction":{"properties":{"description":{"type":"string"},"direction":{"$ref":"#/components/schemas/TransactionDirection"},"failure_reason":{"type":"string"},"id":{"type":"string"},"method":{"$ref":"#/components/schemas/TransactionMethod"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"TransactionDirection":{"enum":["credit","debit"],"type":"string"},"TransactionMethod":{"enum":["standard_ach","same_day_ach","manual","card","wire","rtp"],"type":"string"},"TransactionStatus":{"enum":["created","processing","succeeded","canceled","charged","failed","chargeback","refunded"],"type":"string"}}}}
```

## The HttpError object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}}}
```

## The Invoice object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"Invoice":{"properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"last_notification_at":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"},"memo":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"}}}}
```

## The InvoiceLineItem object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"}}}}
```

## The LineItemReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}}}
```

## The LineItemsUpdateInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"LineItemsUpdateInput":{"description":"Line items update with optional replacement","properties":{"items":{"items":{"$ref":"#/components/schemas/BillLineItemInput"},"type":"array"},"replace":{"type":"boolean"}},"type":"object"},"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}}}
```

## The ListVendorDataRequestsReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"ListVendorDataRequestsReply":{"description":"List of vendor data requests","properties":{"data":{"items":{"$ref":"#/components/schemas/VendorDataRequestReply"},"type":"array"}},"type":"object"},"VendorDataRequestReply":{"description":"Vendor data request details","properties":{"created_at":{"type":"string"},"expires_at":{"type":"string"},"id":{"type":"string"},"status":{"type":"string"},"submitted_at":{"type":"string"},"vendor_id":{"type":"string"}},"type":"object"}}}}
```

## The MethodType object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"MethodType":{"enum":["card","ach"],"type":"string"}}}}
```

## The PaginatedResponse-BillReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-BillReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/BillReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"}}}}
```

## The PaginatedResponse-CustomerReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-CustomerReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CustomerReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"CustomerReply":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"customer_integration_id":{"type":"string"},"default_payment_method_id":{"type":"string"},"ein":{"type":"string"},"email":{"type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"}}}}
```

## The PaginatedResponse-CustomerUser object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-CustomerUser":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CustomerUser"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"CustomerUser":{"properties":{"created_at":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"id":{"type":"string"},"job_title":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"}},"type":"object"}}}}
```

## The PaginatedResponse-Invoice object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-Invoice":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Invoice"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"Invoice":{"properties":{"created_at":{"type":"string"},"currency":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"invoice_number":{"type":"string"},"last_notification_at":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/InvoiceLineItem"},"type":"array"},"memo":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"InvoiceLineItem":{"properties":{"amount":{"type":"number"},"description":{"type":"string"},"quantity":{"type":"integer"}},"type":"object"}}}}
```

## The PaginatedResponse-Payment object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-Payment":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Payment"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"Payment":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PaymentFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PaymentFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"}}}}
```

## The PaginatedResponse-Payout object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-Payout":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Payout"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"Payout":{"properties":{"arrival_date":{"type":"string"},"created_at":{"type":"string"},"customer_id":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PayoutFee"},"type":"array"},"id":{"type":"string"},"status":{"$ref":"#/components/schemas/PayoutStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PayoutFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/PayoutFeeType"}},"type":"object"},"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"},"PayoutStatus":{"enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"],"type":"string"}}}}
```

## The PaginatedResponse-RefundReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-RefundReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RefundReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"RefundReply":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/RefundFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"RefundFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"}}}}
```

## The PaginatedResponse-VendorReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-VendorReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/VendorReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"}}}}
```

## The PaginatedResponse-WebhookEvent object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-WebhookEvent":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookEvent"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"WebhookEvent":{"description":"Webhook event information","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"idempotency_key":{"type":"string"},"partner_id":{"type":"string"},"payload":{},"sent_at":{"type":"string"},"sort_key":{"type":"integer"},"status":{"$ref":"#/components/schemas/WebhookEventStatus"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookEventStatus":{"enum":["pending","sent","failed"],"type":"string"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}}}
```

## The PaginatedResponse-WebhookSubscription object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaginatedResponse-WebhookSubscription":{"properties":{"data":{"items":{"$ref":"#/components/schemas/WebhookSubscription"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}}}
```

## The PatchBillInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PatchBillInput":{"description":"Bill patch request (partial update)","properties":{"amount":{"type":"number"},"description":{"type":"string"},"due_date":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"$ref":"#/components/schemas/LineItemsUpdateInput"},"vendor_id":{"type":"string"}},"type":"object"},"LineItemsUpdateInput":{"description":"Line items update with optional replacement","properties":{"items":{"items":{"$ref":"#/components/schemas/BillLineItemInput"},"type":"array"},"replace":{"type":"boolean"}},"type":"object"},"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}}}
```

## The PatchCustomerRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PatchCustomerRequest":{"description":"Request body for patching customer information","properties":{"city":{"type":"string"},"country":{"type":"string"},"ein":{"type":"string"},"legal_name":{"type":"string"},"name":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"sub_premise":{"type":"string"}},"type":"object"}}}}
```

## The PatchVendorInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PatchVendorInput":{"description":"Vendor patch request (partial update)","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"}},"type":"object"}}}}
```

## The Payment object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"Payment":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PaymentFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"status":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PaymentFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"}}}}
```

## The PaymentFee object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaymentFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"}}}}
```

## The PaymentItemInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaymentItemInput":{"description":"Payment item for vendor payment creation","properties":{"bill_id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedInput"}},"type":"object"},"PaymentSpeedInput":{"description":"Payment speed enum: standard, next_day, same_day, instant","enum":["standard","next_day","same_day","instant"],"type":"string"}}}}
```

## The PaymentMethod object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaymentMethod":{"properties":{"brand":{"type":"string"},"created_at":{"type":"string"},"default":{"type":"boolean"},"exp_month":{"type":"string"},"exp_year":{"type":"string"},"id":{"type":"string"},"last4":{"type":"string"},"type":{"$ref":"#/components/schemas/MethodType"}},"type":"object"},"MethodType":{"enum":["card","ach"],"type":"string"}}}}
```

## The PaymentRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaymentRequest":{"properties":{"id":{"type":"string"},"redirect_url":{"type":"string"},"reference_id":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"type":"object"}}}}
```

## The PaymentRequestInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaymentRequestInput":{"properties":{"amount":{"type":"string"},"redirect_url":{"type":"string"},"reference_id":{"type":"string"}},"type":"object"}}}}
```

## The PaymentSpeedEnum object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"}}}}
```

## The PaymentSpeedInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PaymentSpeedInput":{"description":"Payment speed enum: standard, next_day, same_day, instant","enum":["standard","next_day","same_day","instant"],"type":"string"}}}}
```

## The Payout object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"Payout":{"properties":{"arrival_date":{"type":"string"},"created_at":{"type":"string"},"customer_id":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/PayoutFee"},"type":"array"},"id":{"type":"string"},"status":{"$ref":"#/components/schemas/PayoutStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"PayoutFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/PayoutFeeType"}},"type":"object"},"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"},"PayoutStatus":{"enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"],"type":"string"}}}}
```

## The PayoutFee object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PayoutFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/PayoutFeeType"}},"type":"object"},"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"}}}}
```

## The PayoutFeeType object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PayoutFeeType":{"enum":["unspecified","late_payment","product","method"],"type":"string"}}}}
```

## The PayoutStatus object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"PayoutStatus":{"enum":["unspecified","creating","processing","analyzing","succeeded","scheduled","approved","canceled","pending","failed"],"type":"string"}}}}
```

## The ReactivateVendorReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"ReactivateVendorReply":{"description":"Vendor reactivation result","properties":{"affected_bill_count":{"type":"integer"},"vendor_id":{"type":"string"}},"type":"object"}}}}
```

## The RefundFee object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"RefundFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"}}}}
```

## The RefundReasonDetail object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"RefundReasonDetail":{"description":"The reason for the refund. If 'Other', please specify the reason in more detail.","properties":{"description":{"type":"string"},"type":{"allOf":[{"$ref":"#/components/schemas/refunds_api.RefundType"}],"description":"@enum Customer Request, Duplicate, Fraud, Other"}},"type":"object"},"refunds_api.RefundType":{"enum":["Customer Request","Duplicate","Fraud","Other"],"type":"string"}}}}
```

## The RefundReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"RefundReply":{"properties":{"created_at":{"type":"string"},"customer_id":{"type":"string"},"due_date":{"type":"string"},"fees":{"items":{"$ref":"#/components/schemas/RefundFee"},"type":"array"},"id":{"type":"string"},"payment_method":{"type":"string"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"RefundFee":{"properties":{"amount":{"type":"number"},"covered_by_customer":{"type":"boolean"},"name":{"type":"string"},"type":{"description":"@enum FT_LATE_PAYMENT,FT_PRODUCT,FT_METHOD,FT_INTEREST","enum":["FT_LATE_PAYMENT","FT_PRODUCT","FT_METHOD","FT_INTEREST"],"type":"string"}},"type":"object"}}}}
```

## The RejectBillInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"RejectBillInput":{"description":"Bill rejection request","properties":{"reason":{"type":"string"}},"type":"object"}}}}
```

## The RejectBillReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"RejectBillReply":{"description":"Bill rejection result","properties":{"bill_id":{"type":"string"}},"type":"object"}}}}
```

## The ResendVendorDataRequestReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"ResendVendorDataRequestReply":{"description":"Data request resend confirmation","properties":{"success":{"type":"boolean"}},"type":"object"}}}}
```

## The RetryVendorPaymentReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"RetryVendorPaymentReply":{"description":"Vendor payment retry result","properties":{"bill_id":{"type":"string"}},"type":"object"}}}}
```

## The RetryWebhooksResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"RetryWebhooksResponse":{"description":"Response from retrying webhooks","properties":{"message":{"type":"string"}},"type":"object"}}}}
```

## The SubmitBillReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"SubmitBillReply":{"description":"Bill submission result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"}}}}
```

## The SubscribeWebhookInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"SubscribeWebhookInput":{"description":"Subscribe to a webhook","properties":{"endpoint_url":{"type":"string"},"secret_key":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}}}
```

## The ThemePreferences object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"ThemePreferences":{"properties":{"color":{"type":"string"},"logo_url":{"type":"string"}},"type":"object"}}}}
```

## The TokenResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"TokenResponse":{"description":"OAuth2 access token response structure containing the bearer token and expiration details","properties":{"access_token":{"description":"@Description The OAuth2 access token for API authentication - use as Bearer token in Authorization header\n@Example 580defdbe1d21e0001c67e5c2a0a6c98ba8b4a059dc5825388501574","type":"string"},"expires_in":{"description":"@Description Token expiration time in seconds from issuance\n@Example 3600","type":"integer"},"token_type":{"description":"@Description OAuth2 token type - always \"bearer\" for this implementation\n@Example bearer","type":"string"}},"type":"object"}}}}
```

## The Transaction object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"Transaction":{"properties":{"description":{"type":"string"},"direction":{"$ref":"#/components/schemas/TransactionDirection"},"failure_reason":{"type":"string"},"id":{"type":"string"},"method":{"$ref":"#/components/schemas/TransactionMethod"},"status":{"$ref":"#/components/schemas/TransactionStatus"},"sub_total":{"type":"number"},"total":{"type":"number"}},"type":"object"},"TransactionDirection":{"enum":["credit","debit"],"type":"string"},"TransactionMethod":{"enum":["standard_ach","same_day_ach","manual","card","wire","rtp"],"type":"string"},"TransactionStatus":{"enum":["created","processing","succeeded","canceled","charged","failed","chargeback","refunded"],"type":"string"}}}}
```

## The TransactionDirection object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"TransactionDirection":{"enum":["credit","debit"],"type":"string"}}}}
```

## The TransactionMethod object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"TransactionMethod":{"enum":["standard_ach","same_day_ach","manual","card","wire","rtp"],"type":"string"}}}}
```

## The TransactionStatus object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"TransactionStatus":{"enum":["created","processing","succeeded","canceled","charged","failed","chargeback","refunded"],"type":"string"}}}}
```

## The UpdatePayDateInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"UpdatePayDateInput":{"description":"Pay date update request","properties":{"pay_date":{"type":"string"}},"type":"object"}}}}
```

## The UpdatePayDateReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"UpdatePayDateReply":{"description":"Pay date update result","properties":{"bill_id":{"type":"string"}},"type":"object"}}}}
```

## The UploadBillDocumentInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"UploadBillDocumentInput":{"description":"Bill document upload request","properties":{"content":{"type":"string"},"content_type":{"type":"string"},"filename":{"type":"string"}},"type":"object"}}}}
```

## The UploadBillDocumentReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"UploadBillDocumentReply":{"description":"Bill upload result with OCR data","properties":{"bill_id":{"type":"string"},"bill_number":{"type":"string"},"document_path":{"type":"string"},"extracted_data":{"$ref":"#/components/schemas/ExtractedBillDataReply"},"warnings":{"items":{"type":"string"},"type":"array"}},"type":"object"},"ExtractedBillDataReply":{"description":"Extracted bill data from OCR","properties":{"description":{"type":"string"},"due_date":{"type":"string"},"invoice_number":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/ExtractedLineItemReply"},"type":"array"},"total":{"type":"number"},"vendor_email":{"type":"string"},"vendor_name":{"type":"string"}},"type":"object"},"ExtractedLineItemReply":{"description":"Extracted line item from OCR","properties":{"description":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"}},"type":"object"}}}}
```

## The UploadInvoicePdfInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"UploadInvoicePdfInput":{"description":"Invoice PDF upload request. Provide exactly one of content (base64-encoded bytes) or url (public HTTPS link to the PDF, downloaded once at upload time and stored). Either way we keep our own copy and never read the link again, so send the request again to publish an updated document.","properties":{"content":{"description":"The PDF document as standard base64 (RFC 4648). Must decode to a valid PDF\n(the file must start with the PDF header) of at most 10 MB. Mutually\nexclusive with url.","type":"string"},"url":{"description":"A public, absolute HTTPS link to the PDF. Fetched exactly once, at upload\ntime; we store our own copy and never read the link again — if the document\nbehind it changes, re-send this request to publish the new version. HTTP links,\nredirects to non-HTTPS locations, and links resolving to private addresses\nare rejected. The response must be a PDF of at most 10 MB. Mutually\nexclusive with content.","type":"string"}},"type":"object"}}}}
```

## The UploadInvoicePdfReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"UploadInvoicePdfReply":{"properties":{"path":{"description":"Path is the stored location of the PDF, for both the content and url\nvariants. It is an opaque identifier, not a downloadable link — to retrieve\nthe document, call GET /invoices/{id}/pdf-link for a signed URL.","type":"string"}},"type":"object"}}}}
```

## The UpsertBankAccountInput object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"UpsertBankAccountInput":{"description":"Bank account upsert request","properties":{"account_number":{"type":"string"},"account_type":{"type":"string"},"bank_name":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}}}
```

## The VendorDataRequestReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"VendorDataRequestReply":{"description":"Vendor data request details","properties":{"created_at":{"type":"string"},"expires_at":{"type":"string"},"id":{"type":"string"},"status":{"type":"string"},"submitted_at":{"type":"string"},"vendor_id":{"type":"string"}},"type":"object"}}}}
```

## The VendorOriginEnum object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"}}}}
```

## The VendorPaymentReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"}}}}
```

## The VendorPaymentStatusEnum object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"}}}}
```

## The VendorReply object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"VendorReply":{"description":"Vendor details","properties":{"category":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string"},"email":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"name":{"type":"string"},"origin":{"$ref":"#/components/schemas/VendorOriginEnum"},"phone":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"},"street_address":{"type":"string"},"tax_id":{"type":"string"},"updated_at":{"type":"string"}},"type":"object"},"VendorOriginEnum":{"description":"Vendor origin enum","enum":["manual","quickbooks","ocr"],"type":"string"}}}}
```

## The WebhookEvent object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"WebhookEvent":{"description":"Webhook event information","properties":{"created_at":{"type":"string"},"id":{"type":"string"},"idempotency_key":{"type":"string"},"partner_id":{"type":"string"},"payload":{},"sent_at":{"type":"string"},"sort_key":{"type":"integer"},"status":{"$ref":"#/components/schemas/WebhookEventStatus"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookEventStatus":{"enum":["pending","sent","failed"],"type":"string"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}}}
```

## The WebhookEventStatus object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"WebhookEventStatus":{"enum":["pending","sent","failed"],"type":"string"}}}}
```

## The WebhookSubscription object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"WebhookSubscription":{"description":"Webhook subscription information","properties":{"created_at":{"type":"string"},"endpoint_url":{"type":"string"},"id":{"type":"string"},"is_active":{"type":"boolean"},"partner_id":{"type":"string"},"secret_last_4_digits":{"type":"string"},"topic":{"$ref":"#/components/schemas/WebhookTopic"},"updated_at":{"type":"string"}},"type":"object"},"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}}}
```

## The WebhookTopic object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"WebhookTopic":{"enum":["payout_paid","payout_failed","payout_processing","payout_scheduled","customer_created","customer_updated","customer_archived","payment_succeeded","payment_chargeback","payment_refunded","invoice_paid","invoice_archived","invoice_created","invoice_updated","payment_failed","payment_method_added","payment_method_deleted","default_payment_method_changed","vendor_created","vendor_updated","vendor_deactivated","vendor_reactivated","bill_created","bill_updated","bill_submitted","bill_rejected","bill_deleted","vendor_payment_processing","vendor_payment_succeeded","vendor_payment_failed","vendor_payment_canceled","vendor_data_request_submitted"],"type":"string"}}}}
```

## The address\_api.AddressComponent object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.AddressComponent":{"properties":{"long_name":{"type":"string"},"short_name":{"type":"string"},"types":{"items":{"type":"string"},"type":"array"}},"type":"object"}}}}
```

## The address\_api.AddressResult object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.AddressResult":{"properties":{"address_components":{"items":{"$ref":"#/components/schemas/address_api.AddressComponent"},"type":"array"},"name":{"type":"string"}},"type":"object"},"address_api.AddressComponent":{"properties":{"long_name":{"type":"string"},"short_name":{"type":"string"},"types":{"items":{"type":"string"},"type":"array"}},"type":"object"}}}}
```

## The address\_api.AutocompleteRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.AutocompleteRequest":{"properties":{"country":{"type":"string"},"q":{"type":"string"},"sessiontoken":{"type":"string"}},"type":"object"}}}}
```

## The address\_api.AutocompleteResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.AutocompleteResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/address_api.Prediction"},"type":"array"}},"type":"object"},"address_api.Prediction":{"properties":{"description":{"type":"string"},"place_id":{"type":"string"},"structured_formatting":{"$ref":"#/components/schemas/address_api.StructuredFormating"}},"type":"object"},"address_api.StructuredFormating":{"properties":{"main_text":{"type":"string"},"secondary_text":{"type":"string"}},"type":"object"}}}}
```

## The address\_api.DetailsRequest object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.DetailsRequest":{"properties":{"id":{"type":"string"},"sessiontoken":{"type":"string"}},"type":"object"}}}}
```

## The address\_api.DetailsResponse object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.DetailsResponse":{"properties":{"data":{"$ref":"#/components/schemas/address_api.PlaceDetails"}},"type":"object"},"address_api.PlaceDetails":{"properties":{"result":{"$ref":"#/components/schemas/address_api.AddressResult"}},"type":"object"},"address_api.AddressResult":{"properties":{"address_components":{"items":{"$ref":"#/components/schemas/address_api.AddressComponent"},"type":"array"},"name":{"type":"string"}},"type":"object"},"address_api.AddressComponent":{"properties":{"long_name":{"type":"string"},"short_name":{"type":"string"},"types":{"items":{"type":"string"},"type":"array"}},"type":"object"}}}}
```

## The address\_api.PlaceDetails object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.PlaceDetails":{"properties":{"result":{"$ref":"#/components/schemas/address_api.AddressResult"}},"type":"object"},"address_api.AddressResult":{"properties":{"address_components":{"items":{"$ref":"#/components/schemas/address_api.AddressComponent"},"type":"array"},"name":{"type":"string"}},"type":"object"},"address_api.AddressComponent":{"properties":{"long_name":{"type":"string"},"short_name":{"type":"string"},"types":{"items":{"type":"string"},"type":"array"}},"type":"object"}}}}
```

## The address\_api.Prediction object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.Prediction":{"properties":{"description":{"type":"string"},"place_id":{"type":"string"},"structured_formatting":{"$ref":"#/components/schemas/address_api.StructuredFormating"}},"type":"object"},"address_api.StructuredFormating":{"properties":{"main_text":{"type":"string"},"secondary_text":{"type":"string"}},"type":"object"}}}}
```

## The address\_api.StructuredFormating object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"address_api.StructuredFormating":{"properties":{"main_text":{"type":"string"},"secondary_text":{"type":"string"}},"type":"object"}}}}
```

## The checkout\_api.AccountSubtype object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"checkout_api.AccountSubtype":{"enum":["checkings","savings"],"type":"string"}}}}
```

## The checkout\_api.AccountType object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"checkout_api.AccountType":{"enum":["depository"],"type":"string"}}}}
```

## The checkout\_api.CardProvider object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"checkout_api.CardProvider":{"enum":["evervault"],"type":"string"}}}}
```

## The checkout\_api.MethodType object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"checkout_api.MethodType":{"enum":["card","ach"],"type":"string"}}}}
```

## The payment\_methods\_api.CAAccountData object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"payment_methods_api.CAAccountData":{"properties":{"account_number":{"type":"string"},"institution_code":{"type":"string"},"transit_number":{"type":"string"}},"type":"object"}}}}
```

## The payment\_methods\_api.USAccountData object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"payment_methods_api.USAccountData":{"properties":{"account_number":{"type":"string"},"routing_number":{"type":"string"}},"type":"object"}}}}
```

## The refunds\_api.RefundType object

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"components":{"schemas":{"refunds_api.RefundType":{"enum":["Customer Request","Duplicate","Fraud","Other"],"type":"string"}}}}
```