Card migration
When you switch from one payment processor to another, card migration transfers stored guest payment tokens so that guests do not need to re-enter their card information. The process uses a CSV-based upload workflow with automated processing and status tracking.
Before you begin
Permission: Configure Payment Settings (under Payments) β Required to initiate and manage card migrations. The Card migration row under Process payments is shown to Zenoti support logins only.
- Both the source and destination payment processors must be configured for your organization.
- Plan migrations during low-traffic periods to minimize impact on guest payments.
How card migration works
Card migration transfers tokenized card data from one processor to another. The process involves three phases:
- Download β Export existing card data from the source processor.
- Upload β Prepare the migration file using one of four CSV template variations (based on the source and destination processor combination) and upload it.
- Monitor β Track migration status with automatic polling every 30 seconds until completion.
CSV template variations
Each source-to-destination processor pair uses a specific column schema. Use the template that matches your migration direction:
| Template | Source processor | Destination processor | Key columns | Notes |
|---|---|---|---|---|
| Adyen β Stripe | Adyen | Stripe / Stripe Connect | shopperReference, recurringDetailReference, cardSummary, cardType, cardExpiryMonth, cardExpiryYear |
Re-tokenization happens on Stripe's side using Adyen network tokens. |
| Stripe β Adyen | Stripe | Adyen | stripeCustomerId, paymentMethodId, last4, brand, expMonth, expYear |
Stripe customer ID maps to Adyen shopperReference. |
| Stripe β Stripe (account-to-account) | Stripe | Stripe (different merchant account, e.g., Stripe Connect Express) | sourceCustomerId, destinationCustomerId, paymentMethodId |
Used during multi-entity rollout. |
| Adyen β Adyen (account-to-account) | Adyen | Adyen (different merchant account) | sourceShopperRef, destShopperRef, recurringDetailReference |
Used when consolidating merchant accounts. |
Use the source-processor download as the starting point and map columns to the template that matches your destination. Worldpay, FreedomPay, and BBVA migrations to or from Adyen/Stripe are not supported through the self-service card migration UI β contact Zenoti Support.
Impact on recurring payments during migration
While a migration is in flight, recurring payments continue to use the source processor's tokens. After migration completes successfully:
- New recurring charges automatically use the destination processor's tokens.
- Any recurring charge that was queued but not yet attempted at the moment of cutover routes to the destination processor.
- If a token failed to migrate (visible as an Error row in the result file), the next scheduled recurring charge for that guest will fail. Update the guest's payment method in the guest profile or send a re-collection link.
Plan the migration during a low-traffic window and pause any scheduled batch collection jobs during the migration to reduce in-flight churn.
Run a card migration
- Navigate to Card Migration in the payments section.
- Select the Source Processor and download the existing card data CSV.
- Prepare the migration file using the appropriate CSV template for your source-to-destination processor combination.
- Select the Source Processor and Destination Processor.
- Upload the prepared CSV file (drag-and-drop is supported).
- Click Start Migration.
- The system begins processing. The status updates automatically β you do not need to refresh the page.
- When complete, download the result file. The result is in Excel format and contains either:
- Success records β Cards that migrated successfully.
- Error records β Cards that failed with per-card error details.
Migration statuses
| Status | Meaning |
|---|---|
| Pending | Migration request created, waiting to start. |
| Processing | Migration in progress. Cards are being transferred between processors. |
| Completed | All cards processed. Download the result file to review outcomes. |
| Failed | The migration encountered a system-level error. Contact support. |
| ValidationFailed | The uploaded CSV contains invalid data. Review the error details, correct the file, and re-upload. |
Handle failures
- ValidationFailed: Review the validation errors in the result file. Common issues include incorrect column mappings, missing required fields, or invalid card data. Correct the CSV and re-upload.
- Partial failures: Some cards may migrate successfully while others fail. The result file shows per-card status. For failed cards, review the error reason and determine whether to retry or manually update the guest's payment method.
For card migration between processors and stored payment account management, see the Integrations category.