# Scenario Simulators

Source: https://docs.gocardless.com/docs/developer-resources/scenario-simulators

# Scenario Simulators

When you're building an integration, there are common paths you should make sure your integration handles — for example, a customer cancelling their mandate or a payment failing due to insufficient funds.

In the **sandbox environment**, scenario simulators let you manually trigger these cases to test how your integration responds. They're available through the dashboard and the API.

> **Warning:**
> Do not use real customer email addresses or banking information in the Sandbox environment.
>   Payments will not be processed, but email notifications may still be triggered.

## Dashboard-triggered scenarios

Dashboard-triggered scenarios are started from your [Sandbox Dashboard](https://manage-sandbox.gocardless.com/). Head to the **Developers** tab → **API Settings**, open the **Actions** dropdown, and click **Simulate scenario**.

![Simulate a scenario](/images/docs/developer-resources/scenario-simulators/screenshot_2026-01-09_at_15.04.46.png)

Choose a scenario from the dropdown. You'll see a description of what will happen and anything to be aware of — some simulators are incompatible with certain schemes.

![Simulate a scenario modal](/images/docs/developer-resources/scenario-simulators/screenshot_2022-09-28_at_12.25.32.png)

Enter the ID of the resource to simulate against, then click **Simulate scenario**. If the resource can't be found or isn't compatible with the chosen scenario, you'll see an error.

Dashboard-triggered scenarios support all name-triggered scenarios below, plus extras such as creditor verification status for partners.

## API-triggered scenarios

Trigger simulators via the API. See the [scenario simulators API reference](/docs/api-reference/scenario-simulator#simulate-a-scenario) for details.

## Name-triggered scenarios

> **Info:**
> Where possible, use dashboard or API-triggered scenarios — they are more reliable and support a
>   wider range of cases.

Name-triggered scenarios use special customer `given_name` values. For example, creating a customer named `"Successful"` activates their mandate immediately and pays out payments straight away. All relevant events and webhooks are sent.

| `given_name` | Description                                                                                                       | On mandate creation                    | On payment creation                                     | Schemes                                                              |
| ------------ | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------- |
| `Successful` | Payment collected and paid out successfully.                                                                      | `submitted` → `activated`              | `submitted` → `confirmed` → `paid_out` (payout created) | ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, PAD, SEPA Core |
| `Penniless`  | Payment fails (e.g. insufficient funds).                                                                          | `submitted` → `activated`              | `submitted` → `failed`                                  | ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, PAD, SEPA Core |
| `Fickle`     | Payment collected then charged back.                                                                              | `submitted` → `activated`              | `submitted` → `confirmed` → `paid_out` → `charged_back` | ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, PAD, SEPA Core |
| `Late`       | Payment fails but the bank reports it later than normal.                                                          | `submitted` → `activated`              | `submitted` → `confirmed` → `failed`                    | ACH, Bacs, BECS, BECS NZ, SEPA Core                                  |
| `Invalid`    | Mandate fails because bank details are invalid.                                                                   | `submitted` → `failed`                 | N/A                                                     | ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, PAD            |
| `Expired`    | Mandate expires after the scheme dormancy period (13 months Bacs, 15 months BECS/Betalingsservice, 3 years SEPA). | `submitted` → `activated` → `expired`  | N/A                                                     | ACH, Bacs, BECS, BECS NZ, Betalingsservice, PAD, SEPA Core           |
| `Switching`  | Bacs mandate transferred via the Current Account Switching Service.                                               | `submitted` → `active` → `transferred` | N/A                                                     | Bacs only                                                            |

> **Info:**
> For SEPA mandates, mandate lifecycle events only occur when the first payment is taken.

## Instalment Schedules

Instalment schedule states are simulated using a special customer `given_name` or a special schedule `name`:

| Schedule `name` | Customer `given_name` | Description                                                                    | Result            |
| --------------- | --------------------- | ------------------------------------------------------------------------------ | ----------------- |
| N/A             | `Successful`          | All payments collected successfully.                                           | `completed`       |
| N/A             | `Penniless`           | Payments cannot be collected.                                                  | `errored`         |
| `Faily`         | N/A                   | Fails with: _must be on or after mandate's next_possible_customer_charge_date_ | `creation_failed` |

## Outbound Payments

Simulate outbound payment outcomes by setting a specific `description` value at creation:

| `description`                                  | Description                                                  | Result                              |
| ---------------------------------------------- | ------------------------------------------------------------ | ----------------------------------- |
| `failed_to_execute`                            | Submission to the bank fails.                                | `executing` → `failed`              |
| `failed_due_to_bank_rejection`                 | Submission succeeds but is rejected by the recipient's bank. | `executing` → `failed`              |
| `failed_due_to_bank_rejection_after_execution` | Submitted and accepted, then later rejected.                 | `executing` → `executed` → `failed` |
| Any other value                                | Submission succeeds and is accepted.                         | `executing` → `executed`            |

## Payer Name Verification

To simulate a **No Match** result in the Billing Request Flow, use these details at the `collect_bank_account_details` step:

| `account_holder_name` | `sort_code` | `account_number` |
| --------------------- | ----------- | ---------------- |
| `No Match`            | `200000`    | `55779911`       |

## Confirmation of Payee (CoP) for Outbound Payments

Simulate CoP results by creating bank accounts with specific `account_holder_name` values:

| `account_holder_name` | `sort_code` | `account_number` | Result            |
| --------------------- | ----------- | ---------------- | ----------------- |
| `PARTIAL MATCH`       | `200000`    | `55779911`       | `partial_match`   |
| `NO MATCH`            | `200000`    | `55779911`       | `no_match`        |
| `UNABLE TO MATCH`     | `200000`    | `55779911`       | `unable_to_match` |
| Any other name        | `200000`    | `55779911`       | `full_match`      |

## What's next?

  
#### [Testing Webhooks (Dashboard)](/docs/developer-resources/testing-webhooks-dashboard)

Send test webhooks from the dashboard and inspect request/response details.

  
#### [Testing Webhooks (CLI)](/docs/developer-resources/gc-cli/testing-webhooks-cli)

Use the GoCardless CLI to listen for and forward webhook events locally.