> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payoes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Payoes REST API conventions, base URL, authentication, and available resources.

The Payoes API is a REST JSON API for creating and managing Stellar payments, customers, and billing resources.

## Base URL

<Snippet file="base-url.mdx" />

All public integration endpoints are under `/api/v1`.

## Authentication

<Snippet file="auth-header.mdx" />

See [Authentication](/guides/authentication) for key management and rotation.

## Environments

API keys are scoped to a single environment:

| Key prefix    | Environment | Stellar network |
| ------------- | ----------- | --------------- |
| `pk_test_...` | Sandbox     | Testnet         |
| `pk_live_...` | Production  | Mainnet         |

List and retrieve operations only return resources created in the same environment as the API key. Sandbox and production data are fully isolated.

See [Environments](/guides/environments) for dashboard mode switching and settlement wallets.

## Request format

* Send JSON bodies with `Content-Type: application/json`
* Use snake\_case field names in request and response bodies
* Amounts are strings with up to 7 decimal places (Stellar convention)

## Response format

Successful responses return JSON objects. List endpoints wrap resources in a plural key (for example `payments`, `customers`).

Errors return:

```json theme={null}
{
  "error": "Human-readable message"
}
```

## Object types

Resources include an `object` field for identification:

| `object` value     | Resource         |
| ------------------ | ---------------- |
| `payment_intent`   | Payment          |
| `checkout.session` | Checkout session |
| `payment_link`     | Payment link     |
| `invoice`          | Invoice          |

## Available endpoints

### Payments

| Method | Path             | Description             |
| ------ | ---------------- | ----------------------- |
| `POST` | `/payments`      | Create a payment intent |
| `GET`  | `/payments`      | List payments           |
| `GET`  | `/payments/{id}` | Retrieve a payment      |

### Customers

| Method | Path              | Description                             |
| ------ | ----------------- | --------------------------------------- |
| `POST` | `/customers`      | Create a customer                       |
| `GET`  | `/customers`      | List customers                          |
| `GET`  | `/customers/{id}` | Retrieve a customer and payment history |

### Checkout sessions

| Method | Path                      | Description                 |
| ------ | ------------------------- | --------------------------- |
| `GET`  | `/checkout-sessions`      | List checkout sessions      |
| `GET`  | `/checkout-sessions/{id}` | Retrieve a checkout session |

Checkout sessions are created when you finalize an invoice or when a customer visits a payment link.

### Payment links

| Method | Path                  | Description                    |
| ------ | --------------------- | ------------------------------ |
| `POST` | `/payment-links`      | Create a reusable payment link |
| `GET`  | `/payment-links`      | List payment links             |
| `GET`  | `/payment-links/{id}` | Retrieve a payment link        |

### Invoices

| Method | Path                      | Description                                     |
| ------ | ------------------------- | ----------------------------------------------- |
| `POST` | `/invoices`               | Create a draft invoice                          |
| `GET`  | `/invoices`               | List invoices                                   |
| `GET`  | `/invoices/{id}`          | Retrieve an invoice                             |
| `POST` | `/invoices/{id}/finalize` | Finalize a draft invoice and get a checkout URL |

Invoices can also be created with line items and sent by email from the dashboard. The hosted invoice page is available at `/i/{invoice_id}` after finalize.

Full request and response schemas are in the endpoint sections of this API reference, generated from `apps/docs/openapi/v1.yaml`.

## Hosted URLs

| Resource         | URL pattern                                     |
| ---------------- | ----------------------------------------------- |
| Payment checkout | `/c/{payment_id}` or `/c/{checkout_session_id}` |
| Payment link     | `/c/{payment_link_id}`                          |
| Hosted invoice   | `/i/{invoice_id}`                               |

## Rate limiting

Rate limits are not enforced in the current release. Production deployments should implement limits. Check release notes for updates.

## Idempotency

Idempotency keys are planned. Until then, use unique `metadata` values and guard webhook handlers against duplicate processing.

## Changelog

| Version | Changes                                                                  |
| ------- | ------------------------------------------------------------------------ |
| `v1`    | Payments, customers, checkout sessions, payment links, and invoices APIs |