Architectural Shift

v2 refines and extends the v1 architecture across a few foundational areas: money movement, accounts, identity, funding, and user-facing interactions. Understanding these changes will make the rest of the migration straightforward.

Transaction Model Evolution

The most foundational change to the transaction model is how funds flow is expressed. In v1, transactions specified a customer_id and a processing_id, and the direction of funds was inferred from the transaction type — a payment meant money moved from the customer to the processing account, while a credit (payout) meant the reverse. This implicit directionality became increasingly awkward as scenarios grew more complex.

v2 replaces this with explicit sender and receiver fields on every transaction. Funds flow is clear from the object itself — regardless of transaction type, whether it's a payment, payout, transfer, refund, or split. Any account can act as sender or receiver, which also unlocks scenarios like processing-to-processing transfers, synthetic account funding, and multi-party splits without special-casing.

Beyond the sender/receiver shift, v2 also adds explicit type names (payout, refund, deposit, withdraw) and the transfers array for Dynamic Funding — but the unified /transactions endpoint concept itself was already present in v1.

Unified Account Model

v1 exposed Customer and Processing accounts as separate endpoints, each with its own object model. v2 unifies them under a single /accounts endpoint with polymorphic types, so accounts can be queried, filtered, and managed generically — and new account types can be introduced without adding new endpoints or reworking integrations.

• Customer Account — Payers and recipients. Used for sending payments and receiving payouts. No inherent processing capability. No KYC requirements for basic usage. Concept unchanged from v1.

• Processing Account — Merchant or vendor accounts that receive payments, send payouts, and manage automated funding. The concept is unchanged from v1, but v2 decouples identity into a dedicated Entity object that must be attached for KYC verification. v2 also expands processing account capabilities beyond the merchant role — they can now send payments, receive payouts, and act as the payer on payment links or invoices, just like customer accounts. Supports custom pricing, funding rules, and bank account configurations for settlement.

• Flexible Categorization — Coming soon in v2. Accounts will support any label (User, Client, Agent, Vendor, Partner, etc.) in addition to Customer/Processing, enabling custom business logic without account type constraints.

Expanded Entity System

v2 generalizes the Entity object so any account type can be associated with one, and entities can represent either a business or an individual.

• Individual entities — NEW in v2. For people. Captures name, date of birth, SSN/SIN, address. Used for sole proprietors, individual customers, and payout recipients.

• Business entities — For companies. Captures business name, EIN/BN, address, plus stakeholders with ownership percentages for beneficial ownership compliance. Carried over from v1 with expanded attachment flexibility.

• Universal attachment — NEW in v2. Entities can be attached to customer accounts, processing accounts, or any other account type. v1 restricted entities to processing accounts only.

• Internationalization — NEW in v2. Entities support international identities with country-specific tax IDs, address formats, and verification requirements, enabling KYC/KYB flows for non-US businesses and individuals.

• Reusable — One Entity can be attached to multiple accounts. If a business operates several Processing accounts (for example, separate locations or subsidiaries), it verifies once and those accounts share the same Entity.

• Tiered KYC — Coming soon in v2. Entity objects will support Level 1 (Screening), Level 2 (Light KYC/KYB), and Level 3 (Full KYB). v1 had inline identity info; v2 separates and tiers it.

Funding Architecture Evolution

v1 had net/gross/itemized settlement modes with limited visibility. v2 expands this into a fully configurable, tiered funding system.

• Funding styles — v2 carries over v1's net, gross, and itemized styles and adds manual for no automatic disbursement.

• Funding timing tiers — v1 had standard settlement only. v2 has standard (account default), rapid (accelerated), or instant (Real-Time Payments via RTP + synthetic accounts).

• 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.

• Dynamic funding transfers — NEW in v2. The transfers array on a transaction directs how funds are split across multiple processing or synthetic accounts at funding time. Unlocks multi-party splits, platform fee collection, revenue sharing, and marketplace payouts in a single atomic transaction.

Unified Intent API

v1 handled user-facing interactions — checkout links, payment forms, enrollment links, payment method forms — across a mix of shared and distinct endpoints and object models. v2 consolidates these under a single Intent API, where all user-initiated flows are represented as polymorphic Intent objects with a shared lifecycle, status model, and webhook events. This makes it simpler to build, track, and respond to user interactions across the platform without maintaining separate integrations for each surface.