---
title: "Cascade Profiles"
description: "Retry a declined payment on backup gateways immediately, within the same checkout, before the customer leaves."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sparkcrm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cascade Profiles

A cascade profile gives one gateway an ordered list of backup gateways to try when a payment declines. The retry happens **immediately**, inside the same checkout request, so a recoverable decline can still convert before the customer gives up.

**Navigation**: Sidebar > Payments > Cascade Profiles

---

## Cascading vs. Salvage vs. Failover

Spark CRM has three separate recovery mechanisms. They solve different problems and can be used together.

| Mechanism | When it runs | What it changes |
|-----------|--------------|-----------------|
| **Cascade profile** | Immediately, during the same checkout | The gateway the charge is attempted on |
| **[Decline salvage](/payment-processing/decline-salvage)** | Later, on a schedule | Re-attempts the charge after a delay |
| **[Orchestrator failover](/payment-processing/orchestrators)** | Immediately, during the same checkout | The gateway, chosen by the orchestrator's own rules |

The practical difference between cascading and salvage is the customer. Cascading tries to save the sale while the customer is still on the page. Salvage tries to save it hours or days later, once they have gone.

Cascading and orchestrator failover both retry immediately, so the **Override orchestrator failover** setting decides which one owns the retry when both could apply.

---

## Creating a Cascade Profile

### Step 1: Navigate to Cascade Profiles

1. Go to **Payments** in the sidebar
2. Click **Cascade Profiles**
3. Click **New Cascade Profile** (on a team with no profiles yet, the empty-state button reads **Create Cascade Profile**)

A flyout titled *Create Cascade Profile* opens; its submit button reads **Create Profile**.

### Step 2: Choose the Main Gateway

**Main gateway** is the gateway the profile watches. When a payment on this gateway declines, the cascade begins.

Each gateway can have **only one cascade profile**, whether that profile is active or not. Deactivating a profile does not free its gateway — the gateway disappears from the **Main gateway** picker until the existing profile is deleted. To change a gateway's cascade behavior, edit its existing profile.

### Step 3: Add Cascade Targets

**Cascade targets** are the backup gateways, tried **in the order listed**. Put your strongest backup first.

A target is skipped if it is not active, belongs to another team, or has already been attempted during this cascade. If no target is left, the cascade stops and the decline stands.

### Step 4: Choose What It Applies To

**Applies to** limits the cascade to specific payment types. At least one must be selected.

| Option | Covers |
|--------|--------|
| **Initials** | The first sale in an order |
| **Rebills** | Subscription renewal charges |
| **Upsells** | Post-purchase upsell charges |

A common setup is initials and upsells only, leaving rebills to decline salvage — a rebill has no customer waiting, so there is nothing to save in the moment.

### Step 5: Configure Behavior

| Setting | Default | Effect |
|---------|---------|--------|
| **Respect sticky MID** | Off | When on, a charge routed by an orchestrator that has **Sticky MID on Reattempt** enabled will **not** cascade. This covers initial sales as well as rebills. Upsells are exempt and still cascade. |
| **Allow cascade on forced gateway** | Off | When on, a transaction that explicitly named a gateway may still cascade to another. |
| **Override orchestrator failover** | Off | When on, this profile takes precedence over the orchestrator's failover routing, and cascading also handles hard failures. |
| **Active** | On | Turn a profile off without deleting it. |

### Step 6: Save

The profile takes effect on the next transaction. Nothing is backfilled.

---

## How a Cascade Runs

When a payment declines on the main gateway:

1. **Check the profile** — is there an active profile for this gateway, and does it apply to this payment type?
2. **Check the decline** — is this decline eligible to cascade? (See below.)
3. **Select the next target** — the first active, not-yet-attempted gateway in profile order.
4. **Retry the charge** — on that gateway, within the same request.
5. **Repeat if needed** — up to a maximum of **three cascade attempts** per transaction.

Every attempt is recorded as its own transaction, so all of them appear in reporting and the order timeline.

### Which Declines Cascade

Not every failure is worth retrying elsewhere:

| Cascades | Failure type |
|----------|--------------|
| No | **Validation errors** — a malformed request or bad card data will fail identically everywhere |
| Depends | **Hard failures** — only when **Override orchestrator failover** is on; otherwise the orchestrator handles them |
| Yes | **Soft declines** — insufficient funds, processor errors, and similar recoverable responses |

Which declines cascade is decided by Spark CRM from the gateway's response text and response code. It is not configurable. [Decline Mappings](/payment-processing/decline-mappings) only rewrite the message (and optional decline code) shown to the customer or returned by the API — they do not affect cascade eligibility.

### What Never Cascades

Cascading is skipped for zero-amount transactions, authorization-only transactions, and test transactions.

---

## Managing Profiles

The list shows each profile's main gateway, its targets, what it applies to, and whether it is active.

- **Edit** — change targets, scope, or behavior at any time.
- **Deactivate** — clear **Active** to stop cascading without losing the configuration.
- **Delete** — removes the profile. The main gateway keeps processing normally; only cascading stops. Deleting is also the only way to free that gateway for a new profile.

Access to cascade profiles requires the `cascade_profile:view_any` permission, or an admin or owner role.

---

## Best Practices

### Order Targets by Strength

Targets are tried in order, not by approval rate. Put the gateway most likely to approve first — the cap of three attempts means a weak first choice can consume the budget.

### Do Not Cascade Onto the Same Processor

If the main gateway and its target share a processor or MID, a decline on one is likely to repeat on the other. Cascade across genuinely independent processing.

### Watch the Statement Descriptor

A cascaded charge settles on the target gateway, so the customer sees **that** gateway's [statement descriptor](/payment-processing/gateways). Keep descriptors consistent across gateways in a cascade to avoid chargebacks from unrecognized charges.

### Start Narrow

Enable initials first and watch the results before extending to rebills and upsells.

---

## Troubleshooting

### Cascade Never Triggers

- Confirm the profile is **Active** and its main gateway is the one that actually processed the charge.
- Check **Applies to** covers the payment type — a rebill will not cascade under an initials-only profile.
- Validation errors never cascade. Check whether the decline was a validation failure rather than a decline.
- If the gateway was forced explicitly, enable **Allow cascade on forced gateway**.
- If the charge was routed by an orchestrator with **Sticky MID on Reattempt** enabled, turn off **Respect sticky MID** on the cascade profile (or turn that setting off on the orchestrator). This applies to initial sales as well as rebills — it is not a per-subscription setting.

### Cascade Stops After One Attempt

All remaining targets were skipped — inactive, on another team, or already attempted. Check each target gateway's status.

### Orchestrator Routes Instead of Cascading

Enable **Override orchestrator failover** so the profile takes precedence.

---

## Related Topics

- [Payment Gateways](/payment-processing/gateways) - Configure the gateways a profile routes between
- [Payment Orchestrators](/payment-processing/orchestrators) - Rule-based routing and failover
- [Decline Salvage](/payment-processing/decline-salvage) - Scheduled retries after the customer has gone
- [Decline Mappings](/payment-processing/decline-mappings) - Rewrite gateway decline messages shown to customers

Source: https://docs.sparkcrm.io/payment-processing/cascade-profiles/index.mdx