FAQ
Common questions about migrating from v1 to v2
Will v1 stop working?
No. v1 is not being sunset and will continue to work indefinitely. v1 and v2 are fully interoperable on the same platform, so you can continue running v1 or adopt v2 incrementally on your own timeline. That said, all new feature development is on v2 — if you want to access net-new capabilities like synthetic accounts, dynamic funding, or instant payouts, v2 is required.
Do I need to re-onboard my existing accounts?
No. v1 and v2 are interoperable on the same platform, so existing accounts continue to work without conversion. The same accounts, entities, and payment methods are accessible through both API versions.
Will my existing payment methods (stored cards, bank accounts) carry over?
Yes. Payment method IDs are the same across v1 and v2 — no mapping or conversion script is required. The API surface for creating and referencing them changes slightly, but the stored tokens themselves remain valid and directly accessible from both versions.
Can I migrate incrementally, or do I need to migrate everything at once?
You can migrate incrementally. For example, start by migrating payment collection to v2 while keeping v1 billing in place, then migrate billing separately. Many integrators choose a feature-by-feature approach over a big-bang cutover.
What if I want to adopt v2 net-new features as part of the migration?
Excellent approach. Many integrators treat the migration of equivalent v1-to-v2 features as an opportunity to also implement net-new v2 functionality: Synthetic Accounts, Dynamic Funding, instant payouts, Processing Rules, and more.. These features often unlock new revenue opportunities and enable use cases that weren't possible in v1. Plan for extra development time in your migration timeline, and work closely with your Payload account team to design the architecture. Starting fresh with v2 gives you a clean foundation for these new capabilities.
Do I need v2 to use synthetic accounts, instant payouts, or dynamic funding?
Yes. These are v2-only features with no v1 equivalent. Migration to v2 is required to access any net-new capabilities.
What if I only use Payload for simple payment links?
The core flow doesn't change conceptually — you're updating the API surface and adding explicit account typing.
Can Payload help with the migration?
Yes. Your Payload account team can provide a migration assessment tailored to your integration, help configure processing rules and funding settings, and support sandbox testing.