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

# API Reference

> High-level overview of API endpoint groups. Understand what each group does and when to use it, then dive into the OpenAPI spec for detailed documentation.

> API Reference — quick guide to endpoint groups\
> This page gives you a high-level overview. For complete request/response schemas, parameters, and examples, see the [OpenAPI/Swagger spec](/api-reference/).

## Quick Start

**Base URL**: Use the environment-specific base URL shown in the OpenAPI/Swagger spec:

* **Sandbox**: `api-sandbox.revolv3.com` (for testing)
* **Production**: `api.revolv3.com` (for live transactions)

**Authentication**: Include your static API token in the `x-revolv3-token` header on every request.

**Content Type**: `application/json` for all requests.

**Errors**: Check HTTP status codes. Error responses include an internal error code and a human-readable message to help you debug.

## Endpoint Groups Overview

Here's what each group of endpoints does and when you'd use them:

### Authentication & Keys

**What it's for**: Managing API keys and authentication tokens for your account.

**When to use**:

* Getting your API keys for authentication
* Rotating or managing API credentials
* Setting up authentication for your integration

**Examples**:

* `POST /auth/token` — Generate authentication tokens
* `GET /auth/keys` — Retrieve your API keys

**Error codes**: [API Response Codes](/docs/error-codes/error-responses)

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**: [Authentication Guide](/docs/authentication-security/merchant-access-token)

***

### Customers

**What it's for**: Managing customer records in Revolv3. Customers are optional but useful for tracking all of a customer's payments, subscriptions, and payment methods together.

**When to use**:

* Creating customer profiles before subscriptions
* Linking multiple payments to the same customer
* Managing customer information separately from payments
* Building a customer management system

**Examples**:

* `POST /customers` — Create a new customer
* `GET /customers/{id}` — Get customer details and their payment history
* `PATCH /customers/{id}` — Update customer information

**Note**: Customers are optional—you can process payments without creating customer records. But they're helpful for subscriptions and tracking.

**Error codes**: [API Response Codes](/docs/error-codes/error-responses)

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**: [Customer Guide](/docs/core-concepts/customer/customer)

***

### Payment Methods

**What it's for**: Storing customer payment credentials securely (credit cards, bank accounts) so you can charge them again without asking for their details every time. This uses tokenization for security.

**When to use**:

* Saving a customer's card for faster checkout next time
* Setting up subscriptions (need a stored payment method)
* One-click purchases for returning customers
* Avoiding PCI compliance requirements (Revolv3 handles security)

**Examples**:

* `POST /payment-methods` — Store a payment method and get a token
* `GET /payment-methods/{id}` — Retrieve stored payment method details
* `POST /payment-methods/{id}/verify` — Verify a payment method before using it

**Error codes**: [API Response Codes](/docs/error-codes/error-responses), [Decline Codes](/docs/error-codes/decline-codes)

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**: [Payment Methods Guide](/docs/core-concepts/paymentmethod/paymentmethod-guide)

***

### Payments

**What it's for**: Processing one-time payments, authorizing funds (without charging), and capturing authorized payments. This is your main endpoint for charging customers.

**When to use**:

* E-commerce checkout (one-time purchases)
* Authorizing funds before you know the final amount (hotels, restaurants)
* Capturing previously authorized payments
* Immediate charges where you know the exact amount

**Examples**:

* `POST /payments/sale` — Charge a customer immediately (most common)
* `POST /payments/authorization` — Reserve funds without charging (for hotels, pre-orders)
* `POST /payments/{id}/capture` — Actually charge previously authorized funds
* `POST /payments/{id}/void` — Cancel an authorization

**Error codes**: [API Response Codes](/docs/error-codes/error-responses), [Decline Codes](/docs/error-codes/decline-codes)

**Related webhooks**: [Webhooks Guide](/docs/webhook-events/webhook) — payment and invoice lifecycle events

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**:

* [Make a Payment](/docs/getting-started/make-a-payment)
* [Authorizations & Captures](/docs/integration-flows/authorizations-captures)

***

### Invoices

**What it's for**: Managing invoices, which are billing documents that represent what you're charging for. Invoices drive payment attempts and track the status of charges.

**When to use**:

* Creating invoices before processing payments
* Checking payment status and invoice details
* Tracking what's been paid and what's pending
* Managing receivables and billing records

**Examples**:

* `POST /invoices` — Create an invoice
* `GET /invoices` — List invoices (with filters)
* `GET /invoices/{id}` — Get invoice details and payment status
* `GET /invoices/{id}/attempts` — See all payment attempts for an invoice

**Note**: When you process a payment, Revolv3 automatically creates an invoice. You can also create invoices separately if needed.

**Error codes**: [API Response Codes](/docs/error-codes/error-responses), [Decline Codes](/docs/error-codes/decline-codes)

**Related webhooks**: [Webhooks Guide](/docs/webhook-events/webhook) — e.g. InvoicePaid, InvoiceFailed

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**:

* [Invoice Status](/docs/core-concepts/invoice/invoice-status)
* [Get Invoices API](/docs/core-concepts/invoice/get-invoices-api)

***

### Refunds

**What it's for**: Issuing refunds to customers—returning money for previous payments. Supports both full and partial refunds.

**When to use**:

* Customer returns a product
* Service wasn't delivered as promised
* Customer cancels and is eligible for refund
* Partial refunds for damaged items or partial service
* Handling customer disputes

**Examples**:

* `POST /invoices/{id}/refund` — Issue a refund (full or partial)
* `GET /refunds/{id}` — Get refund status and details

**Error codes**: [API Response Codes](/docs/error-codes/error-responses)

**Related webhooks**: [Webhooks Guide](/docs/webhook-events/webhook) — e.g. RefundProcessed

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**: [Processing Refunds](/docs/integration-flows/refunds)

***

### Subscriptions

**What it's for**: Setting up recurring billing—automatically charging customers at regular intervals (weekly, monthly, yearly, etc.). Perfect for SaaS products, memberships, and subscription services.

**When to use**:

* Monthly software subscriptions
* Membership services (gyms, clubs, streaming)
* Recurring service billing
* Installment plans ("buy now, pay later")

**Examples**:

* `POST /subscriptions` — Create a subscription with billing plan
* `GET /subscriptions/{id}` — Get subscription details and next billing date
* `PATCH /subscriptions/{id}` — Update subscription (change plan, billing frequency, etc.)
* `POST /subscriptions/{id}/cancel` — Cancel a subscription

**Error codes**: [API Response Codes](/docs/error-codes/error-responses), [Decline Codes](/docs/error-codes/decline-codes)

**Related webhooks**: [Webhooks Guide](/docs/webhook-events/webhook) — subscription and invoice lifecycle events

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**:

* [Create a Subscription](/docs/core-concepts/subscription/create-subscription)
* [Canceling Subscriptions](/docs/core-concepts/subscription/canceling-a-subscription)

***

### Checkout (Hosted / Embedded)

**What it's for**: Creating hosted payment pages or embedded checkout forms. Revolv3 handles the payment form UI and security, so you don't have to build your own.

**When to use**:

* You want Revolv3 to handle the payment form (less development work)
* You need a PCI-compliant checkout without handling card data yourself
* Quick integration without building custom payment forms
* Embedded checkout in your application

**Examples**:

* `POST /checkout/sessions` — Create a checkout session
* `GET /checkout/sessions/{id}` — Get checkout session status

**Error codes**: [API Response Codes](/docs/error-codes/error-responses)

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**:

* [Checkout Guide](/docs/checkout/checkout)
* [Hosted Page](/docs/checkout/hosted-page)
* [Embedded Checkout](/docs/checkout/embedded)

***

### Processors & Merchant Configuration

**What it's for**: Configuring your merchant account settings, payment processor credentials, and business-level settings that affect how payments are processed.

**When to use**:

* Setting up payment processors (WorldPay, Adyen, etc.)
* Configuring merchant settings (descriptors, retry policies, etc.)
* Managing processor credentials
* Adjusting business-level payment processing rules

**Examples**:

* `GET /merchants/{id}/processors` — List configured processors
* `POST /merchants/{id}/processors` — Add or update processor configuration
* `GET /merchants/{id}/settings` — Get merchant settings

**Note**: Most merchants configure this once during setup. You typically don't need to change these frequently.

**Error codes**: [API Response Codes](/docs/error-codes/error-responses)

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**: [Merchant Settings](/docs/core-concepts/merchants/merchant-setting)

***

### Reports & Reconciliation

**What it's for**: Generating reports and reconciliation files to match your Revolv3 transactions with your accounting records and bank statements.

**When to use**:

* Daily/weekly/monthly reconciliation
* Exporting transaction data for accounting
* Generating settlement reports
* Matching payments with bank deposits
* Financial reporting and analysis

**Examples**:

* `POST /reports` — Generate a report (transactions, settlements, etc.)
* `GET /reports/{id}` — Get report status and download link

**Error codes**: [API Response Codes](/docs/error-codes/error-responses)

**Endpoints**: [OpenAPI spec](/api-reference/)

**Learn more**: [Invoice Export](/docs/core-concepts/invoice/invoice-export)

***

### Files & Attachments

**What it's for**: Uploading and managing supporting documents (receipts, invoices, contracts) that are associated with payments or customers.

**When to use**:

* Attaching receipts to transactions
* Storing customer documents
* Uploading proof of delivery or service
* Managing supporting documentation for disputes

**Examples**:

* `POST /files` — Upload a file
* `GET /files/{id}` — Download a file

**Note**: This is optional—most integrations don't need file uploads unless you have specific requirements.

**Error codes**: [API Response Codes](/docs/error-codes/error-responses)

**Endpoints**: [OpenAPI spec](/api-reference/)

***

## Common Integration Patterns

### E-Commerce Checkout Flow

1. **Payment Methods** → Store customer's card (optional, for faster checkout)
2. **Payments** → Charge the customer (`POST /payments/sale`)
3. **Invoices** → Check payment status (`GET /invoices/{id}`)
4. **Refunds** → Issue refund if customer returns item (`POST /invoices/{id}/refund`)

### Subscription Service Flow

1. **Customers** → Create customer record (optional)
2. **Payment Methods** → Store payment method for recurring charges
3. **Subscriptions** → Create subscription with billing plan
4. **Invoices** → Monitor subscription payments via webhooks
5. **Subscriptions** → Cancel if needed (`POST /subscriptions/{id}/cancel`)

### Hotel/Restaurant Flow (Authorization & Capture)

1. **Payments** → Authorize funds at check-in (`POST /payments/authorization`)
2. **Payments** → Capture actual amount at checkout (`POST /payments/{id}/capture`)
3. **Refunds** → Refund if customer cancels before capture

## Where to Go Next

* [**OpenAPI/Swagger Spec**](/api-reference/) — Complete API documentation with request/response schemas, parameters, and examples
* [**Error Codes & Troubleshooting**](/docs/error-codes/error-responses) — Understand error responses and how to handle them
* [**Authentication**](/docs/authentication-security/merchant-access-token) — Learn about API tokens, required headers, and security best practices
* [**Getting Started**](/docs/getting-started/getting-started) — Step-by-step guide to your first integration
* [**Core Concepts**](/docs/core-concepts/paymentmethod/paymentmethod-guide) — Deep dive into payment methods, invoices, subscriptions, and more

***