Guides

How to set up and use every part of Payzo — from your first checkout to advanced multi-MID routing.

Getting Started

Connect a merchant account from Merchants (Stripe, NMI, Airwallex, Adyen, Payarc, or Authorize.Net), then create a plan under Plans and a checkout page under Checkout. That checkout's URL is what you share with customers or embed on your site.

Once you have real subscribers, the rest of Payzo is about resilience: routing across multiple merchant accounts (MID Groups + MID Selection) and automatically retrying failed renewals (Retry Strategies) so a single processor problem never takes your revenue down with it.

Prefer to integrate programmatically instead? See the API Reference →

Checkouts

A checkout is a hosted page a customer uses to subscribe to one of your plans. Create one from Checkout → Create checkout, pick a plan, and choose a template — Classic (split-screen, plan details on one side, card form on the other) or Shopify Original (order-summary sidebar, contact/payment on the left).

Each checkout has its own store name, logo, accent color, description, and bullet points, all editable from the checkout's builder page — with a live preview that updates as you type.

Cards are always tokenized in the customer's browser (via Stripe.js or Basis Theory, depending on the connected processor) — Payzo's servers never see a raw card number.

For a Stripe-connected account, checkout uses Stripe.js/Elements by default — this is the only option visible from the account settings UI, and it's what nearly every account should use. A Basis Theory-powered custom card form is also supported for Stripe accounts, but only works if Stripe has separately granted that specific account raw card data API access (a manual, per-account approval — contact Stripe support to request it). Enabling this without that approval will make every charge on the account fail, so it's set at the database level rather than exposed as a self-serve toggle.

Template Builder

For full control over layout, build a custom checkout template from Templates → New template. Drag blocks — order summary, payment form, submit button, wallet buttons, discount code, upsell — onto the canvas, then set a page-wide theme (colors, font, border radius) from the Theme tab.

Templates have a draft and a published version — changes only go live once you click Publish, so you can safely experiment without affecting the checkout your customers currently see.

An AI Assistant tab in the builder can build or adjust the block layout for you from a plain-English description.

Subscriptions

The Subscriptions page lists every active and historical subscription across your connected accounts, with filters covering search, account, status, migration eligibility, card brand, processor, MID group, assigned retry strategy (issuer decline and insufficient funds separately), decline history, and date ranges for both when a subscription was acquired and its next billing date.

Filters apply live as you change them — no submit button — and combine, so e.g. Status: Active + Card brand: Visa + MID group: East Coast Pool shows only that exact slice. The search box debounces briefly while you type; every other filter updates the results immediately. Use Clear all to reset every filter at once.

MID Selection

Build rules that decide which merchant account (MID) a transaction should use, then apply those rules to the scenarios where routing decisions actually happen.

A MID Selection Rule is a named set of conditions. Each condition narrows down which MID is eligible for a transaction: for example, preferring a MID with the same brand, or a different acquiring bank than the one that just declined. Rules don't take effect on their own; they're only used once bound to a Scenario.

Conditions

Conditions are the building blocks of a rule. Each one filters or ranks the candidate MIDs, matching on brand, master brand, corp, PSP, acquiring bank, vertical, or customer/bank history. Add a condition by clicking it in Available Conditions or dragging it into Selected Conditions; remove one the same way in reverse.

"Same" and "Different" conditions of the same category (e.g. Same Brand / Different Brand) are mutually exclusive: selecting one disables the other, since they contradict each other.
Reordering Selected Conditions changes their Priority: condition 1 is evaluated before condition 2, and so on.

Mandatory vs. Preferred

Each selected condition is either:

Mandatory: a MID must satisfy this condition to be considered at all. If no MID satisfies every mandatory condition, the rule has no eligible MID.
Preferred: used as a tiebreaker to rank otherwise-eligible MIDs, but a MID that fails a preferred condition is still eligible, just ranked lower.

The toggle next to each condition turns it on or off without removing it from the rule, useful for temporarily disabling a condition while you test.

Default vs. Custom Rules

Every organization starts with four default rules: Global Default Cross Sale, Global Default Mid Retries, Global Default Mid Selection, and Global Default Porting. Default rules can't be edited or deleted; they exist as a safe, always-available fallback.

To customize routing logic, create a new rule with the New MID Selection Rule field and Create Rule button. Custom rules are fully editable and deletable.

Applying Rules to Scenarios

The Scenarios panel is where a rule actually starts controlling routing. Each scenario represents a distinct moment routing decisions get made:

Issuer Declines for MIT (Retries): when a merchant initiated transaction (e.g. a rebill) is declined by the issuer.
Issuer Decline Retries for CIT (Cascades): when a customer initiated transaction (e.g. an initial sale or subscription signup) is declined by the issuer.
Cross Sale: when a customer is opted into an additional service (e.g. a premium or second subscription).

Pick a rule from each scenario's dropdown to bind it. The change is applied immediately, no separate save step required.

Only the Issuer Declines for MIT (Retries) binding actually runs anything today: it's consulted whenever the retry engine considers moving a renewal to a different account. CIT (Cascades) isn't wired up yet (see the Retry Strategies guide for why), and Cross Sale has no execution path at all yet, so those two bindings are config-only for now.

Building a Rule Step by Step

Create the rule

Enter a name in New MID Selection Rule and click Create Rule. It appears in the list, tagged Custom, and opens for editing.

Add conditions

Click (or drag) conditions from Available Conditions into Selected Conditions. Conflicting conditions grey out with an explanation until you remove the one they conflict with.

Set requirement, priority, and enabled state

For each selected condition, choose Mandatory or Preferred, drag to set its priority order, and use the toggle to enable or disable it without removing it.

Apply it to a scenario

Head to the Scenarios panel on the right and pick this rule for whichever scenario should use it.

Retry Strategies

Understand how to design, implement, and manage sophisticated retry strategies for failed Merchant Initiated Transactions (MITs) to enhance payment recovery rates.

Retry strategies provide a robust and configurable framework for automating responses to failed Merchant Initiated Transactions (MITs). Each strategy comprises a sequence of customizable steps, allowing for nuanced control over retry conditions (such as decline types), pricing adjustments, and precise timing for subsequent attempts.

Overview

A retry strategy is a set of sequential steps that determine:

How many times to retry a failed transaction
What price to use for the retry attempt
Use preferred days for retry attempts
Custom selection logic for optimal retry success

"Retry strategies are essential for maximizing transaction success rates while maintaining control over retry timing and pricing."

Strategy Step Configuration Options

Each retry step includes several key options:

Price Settings: configure whether to use the original transaction price or a custom amount for the retry attempt.

Timing Rules: define the minimum delay (in hours) before this retry attempt fires.

Preferred Days: when on, a retry that would otherwise land on a Saturday or Sunday is pushed to the following Monday instead.

Custom Selection: route this specific retry step through a MID Group instead of the account the original charge was on.

Creating a Strategy

Access Retry Strategies

Navigate to Retry Strategies in the main navigation menu within the platform.

Create a New Strategy

You have two options for creating a strategy:

Create an empty strategy by entering a name and clicking Create Strategy
Use a template by clicking Create from Template

Configure Strategy Steps

The following parameters can be configured on a step:

Retry Number: the sequential order of the retry attempt. You can re-order the steps by dragging them around.

Original Price: whether the original transaction price is used for the retry. Disabling 'Original Price' reveals a Price input field, allowing a custom amount for the retry.

Extend to Preferred Days: when on, a retry that would otherwise land on a Saturday or Sunday is pushed to the following Monday instead.

Price: the amount used for the retry attempt. Required once 'Original Price' is turned off, and must be greater than 0.

Custom Selection: which merchant account this specific step retries against. The available options are:

Default (same account): retries on the same merchant account the original charge failed on.
Route through a MID Group: pick one of your MID Groups, and the step retries against a weighted account inside it instead, using the same weighting MID Selection uses for a normal checkout.

Once you have configured the steps, you can add more steps by clicking the Add Retry Step button. When you are happy with your steps, you can click the Save button to save your strategy.

Apply to Subscriptions

Once a strategy is configured, it must be applied to subscriptions to take effect. This is typically managed on a per-subscription basis, allowing strategies to be tailored to specific decline scenarios.

To apply a strategy, first locate and select the relevant subscription. You can do this by searching by name or ID in the Subscriptions section or by navigating directly to Subscriptions via the main navigation menu within the platform.

Once you have selected and opened a subscription in a sidepanel, navigate to the Retry Strategy section.

Within this section, you'll select the decline scenario to which the strategy will apply:

Insufficient Funds
Issuer Declines

From the dropdown menu, choose the desired retry strategy. You can also search for the strategy by its name if you have many configured.

Once the strategy is selected for the scenario, click Update Subscription to save these changes and activate the strategy for that subscription.

⚠ Changes to retry strategies affect all linked subscriptions. Review carefully before applying.

Automatic Soft-Decline Retries

Separately from the configurable steps above, Payzo automatically retries a subscription once when its renewal fails with a soft/technical decline: a processor or issuer availability problem (e.g. a gateway timeout, "issuer unavailable", or a generic "try again"), not a problem with the card itself. This runs the moment the relevant webhook lands, a few minutes after the failure.

This auto-retry never fires for hard/issuer declines (stolen, lost, restricted, or flagged-fraudulent cards) or for funds/data declines (insufficient funds, expired card, incorrect CVC). Retrying those anywhere, on any account, doesn't fix the underlying problem and is what card networks treat as card testing. It is capped at exactly one attempt per decline.

Same account vs. a different MID

By default the retry re-charges the subscription's existing saved payment method on the same merchant account. It only retries on a different MID in the same MID Group when all of the following are true:

The original account has Allow Retries from Other MIDs enabled (Merchants → account settings, or the MID Groups page).
The target account also has that same setting enabled, since it's a two-way opt-in, not something one account can force on another.
Both accounts belong to the same MID Group.
The card was originally captured through the Basis Theory-powered form (NMI, Airwallex, Adyen, or a Stripe account with raw card data API access) rather than Stripe.js/Elements. Basis Theory tokens can be safely detokenized more than once, so each retry still goes straight from Basis Theory to the processor, and Payzo's own servers never see the raw card. A card captured through the default Stripe.js path can only ever be charged again on that same Stripe account, since Stripe's own PaymentMethod ids are scoped to the account that created them.

If a retry (same-account or cross-MID) still fails, the subscription stays in salvage and is not retried again automatically by this always-on safety net. It's picked up next by the configured strategy steps below, if one is assigned to the subscription.

How Configured Steps Actually Run

When a subscription has a retry strategy assigned (from the Subscriptions panel on the right, or the Subscriptions page), a decline schedules that strategy's first enabled MIT step: the wait is Min Hours Later, adjusted forward to the next Monday if Extend to Preferred Days is on and it would otherwise land on a weekend. If that attempt fails, the next enabled step in the list runs the same way; once the list is exhausted the subscription is left in salvage with no further automatic action.

A step's Custom Selection only takes effect when the card was captured through the Basis Theory-powered form, for the same reason the safety-net cross-MID retry above is scoped that way. On a plain Stripe.js checkout, every step in the cascade retries on the original account regardless of what Custom Selection says.

CIT cascades are not wired up to run automatically yet. A CIT cascade retries the very first checkout charge itself, before any subscription exists to attach a schedule to, so it needs to be triggered inside the checkout flow rather than from a decline webhook. Configuring CIT cascades on a strategy currently has no effect until that's built.

Best Practices

Strategy Design

Start Simple: Begin with straightforward strategies and incrementally add complexity. This helps in understanding their impact before introducing more intricate rules.
Pilot Testing: Always test new or modified strategies on a small, representative subset of subscriptions to mitigate potential risks and validate effectiveness before a full rollout.
Maintain Documentation: Thoroughly document the logic and rationale behind each strategy for clarity, team alignment, and easier future maintenance or adjustments.

Step Configuration

Incremental Delays: Implement incremental delays between retry attempts. This can prevent overwhelming payment gateways or cardholder accounts and allows time for transient issues (e.g., insufficient funds) to be resolved.
Timezone Awareness: When configuring retry timing, consider the cardholder's timezone to ensure retries occur at optimal and appropriate times, potentially increasing success rates.
Price Point Variation: Experiment with slightly different price points for retries, especially for certain decline reasons. Some declines might be linked to transaction amount thresholds, and a minor adjustment could lead to approval.

Monitoring

Continuous Monitoring: Regularly review the performance of your retry strategies using available analytics. This helps in identifying trends, measuring effectiveness, and spotting areas for optimization.
Granular Analysis: Track success rates for individual steps and configurations within your strategies. This detailed insight helps understand which approaches are most effective for different decline reasons or customer segments.
Data-Driven Adjustments: Use performance data to make informed adjustments to your strategies. This iterative process is key to continuously improving payment recovery rates and adapting to evolving payment landscapes.

MID Groups

Learn how to create and manage MID Groups in Payzo to optimize payment routing, approvals and business flexibility.

Payzo's MID Groups feature lets you combine multiple Merchant IDs (MIDs) into a single routing pool. This helps optimize transaction approval rates, distribute volume across processors, provide automatic failover and meet regional or product based requirements. The configuration happens in one place, making updates easy as your business grows.

What Are MID Groups?

A MID Group is a set of MIDs that you bundle together with custom logic. Payzo routes transactions across these MIDs to help maximize success, meet compliance needs and increase flexibility, without manual switching.

Key Benefits:

Higher approval rates by routing transactions to the best-performing MID for the card type, region, or other rules.
Built-in failover. If one MID is down or declines the transaction, Payzo immediately tries the next.
Easier scaling since you can add or change MIDs in a group without major disruptions.
Control over routing logic, such as geolocation, currency, risk profile, or product.

Common Use Cases

Merchants processing high volumes with more than one processor.
International businesses needing to route payments based on region.
Businesses aiming for maximum uptime during processor outages or card type restrictions.
Performance testing by sending a percentage of transactions to a new MID.

How to Create a MID Group

Open the MID Groups Section

Go to your Payzo Dashboard.
Navigate to Merchants → MID Groups.

Create and Name Your Group

Click Add Routing Group.
Choose which routing type you want to use and click Create.

The 2 Routing Group Types:

Manual Routing Group:

You have control to weight each added MID account.
Useful for routing transactions to a specific set of merchants.
Weighting determines the percentage of transactions that will be routed to the merchant.

Automatic Routing Group:

Once multiple MID accounts have been added, weighting is calculated automatically based on their current remaining capacity.
Useful and recommended if you want to route transactions to a specific set of merchants but want automated weighting.
A bias multiplier can be set to increase or decrease the weight relative to the other merchants.

Name the group and click Create to continue.

Add MIDs to the Group

Once the group has been created, click Add Merchant Account and choose a MID. Make sure that MID is set live first.
Set weighting or bias if you want priority routing.

Manual Routing Group:

It's recommended to prioritize the bigger-capped MID accounts — if multiple MIDs are weighted in order based on their cap, they'll sequentially move to another MID once the bigger MID fails.

Automatic Routing Group:

The bias multiplier can be increased or decreased relative to the other merchants.

Configure Options

Once a MID Group is set up, change the billing configurations in Subscriptions and Products.
Monitor the performance of each MID once they are set up.
If a MID or multiple MID accounts have been disabled, inform your account manager to check that MID account.

If there is an inactive MID account:

If a MID account is disabled due to cap being reached or manually paused, you do not need to remove it from the group.
It will automatically not be available for selection within the group; once active again, it becomes available again automatically.
This keeps maintenance to a minimum, without the need to swap MID accounts in and out.

Integrations

Connect a Shopify store from Integrations → Shopify to push a fulfillment order after every successful checkout, or to redirect a Shopify cart straight into a Payzo checkout at the real cart total (verified server-side, never trusted from the client). Shopify's own "Buy it now" / accelerated checkout button is hidden when the redirect is active — it can't be reliably intercepted, so shoppers are funneled through "Add to cart" instead.

The checkout redirect can also point at your own subdomain (e.g. checkout.yourstore.com) instead of a payzo.cc URL — add the domain in the redirect settings, add the CNAME record it gives you at your DNS host, then click Check verification. It falls back to the payzo.cc URL until verified.

Merchant accounts themselves (Stripe, NMI, Airwallex, Adyen, Payarc, or Authorize.Net) are connected from Merchants → Connect a new merchant. A Stripe account additionally needs its publishable key added (Stripe Dashboard → Developers → API keys) before real checkouts against it can accept cards.