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

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Autopilot

> Route each payment to the provider most likely to approve it and retry declines on the next one, with a machine-learning-powered node in Workflow Studio.

Autopilot is Payrails' machine-learning powered routing engine. For each payment, it estimates which of your providers is most likely to approve it and sends the payment there. If that provider declines, Autopilot moves on to the next most likely one. You set it up once in Workflow Studio, with no routing rules to write or maintain.

In Workflow Studio it's the **Autopilot** card.

## What it does

* **Picks the best provider per payment.** Static [routing rules](https://docs.payrails.com/docs/overview/routing.md) send every payment that matches a rule to the same provider. Autopilot scores every candidate provider for each payment and routes it to the one with the highest chance of approval.
* **Retries declines automatically.** After a decline, Autopilot picks again from the providers this payment hasn't tried. A retry never goes back to the provider that just declined it. You set how many attempts to allow and whether hard declines stop the retries.
* **Keeps payments moving.** Autopilot picks a provider in a fraction of a second.
* **Records every decision.** Each [workflow execution](https://docs.payrails.com/docs/orchestration/workflow-studio/glossary.md#execution) stores the provider chosen, each candidate's estimated approval probability, and how much past data backs it. That record explains why each payment went where it did, with the fields listed in [execution output](#execution-output).
* **Controlled rollout** to send it a share of your traffic. Compare the results with your current routing before you widen the rollout.

## How the model chooses a provider

### A model per merchant

Each merchant has a special model, trained on all past payments. For each payment, it weighs signals about the payment itself, when it happens, and the customer, the merchant, and payment instrument behind it, including how their earlier payments went. These signals let it judge each payment on its own instead of by a fixed rule.

### A score for every candidate

From these signals, the model estimates each candidate provider's chance of approving the payment. Payrails calibrates the scores per provider, so they're comparable probabilities, not only a ranking. The payment goes to the highest-scoring provider.

### Confidence in each score

Alongside each score, Autopilot tracks how many similar past payments back it. The `decision` recorded for every payment reflects that.

### Self improvement over time

Every payment Autopilot routes adds to your history. When Payrails retrains your model, it learns from those outcomes, including the less common payments it explored.

## Before you start

* **Ask Payrails to turn it on.** Your Payrails contact gets a model trained and Autopilot enabled for you. The **Autopilot** card appears in Workflow Studio only after that.
* **Pick at least two providers.** With one candidate there's nothing to choose between. The card accepts one, but then behaves like a fixed route.
* **Use providers the model has history for.** The model can't score a provider it has no history for, so it skips that provider. If it can't score any of your candidates, Autopilot doesn't route the payment and the step fails. Check your candidate list with your Payrails contact.

## Set it up in Workflow Studio

The Autopilot card holds three connected steps: the provider choice, an **Authorize** step that sends the payment to the chosen provider, and a check that retries a decline on the next provider. You configure all of them from the card's settings. The screenshots use example provider accounts; your own accounts appear in their place.

**1. Open a new workflow version**

Go to **Workflows → Payment acceptance** and click **New version**, or duplicate the version you use today. Live payments don't change until you save the version and send traffic to it.

If you start from a blank version, add the **Start Authorize** trigger and turn on the payment methods you want under **Payment options**.

**2. Add the Autopilot card**

Click the next-action button on the step before routing, for example **Start Authorize**. In **What happens next?**, under **Most used**, pick **Autopilot**.

![Workflow Studio What happens next panel with Autopilot under Most used](https://mintcdn.com/payrails-42074109/XwVXp3J7hDxDMDHv/images/docs/orchestration/autopilot/01-add-card.png?fit=max\&auto=format\&n=XwVXp3J7hDxDMDHv\&q=85\&s=d8ae94b730167a3ee9f9996b80b983c0)

The card appears on the canvas with its settings open. Until you choose providers, it shows **No candidate providers selected**.

![New Autopilot card with its settings open and no candidate providers selected](https://mintcdn.com/payrails-42074109/XwVXp3J7hDxDMDHv/images/docs/orchestration/autopilot/02-settings-empty.png?fit=max\&auto=format\&n=XwVXp3J7hDxDMDHv\&q=85\&s=80170349a040ad9197f8486b52fb0fc7)

**3. Choose the candidate providers**

Under **Candidate providers**, select the provider accounts Autopilot may route between. Each payment goes to the candidate the model rates highest for it. Select at least one; until you do, the field shows *Select at least one provider for smart routing.*

**4. Set how declines cascade**

Under **Cascading**, set how Autopilot retries a declined payment on the next candidate, known as the cascade:

* **Max attempts**: the total number of authorization attempts across your candidates before the payment returns as declined. The default is `2`, the first attempt plus one retry, and it can't exceed the number of candidates you selected. Each retry goes to a provider this payment hasn't tried yet.
* **Stop on hard declines**: on by default. When on, only declines on the Retry Recommendation list move on to the next candidate; any other result stops the cascade and returns the decline. When off, every decline moves on until the payment reaches **Max attempts**.

Keep **Stop on hard declines** on unless you have a specific reason not to: a hard decline, such as a stolen card, rarely succeeds on another provider.

![Autopilot settings with the Stop on hard declines tooltip open](https://mintcdn.com/payrails-42074109/XwVXp3J7hDxDMDHv/images/docs/orchestration/autopilot/03-stop-on-hard-declines.png?fit=max\&auto=format\&n=XwVXp3J7hDxDMDHv\&q=85\&s=79d9fed90707c94b60933727a07e9979)

**5. Set the authorization options**

**Capture mode** and **3DS mode** apply to the Authorize step inside the card, with the same choices as a standalone [Authorize](https://docs.payrails.com/docs/orchestration/workflow-studio/actions.md#authorize) step.

![Autopilot settings with three candidate providers, Max attempts set to 2 and Stop on hard declines on](https://mintcdn.com/payrails-42074109/XwVXp3J7hDxDMDHv/images/docs/orchestration/autopilot/04-settings-filled.png?fit=max\&auto=format\&n=XwVXp3J7hDxDMDHv\&q=85\&s=ee74b2184a2ce8da9d59f6241f148b44)

**6. Turn on notifications**

Further down the settings, under **Send webhook notification when:**, tick the events that send a [notification](https://docs.payrails.com/docs/resources/notifications):

* **Result: Success**: one of the candidates authorized the payment.
* **Result: Declined**: the cascade ended without an authorization.
* **Action is paused, waiting for external action**: for example, a 3DS challenge.
* **Action is updated**: the result changed after the step finished, for example when a late provider notification arrives.

![Webhook notification settings with Result: Success and Result: Declined turned on](https://mintcdn.com/payrails-42074109/XwVXp3J7hDxDMDHv/images/docs/orchestration/autopilot/05-notifications.png?fit=max\&auto=format\&n=XwVXp3J7hDxDMDHv\&q=85\&s=986bfa0aa1c92f6221c3e8bd564f6812)

Click **Notification settings** to choose the **Notification type** for each result, for example **Action completed**, and to add **Mappings**, the fields the webhook includes.

![Notification settings with a notification type and mappings for each result](https://mintcdn.com/payrails-42074109/XwVXp3J7hDxDMDHv/images/docs/orchestration/autopilot/06-notification-settings.png?fit=max\&auto=format\&n=XwVXp3J7hDxDMDHv\&q=85\&s=5b66bef480e044d692f9919752a20846)

Click the back arrow, then **Done** to close the settings.

**7. Connect the outputs**

The card now lists your candidates and has two outputs:

* **Success**: one of the candidates authorized the payment.
* **Declined**: every attempt that **Max attempts** allows ended in a decline, or a hard decline stopped the cascade.

A webhook icon on an output means it sends a notification. Connect each output to the steps that follow, as you would for an Authorize step.

![Configured Autopilot card with three candidates and webhook notifications on both outputs](https://mintcdn.com/payrails-42074109/XwVXp3J7hDxDMDHv/images/docs/orchestration/autopilot/07-card-configured.png?fit=max\&auto=format\&n=XwVXp3J7hDxDMDHv\&q=85\&s=0f1293ee059b236d1b9a9d0ba8b36823)

**8. Check, save and roll out**

Click **Check for issues**. Workflow Studio flags problems such as:

* **Max attempts** higher than the number of candidates
* a candidate provider that's disabled or no longer available
* a payment method that none of the candidates can authorize

Then click **Save version** and send traffic to it from the **Payment acceptance** page. To try Autopilot on part of your traffic first, use **Controlled rollout** to split traffic between this version and your current one.

## Fallback

Autopilot never holds a payment waiting for the model. If the model doesn't answer quickly, is unavailable, or isn't set up for you, the step records `"decision": "fallback"` and carries on:

* **First attempt**: the step names no provider configuration, so Authorize picks the provider with your workflow's usual routing rules, exactly as it would without Autopilot.
* **Retry**: the step picks one of the untried candidate provider configurations at random. Your usual routing rules can't tell which providers already declined this payment, so the step doesn't use them here.

The same applies when the model recommends a provider that isn't among your untried candidates.

The fallback covers an unavailable model. The step fails, and tries no provider, when you set up the workflow in a way Autopilot can't use: the payment has no valid amount or payment method, the model can't score any of the candidates, or every candidate has already had an attempt.

## Execution output

The step's output appears on the workflow execution in the [execution monitor](https://docs.payrails.com/docs/orchestration/workflow-studio/monitoring). Use it to trace why a payment went where it did.

| Field | Description |
| - | - |
| `providerConfigId` | The provider configuration chosen for this attempt. Absent on a first-attempt fallback, where your routing rules choose. |
| `routedPsp` | The provider the payment went to. |
| `modelBestPsp` | The provider the model scored highest. On a `fallback`, it can differ from `routedPsp`. |
| `decision` | `exploit`, `explore` or `fallback`, as described in [Confidence in each score](#confidence-in-each-score). |
| `candidates` | Every provider scored, with its estimated approval `probability` and its `support`: how many past payments back it. |
| `recSupport` | How many similar past payments back the chosen provider. |
| `probability` | Is an estimate from the model, not a promise for that payment. |

## Configure it through the API

If you manage workflow versions through the API instead of Workflow Studio, the card is three steps: a `smartRouting` action, an `authorize` action, and a `condition` that loops back to `smartRouting` on a retryable decline. The `smartRouting` step passes its pick to Authorize through the mapping `output.providerConfigId` → `settings.providerConfigId`:

```json theme={null}
{
    "code": "paymentsAutopilot",
    "type": "action",
    "params": {
        "type": "smartRouting",
        "settings": {
            "candidateProviderConfigIds": [
                "02aef2ba-ff06-4b38-b224-70d77b82fc30",
                "d5a64fe0-9251-45ca-95bd-d4e7ce904f1d"
            ]
        },
        "nextActions": {
            "onCompleted": [
                {
                    "type": "addNextStep",
                    "params": {
                        "code": "authorize",
                        "mapping": [
                            { "from": "output.providerConfigId", "to": "settings.providerConfigId" }
                        ]
                    }
                }
            ]
        }
    }
}
```

The retry limit lives in the condition, not in the `smartRouting` settings: loop back only while `authorize.currentAttempt` is below your maximum and the decline is retryable. Workflow Studio writes the `cascade` settings for its own use. Payrails doesn't read them, nor `goal`, `baseConfig` or `strategies`.

| Setting | Required | Description |
| - | - | - |
| `candidateProviderConfigIds` | Yes | The provider configurations Autopilot may route between. At least one. |
| `cascade` | No | `maxAttempts` and `stopOnHardDeclines`, as set in Workflow Studio. Payrails doesn't read them; the condition enforces the limits. |
| `goal` | No | `maximizeAuth`, `minimizeCost` or `balanced`. Not applied during the beta. |
| `baseConfig` | No | Not applied during the beta. Set capture and 3DS options on the Authorize step. |
| `strategies` | No | Payrails-managed toggles. Not applied during the beta. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.