Skip to main content
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.

​
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 Endpoints: OpenAPI spec Learn more: Authentication Guide

​
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 Endpoints: OpenAPI spec Learn more: Customer Guide

​
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, Decline Codes Endpoints: OpenAPI spec Learn more: Payment Methods 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, Decline Codes Related webhooks: Webhooks Guide — payment and invoice lifecycle events Endpoints: OpenAPI spec Learn more:

​
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, Decline Codes Related webhooks: Webhooks Guide — e.g. InvoicePaid, InvoiceFailed Endpoints: OpenAPI spec Learn more:

​
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 Related webhooks: Webhooks Guide — e.g. RefundProcessed Endpoints: OpenAPI spec Learn more: Processing 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, Decline Codes Related webhooks: Webhooks Guide — subscription and invoice lifecycle events Endpoints: OpenAPI spec Learn more:

​
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 Endpoints: OpenAPI spec Learn more:

​
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 Endpoints: OpenAPI spec Learn more: Merchant Settings

​
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 Endpoints: OpenAPI spec Learn more: 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 Endpoints: OpenAPI spec

​
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