API Reference

Complete REST API documentation with schemas, examples, and guides

Explore comprehensive API documentation for all Payload resources including authentication, request patterns, object schemas, and query capabilities. Every endpoint includes detailed schemas, code examples in multiple languages, and integration guides.

General

Core API concepts and request patterns

Master authentication, request methods, error handling, and query capabilities to build robust API integrations. Learn HTTP Basic Auth and Bearer token authentication, perform GET/POST/PUT/DELETE operations, filter results with conditional queries, and implement pagination for large datasets.

Data & Design

API architecture and data enrichment

Understand object relationships, hierarchical data structures, and how to extend resources with custom metadata. Learn how transactions link to accounts and payment methods, explore nested object patterns, and use the attrs property to add business-specific data fields.

API Resources

Core objects and endpoints

Complete schema documentation for all Payload objects with properties, validation rules, and relationship information. Each resource includes required fields, read-only properties, enumeration values, nested object definitions, and code examples in multiple languages.

Transactions

Process payments, payouts, and track transaction relationships for comprehensive money movement operations. Create transactions with sender and receiver accounts, store payment methods securely, link transactions with transfers for reconciliation, and monitor transaction processing steps.

Account & Entity

Manage customer and processing accounts with identity verification, stakeholders, and processing configurations. Create accounts for customers and merchants, verify individual and business entities with KYC, manage beneficial owners, and configure processing rules and limits.

Billing & Invoicing

Create invoices, set up recurring billing schedules, and manage line items for automated subscription billing. Generate detailed invoices with tax automation, configure billing schedules with flexible frequencies, and define recurring line items for subscription charges.

Webhooks

Subscribe to real-time event notifications and monitor webhook delivery for event-driven integrations. Configure webhook triggers for transaction and invoice events, secure endpoints with signature verification, and troubleshoot failed deliveries with detailed logging.

Tokens & Intents

Create payment intents for hosted checkout flows and customer enrollment with pre-configured payment settings. Generate intents for one-time payments, autopay enrollment, or payment method collection with customizable amounts and customer information.

Profile & Access

Manage organization profiles, user accounts, and access permissions for platform administration. Configure profile settings and branding, create user accounts with role-based permissions, and control access to accounts and resources.

Quick Start

Get started with the Payload API in minutes:

1. Get Your API Keys Sign up for a Payload account and retrieve your secret keys from the dashboard (opens in a new tab).

2. Authenticate Requests Use HTTP Basic Auth or Bearer tokens to authenticate all API requests securely.

3. Make Your First Request Try a simple GET request to retrieve account information and verify your integration.

4. Process a Payment Create a Transaction to process your first payment or payout through the API.

API Fundamentals

REST Architecture Payload follows REST principles with resource-based URLs, standard HTTP methods, and JSON request/response bodies.

Idempotency Use idempotency keys to safely retry requests without duplicating operations. Critical for payment processing reliability.

Versioning API versions are specified during session initialization. The current version is API v2 with {apiVersion: '2'}.

Rate Limiting API requests are rate limited per account. Response headers include rate limit status and reset timing.

Pagination Large result sets use cursor-based pagination. Use paging parameters to navigate through results.

Code Examples

Every endpoint includes working code examples in multiple languages:

• JavaScript/Node.js - Using the official Payload SDK
• Python - Using the official Payload SDK
• cURL - Direct HTTP requests for any language

Examples show request parameters, response structures, and common use cases. Copy and customize for your integration.

Object Relationships

Understanding how objects relate helps you build powerful integrations:

Transactions ↔ Accounts Transactions have sender and receiver accounts defining the parties involved in money movement.

Transactions ↔ PaymentMethods Transactions reference payment methods for charging cards or bank accounts.

Invoices ↔ Accounts Invoices connect payer and biller accounts with payment methods for autopay configuration.

Transactions ↔ Invoices Transactions can allocate payments to one or more invoices using invoice_allocations.

Accounts ↔ Entities Processing accounts require entity verification with KYC information for compliance.

Transactions ↔ Transfers Transfers link paying transactions to funding transactions for reconciliation tracking.

Schema Documentation

Each object page includes:

Properties Table Complete list of all fields with types, descriptions, and validation rules.

Required Fields Clearly marked required properties for creating or updating objects.

Read-Only Fields System-generated fields like IDs and timestamps that cannot be modified.

Nested Objects Expandable nested objects with full schema definitions and relationships.

Enumerations Valid values for enum fields with descriptions of each option.

Query Capabilities

Build powerful queries with conditional operators:

Comparison Operators

• > Greater than
• < Less than
• >= Greater than or equal
• <= Less than or equal

Logical Operators

• | OR condition for multiple values
• Combine multiple conditions with AND logic

Pattern Matching

• ~ LIKE operator for text search
• !~ NOT LIKE for exclusion

Special Functions

• Date functions for time-based queries
• Aggregate functions for reporting
• String functions for text manipulation

Learn Query Language →

Error Handling

Handle API errors gracefully with proper error codes and messages:

4xx Client Errors

• 400 Bad Request - Invalid parameters
• 401 Unauthorized - Authentication failure
• 404 Not Found - Resource doesn't exist
• 422 Unprocessable - Validation errors

5xx Server Errors

• 500 Internal Server Error - Contact support
• 503 Service Unavailable - Temporary outage

Each error includes:

• type - Error category
• message - Human-readable description
• param - Field causing validation error (when applicable)

View Error Reference →

Next Steps

Build Your Integration Start with Authentication to set up secure API access with your secret keys.

Explore Objects Browse Transaction, Invoice, and Account schemas for your use case.

Master Queries Learn Query Language to filter and retrieve exactly the data you need.

Handle Events Set up Webhooks to receive real-time notifications for transaction and invoice events.