v1 to v2 Migration Guide

What changed, what's new, and what it takes to upgrade

Reasons to Migrate to v2

v2 is a ground-up rework of the API surface, delivering a cleaner object model and net-new capabilities that v1 couldn't express. The result is a more intuitive, flexible, and unified experience — whether your integration is simple or complex.

Highlights

• Universal transaction model — A simplified transaction object handles all money movement — payments, payouts, refunds, transfers, wires, deposits, withdrawals, and dynamic funding — with explicit sender and receiver fields that make fund flow clear in every scenario. Simpler code, fewer edge cases, consistent webhook events.
• Unified account model — A single /accounts endpoint with polymorphic types replaces v1's separate customer and processing endpoints. Processing accounts gain customer-like capabilities (sending payments, receiving payouts, acting as payer on invoices), and new account types like synthetic can be added without reworking integrations.
• Expanded entity system — v2 generalizes the Entity object so any account type can attach one, entities can represent either a business or an individual, and international identities are supported with country-specific tax IDs and verification.
• Unified API concepts — Consistent patterns and conventions across the entire API surface, including a unified Intent API that consolidates checkout links, payment forms, and enrollment flows into a single polymorphic object.
• New capabilities — Dynamic funding, instant payouts via RTP, invoice item grouping, API-driven enrollment, synthetic accounts, unified intent API, net fee billing, billing statements via API, alternative payment types (digital wire, Check21), advanced controls like processing rules, and much more.

What Stays the Same

v2 is a new API surface on the same battle-tested platform. The underlying processing infrastructure, PCI compliance, Payload Polygraph (fraud detection and risk management), and Payload Protect (underwriting policy for use cases requiring good funds) all carry over unchanged. Every v1 payment method — cards, ACH, Same Day ACH, EFT, digital wallets (Apple Pay, Google Pay), Plaid, checks, and wires — remains fully supported in v2.

Incremental Migration

v1 and v2 are fully interoperable — both endpoints run side-by-side on the same platform and operate against the same underlying data. Transactions, accounts, and payment methods created in v1 remain accessible through v2 APIs, and vice versa. This lets you migrate incrementally, moving one feature area (payment collection, billing, payouts) to v2 at a time while the rest of your integration continues to run on v1.

Migration Resources