To migrate recurring charges, confirm which credentials can be used at the destination, preserve each subscription’s identity, and maintain one authorized executor per cycle. Separate data transfer from the routing change and resolve pending charges before repeating commands. Cut over verifiable groups, with reconciliation, rollback criteria, and communication. Changing the endpoint does not make tokens portable or guarantee billing continuity.
The goal is to reduce interruptions and control exceptions, not promise a risk-free migration. Some subscriptions may change routes; others will need to remain temporarily at the source or update their payment method. The plan must recognize these differences before changing the scheduler that bills the entire portfolio.
This guide presents a proposed architecture and operating model, using a fictional portfolio of one thousand subscriptions. References were consulted on October 22, 2026. It does not expose AZPay’s internal processes, credentials, or customers, or assume the platform offers any of the portability options described.
What is being migrated beyond the payment API?
A recurring operation combines the commercial relationship, schedule, payment method, external credential, commands, and financial movements. The project must define which of these parts will change. Migrating only new sales differs from transferring an active portfolio; changing card capture differs from migrating execution of earlier charges.
The recurring payments and card-on-file guide separates subscription, cycle, and attempt. Preserve these identities during the transition. A customer should not acquire a second commercial subscription simply because the business now executes the same cycle through another processor.
Also include subsequent operations: querying old charges, capture where relevant, cancellation, refunds, disputes, and reports. A PSP may stop receiving new authorizations while remaining necessary to manage history. Ending that access too early compromises support and financial close.
Write a scope statement covering eligible methods, countries, currencies, commercial models, and cohorts. Record what remains at the source and who owns each exception. This statement supports continuity discussions based on the actual portfolio, instead of defining completion as changing a URL.
How do you inventory credentials without assuming portability?
For each subscription group, identify who issues the token, which service can resolve it, which routes can use it, and how its lifecycle is tracked. Record capabilities, not primary card data in a project spreadsheet. Operational references must also follow internal access controls.
A vault token may simply be an identifier belonging to the source provider. The destination does not gain the ability to use it just by receiving a string with the same value. Adyen’s documentation for importing from another provider (opens in a new tab ↗) illustrates a coordinated migration, with customer references, formats, and transfers agreed between participants. This process does not demonstrate universal portability.
Network tokens require a different analysis. The EMV Payment Tokenisation reference guide (opens in a new tab ↗) describes controls that restrict how and where tokens can be used. Confirm destination compatibility, usage domain, and the data required for processing, rather than treating a network token as an unrestricted credential.
The inventory must also distinguish credentials to be migrated, credentials that will remain accessible only at the source, and situations requiring new customer interaction. The explanation of PAN, vault, and network tokens provides context; the project must obtain concrete answers from its contracted participants.
What evidence should exist before transfer?
Confirm that source and destination accept the process, what responsibilities they assume, and how submission, receipt, and outcome will be evidenced. Define the identity linking the previous record to the new one, along with rejection handling. Confirmation that a file was received is not confirmation that every credential is usable.
Adyen’s import results documentation (opens in a new tab ↗) illustrates the return of a migration result. Use this kind of evidence to check mappings and outstanding items, without copying a supplier’s format as if it were a market standard or implementing manual transfers of sensitive data.
PCI SSC FAQ 1092 (opens in a new tab ↗) clarifies that outsourcing processing does not eliminate a merchant’s responsibility to protect data and monitor the service provider. The project should involve the teams responsible for the applicable scope and controls, including the transfer channel defined by the providers.
Do not place PANs, CVVs, or credential files in support tools, repositories, logs, or project messages. PCI SSC FAQ 1318 (opens in a new tab ↗) distinguishes retention of necessary data from the prohibition on storing sensitive authentication data after authorization. The editorial runbook should stay at the level of responsibilities, references, and evidence, without teaching informal exports.
How do you map states and operations between PSPs?
Build a semantic mapping before converting names. A state called success may mean authorization in one API and another stage in another service. Compare the events that permit charging, delivery, cancellation, and refunds. Where no equivalent exists, preserve the distinction instead of forcing a misleading common status.
For each operation, document the precondition, external reference, conclusive result, pending situation, and query mechanism. Include the idempotency rule and its window where available. Sending the same key to two PSPs does not provide a shared guarantee of single execution.
One proposal is to keep subscription and cycle as stable internal identities, with independent external attempts. Each attempt preserves its provider, reference, and outcome. The route chosen to execute a cycle must be explicit data, not an inference drawn from the last token found in the customer record.
The guide to idempotency in payment APIs develops command-level controls. During migration, add cycle ownership control: which executor may initiate the next action and what evidence allows that responsibility to transfer to another.
How do you prevent two schedulers from charging the same billing period?
Running two integrations during the transition may be necessary; executing the same financial cycle in both must not happen accidentally. The application must decide the owning route before dispatching the command. A transactional exclusion rule per subscription and billing period can protect that decision, depending on the business model.
Use a routing version or equivalent mechanism to invalidate old decisions. Changing a PSP field in the customer record is not enough if a job has already queued a charge at the source. The consumer must check whether it is still authorized to execute and whether that cycle already has an attempt in progress or a recorded completion.
When an outcome at the source is unknown, keep the cycle under investigation. The destination token may be ready, but that does not prove a new charge is safe. Query the attempt, correlate events, and reconcile. The payment failover policy applies the same principle to route switching during a failure.
Coordinate manual commands too. Support, operational dashboards, and jobs must consult the same obligation identity. A block only in the automatic scheduler leaves support able to initiate a second charge while trying to help the customer.
Fictional scenario: how do you partition one thousand subscriptions?
Consider a synthetic portfolio of 1,000 monthly subscriptions, without real prices or data. The inventory identifies 600 with credential mappings validated for the destination, 250 still dependent on the source, and 150 requiring the customer to update their payment method. The groups total 1,000 and must not be merged into a single cutover decision.
Among the 600 mapped subscriptions, 50 still have a charge with an unknown outcome at the source. Therefore, only 550 are candidates for operational cutover at that moment. The complete classification is: 550 candidates, 50 under investigation, 250 retained at the source, and 150 awaiting a new credential. The total remains 1,000.
These quantities are not forecasts or universal eligibility criteria. They show how to avoid confusing a migrated credential with a subscription ready to bill at the destination. The 50 outstanding cases can change groups only after their outcomes and next billing periods are clear.
Choose a pilot from the 550 candidates using criteria defined before execution: destination capacity, sufficient variety to exercise the flow, and acceptable operational impact. A pilot selected only from the simplest cases validates the basic path but does not prove the whole portfolio will behave the same way.
The 250 retained at the source need their own schedule and owner. For the 150 requiring updates, provide a legitimate journey to obtain a new credential, explain the action needed, and track abandonment and confirmation. Do not announce a completed migration because the 550 candidates processed correctly while the rest were left without a plan.
How do you structure preparation, the pilot, and cutover?
During preparation, validate the destination integration and mappings without initiating duplicate charges in production. Exercise command issuance, webhooks, queries, and subsequent operations using appropriate data and environments. Demonstrate that the system can distinguish testing, preparation, and actual financial execution.
During the pilot, enable only the authorized group and maintain exposure limits and stop criteria. Observe the relevant full cycle: not just the authorization response, but commercial updates, capture where applicable, reconciliation, and support capability. A migration may look healthy until the first refund or financial close.
For cutover, record which cycles belong to which route, the decision version, and activation time. Reassess old queues and reserved commands before releasing execution at the destination. A message created before cutover cannot decide on its own that it remains authorized to charge afterward.
Then expand the population based on evidence. A new cohort should be explainable through the inventory and results, not pressure to finish the project on an arbitrary date. A business deadline can guide planning; it does not turn incompatible credentials or unknown outcomes into safe cases.
What should trigger a halt or rollback?
Define conditions before the pilot: confirmed duplication, inability to correlate receipts, ownerless commands, a material increase in errors, or inability to perform critical subsequent operations. Quantitative limits must come from the operation and its approved tolerance; this guide does not invent percentages suitable for every business.
Stopping expansion differs from returning the entire portfolio to the source. First block new commands for the affected group, preserve outcomes, and identify cycles not yet executed. A configuration rollback does not undo an authorization, capture, or payment that has already occurred.
Allow a new execution at the source only if it can still process the credential, the obligation is unsatisfied, and the destination attempt’s outcome has been sufficiently resolved. If any condition is missing, the appropriate action may be to keep the charge pending and investigate, rather than trying to restore availability through duplication.
The backout plan must include whether a return is actually possible. If the old credential has been deactivated or the contract terminated, the former route may no longer exist. Reversibility must therefore be proven before being used as a reason to accelerate cutover.
Also record who decides to halt, who executes the change, and what evidence is preserved. During an incident, an ownerless decision can create competing route versions across dashboards and queues. A single source for operational decisions reduces that risk, provided every consumer respects its version.
How do you maintain webhooks and history during coexistence?
Source and destination may continue producing legitimate events about different objects. Validate each sender using the documented mechanism and preserve provider context in the external identity. Two identical references in different services must not collide in internal processing.
A late event from the source may complete a charge from before cutover. It needs to update that attempt and that billing period, without changing every subscription’s preferred PSP again. Likewise, a destination event must not overwrite the history of a refund still managed at the source.
Retain references linking customer, subscription, cycle, attempt, and financial movement. If there is a new credential identifier, maintain its mapping to the previous one to the extent needed for investigation and in accordance with access and retention policy. The token is a payment method reference, not the customer’s entire identity.
Plan for recovery of lost messages. Queries and verification routines must know both providers while operational obligations remain at each. Shutting down the old consumer on cutover day can cause a technically successful migration to produce outstanding items that only emerge at financial close.
What must be reconciled before shutting down the source?
Reconcile credential migration results with the commercial inventory: how many were accepted, rejected, replaced, or still await action? Then compare planned cycles and executed commands. Every billing period must have an explanation for being paid, pending, canceled, or outside scope.
At the financial layer, preserve captures, fees, refunds, disputes, receivables, and payouts according to the methods and contracts. The destination does not automatically learn these historical facts. Reconciliation across sale, capture, and settlement helps define sources and timing differences.
Close must work in both directions. From a subscription, find its charges at each PSP; from a financial line item, find the corresponding cycle and obligation. Any orphaned movement needs classification and handling, rather than being discarded because it belongs to the integration being decommissioned.
Before terminating contracts or access, confirm how queries and subsequent operations will continue and how long they will be needed. That decision depends on actual obligations, products, and contracts. Retain only necessary access and data, but do not remove the operational capability that history still requires.
How do you communicate the transition to subscribers?
Explain the specific action expected when a payment method update is required. State the legitimate channel for doing so and ensure support can distinguish a credential update, pending charge, and subscription cancellation. Avoid messages that prompt manual payment without checking an attempt in progress.
Do not promise that customers will never notice a change. The name displayed on the statement, authentication requirements, update flow, and billing terms may depend on the participants. Anticipate confirmed differences and validate the copy with those responsible for the commercial experience.
If the new credential is not confirmed in time, apply the product policy for continuity or a grace period. A migration issue must not automatically be classified as customer disinterest. Measuring the source of failure helps avoid incorrect communications and access decisions that are difficult to explain.
How do you test concurrency and recovery before cutover?
Run a test in which two jobs reserve the same billing period simultaneously, one using the old version and the other the new one. The expected result is a single execution authorization; the loser must recognize the existing state and record its decision. This test checks a property that does not appear when each integration is exercised in isolation.
Next, interrupt the process after submission to the source and before persisting the response. Activate cutover while the attempt’s outcome is unknown. The new executor must keep that obligation blocked, query or await evidence, and avoid creating another charge at the destination. The test succeeds when the unknown outcome is preserved until resolution.
Resend an old webhook after a credential update. It must find the original attempt without changing the customer’s current token or granting the same period again. Also simulate commercial cancellation while an instruction is prepared: the decision must account for a financial operation that may already be underway.
Finally, exercise a destination failure during the pilot. Operations must be able to block expansion, list affected cycles, and identify those that can return to the source. Check this set individually: some payments will already have confirmed outcomes, while others will be pending. A single list of affected subscriptions is insufficient for deciding on safe retries.
Does the plan apply to Pix, boleto, and other methods?
The discipline of identity, cycle ownership, and reconciliation is shared; credential migration is not. Cards may involve a vault and token. Other methods may depend on an issued charge, permission, institution, or different contract. Inventory these dependencies separately instead of trying to convert every method into a column called token.
For recurring Pix, the guide to Pix Automático and cancellation distinguishes authorization, instruction, and commercial subscription. Check with the participants how changing service affects that relationship and whether a new journey is necessary. The existing commercial relationship alone does not demonstrate that the destination can initiate the same payments.
What checklist makes the plan executable?
Before the pilot, confirm the inventory by credential type, compatibility and authorization of the process between providers, state mappings, stable commercial identities, and mappings of migrated records. Every item needs evidence and an owner. A list merely marked discussed does not yet demonstrate execution capability.
Before cutover, confirm a single owner per cycle, reviewed old queues, isolated unknown attempts, webhooks for both routes active where needed, and ready query and reconciliation routines. Record the enabled subscription set and decision version to support later auditing.
Before expanding, verify pilot results, open discrepancies, support readiness, an exercised stop mechanism, and a genuinely viable return path. Include tests for lost responses, late events, duplicate jobs, and credential changes during cutover. Acceptance means controlling effects, not simply obtaining a successful HTTP response.
Before closure, explain the disposition of all cohorts, responsibility for historical operations, and reconciliation of amounts. The portfolio may have been correctly migrated in part; if so, describe the remaining portion and its plan rather than hiding it inside an aggregate success percentage.
The expected result is a transition whose next action can be chosen based on evidence: charge at the destination, retain at the source, wait for resolution, or request an update. To assess an AZPay integration, consult Dev Central and confirm capabilities and contracts. Continuity comes from coordinating credentials, cycles, and money, not assuming every token changes providers with the same meaning.