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 or NMI — 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.

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.

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 minimum delay periods (e.g., in hours or days) between retry attempts. A setting of zero implies no delay.

Preferred Days — Choose to use preferred billing days for retry attempts.

Custom Selection — Apply custom MID selection logic for the retry attempt.

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 — Retry number is the sequential order of the retry attempt. You can re-order the steps by dragging the steps around.

Original Price — This switch determines if the original transaction price is used for the retry. Disabling 'Original Price' reveals a Price input field, allowing specification of a custom amount for the retry.

Extend to Preferred Days — Extend to preferred days will extend the retry attempt to the preferred days of the week if turned on. Preferred days are internally set by the platform and cannot be changed at this time.

Price — Price is the amount that will be used for the retry attempt. If the original price is turned off, this field will be required. The price must be greater than 0.

Custom Selection — This dropdown allows selection of a specific Merchant ID (MID) routing logic for the retry attempt. The default, None, means the system uses your standard MID routing configuration for the applicable scenario (e.g., Issuer Declines). The available options are:

Default (None)
Sale Shield: Routes the retry attempt through a Sale Shield-designated MID. This requires an active Sale Shield integration on your account and is designed to optimize approval for specific transaction types.

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.

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 and NMI — 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.