ZenotiHelp

Card migration

ZTZenoti Docs Team Updated September 17, 2026 3 min readGuide

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:

  1. Download β€” Export existing card data from the source processor.
  2. Upload β€” Prepare the migration file using one of four CSV template variations (based on the source and destination processor combination) and upload it.
  3. 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

  1. Navigate to Card Migration in the payments section.
  2. Select the Source Processor and download the existing card data CSV.
  3. Prepare the migration file using the appropriate CSV template for your source-to-destination processor combination.
  4. Select the Source Processor and Destination Processor.
  5. Upload the prepared CSV file (drag-and-drop is supported).
  6. Click Start Migration.
  7. The system begins processing. The status updates automatically β€” you do not need to refresh the page.
  8. 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.

Was this article helpful?
Your feedback helps us improve our documentation.