When you’re building an integration with the API, there are some common paths you should make sure your integration handles successfully, for example a customer cancelling their mandate or a payment failing due to lack of funds.

In the sandbox environment, we provide scenario simulators which allow you to manually trigger certain cases so you can test how your integration responds. There are two types of scenario simulator: Dashboard-triggered scenarios, and name-triggered scenarios.

Dashboard-triggered scenarios

Dashboard-triggered scenarios are started from your Dashboard. Just head to the "Developers" tab on the left-hand side, and then click "Simulate a scenario".

'Simulate a scenario' button

Choose a simulator from the dropdown (for example "Payment paid out"), and then you'll see more information about that scenario, detailing exactly what will happen and anything you need to know before you can use it (for example, some scenario simulators are not compatible with every scheme).

'Simulate a scenario' modal

Enter the ID of the resource you want to run the simulator on, and then click "Simulate scenario". If there's any problem, for example we can't find the resource or it isn't compatible with the scenario you've chosen, we'll let you know.

You can use Dashboard-triggered scenarios to try all of the cases supported by the name-triggered scenarios below, plus a few extras (for example creditor verification status, useful for partners).

Name-triggered scenarios

Where possible, you should use Dashboard-triggered scenarios, since they are more reliable and support a wider range of cases.

Name-triggered scenarios are scenarios started by using special customer names. For example, if you create a customer with the given_name “Successful”, their mandate will be activated immediately, and their payments will be paid out straight away.

All the relevant events and webhooks will be created and sent for these simulators.

Customer given_name Description What happens on mandate creation What happens on payment creation Schemes supported
Successful The customer’s payment is collected successfully and paid out to you. The mandate is marked as submitted, then activated. The payment is marked as submitted, then confirmed. If you’ve set up a creditor bank account, it is then paid_out and a payout is created. ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, PAD and SEPA Core
Penniless The customer’s payment can’t be collected, for example because they don’t have enough money in their account. The mandate is marked as submitted, then activated. The payment is marked as submitted, then failed. ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, PAD and SEPA Core
Fickle The customer’s payment is collected successfully, but is then charged back by the customer disputing it with their bank. The mandate is marked as submitted, then activated. The payment is marked as submitted, then confirmed. If you’ve set up a creditor bank account, it is then paid_out and a payout is created. Finally, the payment is marked as charged_back. ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, PAD and SEPA Core
Late The customer’s payment can’t be collected, but the bank informs us of the failure later than normal. The mandate is marked as submitted, then activated. The payment is marked as submitted, then confirmed, then failed. ACH, Bacs, BECS, BECS NZ, and SEPA Core
Invalid The customer’s mandate can’t be set up because their bank details are rejected by the banks as invalid. The mandate is marked as submitted, then failed. N/A ACH, Autogiro, Bacs, BECS, BECS NZ, Betalingsservice, and PAD
Expired The customer's Bacs or SEPA mandate has expired because no collection attempts were made against it for longer than the scheme's dormancy period (13 months for Bacs, 15 months for BECS and Betalingsservice, 3 years for SEPA). The mandate is marked as submitted, then activated, then expired. N/A ACH, Bacs, BECS, BECS NZ, Betalingsservice, PAD and SEPA Core
Switching The customer has an existing Bacs mandate which is transferred to another bank account using the UK’s Current Account Switching Service. The mandate is marked as submitted, then active, then transferred. N/A Bacs only
For SEPA mandates, “what happens on mandate creation” will only occur when the first payment is taken.

Instalment schedules

The states of instalment schedules are simulated using either a special customer given_name, or a special name for the instalment schedule. Refer to the table below for more information about how you can simulate completed, errored, and creation_failed states:

Instalment Schedule name Customer given_name Description What happens on instalment schedule creation
N/A Successful All payments belonging to the instalment schedule are successfully collected. The instalment schedule is marked as completed.
N/A Penniless Payments belonging to the instalment schedule cannot be collected. The instalment schedule is marked as errored.
Faily N/A Instalment schedule will fail with payment creation error message:
must be on or after mandate's next_possible_customer_charge_date. 		The instalment schedule is marked as creation_failed.
Test webhooks →