Tools: Scenario Simulators

Scenario simulators

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 that allow you to manually trigger certain cases so you can test how your integration responds. These are available in the Developer section of the dashboard and through the API.

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".

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

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).

API-triggered scenarios

You can trigger simulators via the API. Check out the API documentation for more information.

Name-triggered scenarios

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

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`.

Outbound Payments

Outbound payment states can be simulated by using a specific value in the description field. Refer to the table below for detailed information on how to simulate payments in executed and failed due to different reasons states:

Outbound Payment `description`	Description	What happens on outbound payment creation
`failed_to_execute`	The outbound payment submission attempt to the bank is unsuccessful.	An outbound payment is first marked as `executing` and then transitions to `failed`.
`failed_due_to_bank_rejection`	Although outbound payment submission to the bank is successful, it is then rejected by the recipient's bank.	An outbound payment is first marked as `executing` and then transitions to `failed`.
`failed_due_to_bank_rejection_after_execution`	Exceptional case: the outbound payment is submitted and accepted, but later rejected by the recipient's bank.	An outbound payment is first marked as `executing,` then `executed` and then transitions to `failed`.
Any other description	The outbound payment submission to the bank is successful, and it is accepted by the recipient's bank. The outbound payment is on the way to the recipient!	An outbound payment is first marked as `executing` and then transitions to `executed`.

Payer Name Verification

A No Match Payer Name Verification scenario can be simulated following the Billing Request Flow on Sandbox. At the collect_bank_account_details step if the following details are used, the Account holder name does not match bank account details provided error will appear on the screen.

Account Holder Name

account_holder_name

Sort Code

sort_code

Account Number

account_number

No Match

200000

55779911

Confirmation of Payee (CoP) for Outbound Payments

CoP checks are regulatory requirement for outbound payments. They are performed against recipient bank account records to help reduce misdirected payments. A CoP check can return one of the following results: full_match, partial_match, no_match, unable_to_match. You can simulate these results by creating and providing bank accounts with specific account holder names.

Bank Account `account_holder_name`	`sort_code`	`account_number`	Description
`PARTIAL MATCH`	200000	55779911	The account name is similar but does not match to the details provided. The CoP check returns `partial_match` and `actual_account_name` the bank responds with.
`NO MATCH`	200000	55779911	The provided name does not match the account details. The CoP check returns `no_match`.
`UNABLE TO MATCH`	200000	55779911	The verification could not be performed due to recipient bank issues or technical issues. The CoP check returns `unable_to_match`.
Any other account holder name	200000	55779911	The account name exactly matches the details provided. The CoP check returns `full_match`.

Other tools

GC CLIBuild, test and manage your integration with GC directly from your terminal.

Need help?

Connect as a partner