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 page 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
- Only available in sandbox environment
Note: The debit simulator currently only supports simulate 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.
Amount | Payment Status | Description |
---|---|---|
13.00 | MissingFunding | Simulates insufficient funds scenario |
17.00 | PendingProcessing | Payment remains in processing state |
19.00 | Rejected | Payment is rejected immediately |
27.00 | Reversed | Payment is reversed after 30 seconds |
53.00 | Cancelled | Payment is cancelled |
177.00 | Returned | Payment is returned with fee deduction |
178.00 | Returned (Agency Banking) | Simulates agency banking return flow |
Any other amount | Processed | Payment completes successfully |
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:
- Your sandbox environment includes multiple company setups
- Transfers between accounts of the same company are marked as
Own
- Transfers between different companies are marked as:
Outgoing
for the senderIncoming
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 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.
Note: The credit simulator currently only supports simulate incoming payments via SEPA Direct Debit and BACS Direct Debit. More schemes will be added over time.
Updated 6 days ago