Migrate cards between processors
When you switch payment processors, you can migrate stored card tokens from the old processor to the new one. Card migration re-tokenizes saved cards with the new processor so guests do not need to re-enter their card details.
Before you begin
Who runs it: The Card migration console (Configuration > Payments > Process payments > Card migration) is available only in a Zenoti support session; it does not appear for a customer login. Zenoti Support runs the migration with your organization administrator.
Prerequisites
- Both the source processor and the destination processor must be configured in Zenoti.
- Card migration requires that both processors' acquirer relationships and scheme certifications support a network-level token export / import. Many processors do not support this. Confirm with your new processor's technical account team before starting.
- Coordinate the migration timing with your payment team to minimize disruption.
External-system prerequisites
Token migration is a third-party operation. Zenoti triggers the export / import but the heavy lifting happens between the two processors and the card networks.
- Source processor β must support a bulk-export of tokens to a receiving processor. Some processors charge a per-token fee; some require advance notice.
- Destination processor β must accept the import and re-tokenize each card. Timelines vary β plan for several business days.
- Scheme approval β for Visa and Mastercard, network-token migration requires merchant attestation that the token will be used within the same MID (Merchant Identifier) relationship.
Network requirements
Token migration is a back-end operation; there is no real-time guest interaction. Standard outbound HTTPS (port 443) from Zenoti to both processors is sufficient. No additional firewall changes are usually required.
Source of value
| Item | Source |
|---|---|
| Source processor configuration (MID, credentials) | Already present in Zenoti β verify it's still active. |
| Destination processor configuration (MID, credentials) | Must be fully configured and tested before migration. See Set up a payment processor. |
| Migration approval / fee agreement | Signed with both processors' merchant-services teams. |
Steps
Initiate a card migration
- Contact Zenoti Support with the source processor (the processor you are migrating away from), the destination processor, and the centers in scope; agree a low-activity window.
- In the support session, Support opens the Card migration console and creates the batch (New Card Migration) for the source and destination processors.
- Review the migration details with Support and confirm the number of stored card accounts to be migrated.
- Support selects Start Migration.
Monitor migration progress
- Zenoti begins migrating card tokens in batches.
- Support follows the progress in Migration Reports and shares it with you.
- Cards that fail to migrate are flagged with error details.
- After migration completes, review the failed cards list and manually handle any exceptions (for example, by contacting the affected guests to re-enter their card details).
Verify migration
- After migration completes, process a test transaction with a migrated stored card to confirm it works correctly with the new processor.
- Check that recurring payment schedules (memberships, packages) use the migrated card tokens on the new processor.
Failure modes
| Failure mode | Typical cause | Resolution |
|---|---|---|
| Source processor unreachable | Source processor credentials expired or processor API down. | Re-authenticate source; retry the batch. |
| Destination processor reject | Destination processor refuses a token β common reasons: Amex excluded, card scheme not supported at destination, token age-out. | Flag for manual re-enrolment; contact the guest. |
| Card already expired at migration time | Migration is not a card-update event; expired tokens migrate as expired. | Use Update card details automatically after migration where supported, or manually re-enrol. |
| Amount-limit mismatch (post-migration) | Destination processor has different minimum / maximum limits; first charge fails. | Review the destination processor's limits before go-live. |
| Currency mismatch | Destination MID not activated for the center's currency. | Activate the currency with the destination processor before migration. |
| Network-token governance rejection | Scheme declines the token transfer because the two MIDs are not in the same ownership relationship. | Work with both processors to resolve β may require scheme paperwork. |
Migration β dual-system perspective
| System | What happens |
|---|---|
| Zenoti | Stored-account records are updated to reference the new processor's token. Old token is retained in audit logs. |
| Source processor | Tokens are flagged as exported; depending on the processor, they may remain usable for a grace period or be invalidated immediately. |
| Destination processor | Tokens appear in the destination vault against your MID; recurring schedules in Zenoti start charging them on the next billing date. |
Reconciliation during migration
Run a reconciliation cycle before, during, and after migration:
| Phase | Zenoti view | Processor view | What to check |
|---|---|---|---|
| Pre-migration | Collections report for the last 30 days | Source processor settlement report | Count of stored-card charges per day to establish a baseline. |
| During migration | Migration status dashboard | N/A | Zenoti-internal only. |
| Post-migration | Collections filtered by destination processor | Destination processor settlement report | First-week success rate β if it drops below the baseline, migration had failures. |
Tips
- Schedule card migrations during off-peak hours to avoid disrupting payment processing.
- Notify guests in advance if there is any possibility that their stored card will need to be re-entered after migration.
- Not all processor pairs support token migration. If migration is not available for your combination, guests will need to re-enter their card details after the switch. Processors using local-only tokens (EzyPay, Payment Express, Moneris, Payworks) are particularly common for manual re-enrolment.