What's Changed

Enhanced features that work differently in v2

These capabilities existed in v1 but work significantly differently in v2. You'll need to update your code to work with the new patterns.

Automated Funding Architecture

v2 expands the funding system with a new manual settlement style, additional timing tiers, and redesigned default funding fields.

Funding styles — v2 adds a fourth manual style alongside the existing net, gross, and itemized modes for processing accounts that need no automatic disbursement.
Funding timing tiers — v1 had standard (next business day) only. v2 adds rapid (accelerated, varies by region) and instant (Real-Time Payments via RTP to synthetic accounts). Set per transaction.
Default funding methods — v1's default funding fields are redesigned in v2 into account_defaults on PaymentMethod objects, giving processing accounts more explicit control over which bank account receives deposits vs. funds withdrawals.

Migration note: No changes required — existing v1 funding configurations carry over to v2 as-is. The new options (manual style, additional timing tiers, redesigned default fields) are available when you want to opt in.

Billing & Invoicing Expansion

v2 expands billing and invoicing with richer invoice structure, autopay, and external payment recording.

Invoices & Billing Schedules — v2 adds tax rates and line item groups to both invoices and billing schedules, plus attachments on invoices.
Payer / Biller terminology — In invoice and billing schedule contexts, v2 uses payer (the account being charged) and biller (the account collecting) in place of v1's customer / processing fields. The underlying account types are unchanged.
Autopay — v2 adds the ability to set a custom autopay payment method per invoice or per billing schedule (overriding the payer's default).
External Payments — NEW in v2. Record payments received outside Payload (cash, wire, check) against open invoices for complete reconciliation.

Migration note: Existing Invoice and BillingSchedule code continues to work. Adopt item groups, autopay overrides, and external payments as opt-in upgrades when ready.

Webhooks

Several new webhook capabilities — signature verification, idempotent event IDs, and configurable retries — are available on both v1 and v2 endpoints.

Signature verification — NEW. Every delivery includes a Payload-Signature header (HMAC-SHA256) so handlers can verify authenticity. Available on both v1 and v2. Optional OAuth authentication for enterprise integrations.
Idempotent event IDs — NEW. Every delivery carries a stable event ID so handlers can safely deduplicate retries. Available on both v1 and v2.
Configurable retries — NEW. Retry policy can be tuned per webhook subscription instead of relying on a fixed default. Available on both v1 and v2.

Migration note: You can adopt signature verification, idempotent event IDs, and configurable retries on your existing v1 webhooks today. Existing v1 webhook URLs can be reused with v2 events.

Payment Collection

v1 had Checkout Plugin, Checkout Page, Secure Input, Payment Links, plus Payment API. v2 organizes these into 6 clear paths.

v1 patterns: Checkout (modal), Payment Link (hosted), Secure Input (embedded form fields), Payment API (backend), plus inline payment creation.
Checkout Link — Single-use hosted payment URL. 1-hour expiry. Same as v1 Payment Link.
Checkout Plugin — Modal overlay via Payload.js. Same concept as v1 Checkout Plugin.
Payment Form — Embedded form fields with custom CSS styling. Similar to v1 Secure Input but enhanced.
Payment API — Full backend control via direct API calls. Same as v1 direct transaction creation.
Payment Requests — One-time or reusable payment links with custom amounts/descriptions/expiry. Enhancement over v1 Payment Link.
Payment Pages — Branded payment pages for recurring use (tuition, rent, donations). New organizational concept in v2.

Migration note: v1 API-based payments map to Payment API. v1 Checkout Plugin/Page maps to Checkout Plugin/Link. v1 Secure Input maps to Payment Form. No functional changes, just organizational clarity in v2.

Account Architecture & Categorization

v1's separate Customer and Processing endpoints are unified under a single /accounts endpoint with polymorphic types in v2. Flexible labels and tiered KYC are coming soon.

See Architectural Shift → Unified Account Model for the full breakdown of account types, entity attachment, and what's coming next.

Migration note: Existing v1 accounts remain accessible as Customer/Processing under the unified /accounts endpoint. Flexible labels and tiered KYC become available when those capabilities ship.

Enrollment

v1 had Application Link (hosted form) and Processing Account Form (embedded modal). v2 renames both — Application Link becomes Enrollment Link (now backed by the unified Intent API) and Processing Account Form becomes Enrollment Plugin — and adds API-driven enrollment.

v1 pattern: Use form-based enrollment or build custom API-based onboarding. Payload provides hosted/embedded forms for convenience.
Enrollment Link (formerly Application Link) — Hosted enrollment form. Same concept as v1, but in v2 it's an Intent under the unified Intent API, sharing lifecycle, status model, and webhook events with other intent types.
Enrollment Plugin (formerly Processing Account Form) — Embedded modal for KYC collection. Same concept and capabilities as v1, just renamed for consistency with the rest of the v2 plugin lineup.
API-Driven Enrollment — NEW in v2. Submit entity data, bank accounts, and beneficial ownership directly via API. Processing Account + Entity created in one call. KYC triggers automatically. You keep full UI control.

Migration note: If using v1 form-based enrollment, no functional changes required — update references from Application Link to Enrollment Link and from Processing Account Form to Enrollment Plugin. If building custom flows, v2 makes this easier with explicit API-driven enrollment endpoints.

What's New Code Examples