Simulating payments

The sandbox payment simulator helps you test your integration thoroughly before going to production. You can simulate complete payment lifecycles, validate different payment statuses, and test error scenarios - all without real money movement.

The simulator supports both outgoing and incoming payment flows, with special features to help you test specific scenarios. This guide explains how to use these features effectively.

Outgoing Payments

Payment Initiation Methods

There are two ways to trigger outgoing payments in the sandbox:

1. Production Payment Endpoints

Use the standard payment initiation endpoints to create payments exactly as you would in production. This approach:

• Tests your complete payment initiation flow
• Validates request payloads match your production requirements
• Simulates the full payment lifecycle from initiation through to completion
• Ensures proper error handling

2. Sandbox-specific Debit Simulator

The sandbox provides a special POST /api/v1/payments/simulations/debits endpoint that bypasses the payment initiation phase. This endpoint:

• Creates a simulated payment that starts directly from the 'processed' status
• Skips the initial payment initiation and validation steps
• Useful for testing downstream payment processing scenarios, such as reporting
• Only available in sandbox environment

Note: The debit simulator currently only supports simulating outgoing payments via SEPA Direct Debit and BACS Direct Debit. More schemes will be added over time.

Simulating Payment Outcomes

You can trigger specific payment statuses by using special amounts in your payment requests. This works with both initiation methods and ensures your request payloads match what you'd use in production.

¹ due to the limited nature of the sandbox, the network chosen for the reroute is hardcoded to T2, regardless of other conditions, such as the clearingNetwork or prioritizedClearingNetworks set, or if T2 is disabled for your account. In production, the logic would follow what is described in Automatic Retry & Rerouting.

Special Payment Scenarios

Reversed Payments

• Simulates payments returned before reaching beneficiary bank
• Could represent scheme rejection or sanctions screening failure
• Reversal occurs 30 seconds after initiation

Returned Payments

• Simulates payments returned by beneficiary bank
• For amount 177.00, returns 147.00 after 30 seconds
• Simulates typical return fee scenarios

Future value dated payments

Payments created with a future value date will not be processed, and remain in PendingProcessing state, due to the limited nature our the sandbox environment.

Incoming Payments

Simulating External Incoming Payments

Since the sandbox is not connected to external payment rails, incoming payments can be simulated in two ways:

Internal Transfers

The primary method to test incoming payments is through internal transfers between your sandbox accounts:

1. Your sandbox environment includes multiple company setups
2. Transfers between accounts of the same company are marked as Own
3. Transfers between different companies are marked as:
   • Outgoing for the sender
   • Incoming for the receiver

To properly simulate an incoming payment, initiate transfers between accounts with different Company Owner.

External Incoming Payments

While you cannot receive incoming payments from external banks directly in the sandbox, the POST /api/v1/payments/simulations/credits endpoint allows you to simulate incoming credits to your accounts. This endpoint is only available in the sandbox environment and can be used alongside internal transfers for testing incoming payment scenarios.

The endpoint supports simulating payments received via the following schemes: SEPA Instant, SEPA Credit Transfer, SEPA Direct Debit, BACS Direct Debit.

Note: The credit endpoint supports FX conversions. To simulate an incoming payment with FX, simply ensure that the creditor account currency is different than the amount currency.

Read more about simulating credits