X5 Sandbox and simulators

Break it on purpose, before it breaks on its own.

A sandbox where everything succeeds tells you nothing you need to know. This one runs the same code as production with deterministic rail simulators, and you can inject the failure you are worried about rather than waiting for it.

Same code as productionDeterministicScenario injection

Scenarios you can inject.

Each is a request away, and each behaves the same way every time, so a test that passes today passes tomorrow for the same reason.

ScenarioWhat it exercises
Rail timeoutThe rail accepts and never confirms.Your integration should see SUBMITTED_UNKNOWN and wait for a query result. If it resends, you have found the bug the simulator exists for.
ReturnA settled payment comes back days later, after you have told the customer it went.
ChargebackAn acquired card payment is disputed and reversed.
Partial settlementThe rail settles less than was instructed.
Duplicate inboundThe same credit arrives twice with the same reference.
Screening hitA control returns REVIEW and a case opens mid-onboarding.
Provider outageA verification provider returns errors rather than verdicts, so you can check that nobody is onboarded on a timeout.

The states a payment can reach.

Every one of these is reachable in the sandbox on demand, including the terminal ones you would rather not meet in production first.

LiveInstruction lifecycleWaiting
RECEIVEDAccepted from the API. Cancellable.5 min
VALIDATEDShape, account and currency check. Cancellable.5 min
APPROVEDControls satisfied, or a case resolved. Cancellable.5 min
RESERVEDFunds held on the wallet. Cancellable.5 min
SUBMITTEDHanded to the rail. No longer cancellable.1 day
SETTLEDThe entries are posted and the transaction is final.terminal

Where else it can go

HELD_REVIEW1 daySUBMITTED_UNKNOWN15 minHELD_BY_PROVIDER1 dayOPERATIONS_CASE1 dayREJECTED_BY_RAILterminalBLOCKEDterminalCANCELLEDterminal

Every non-terminal state carries a deadline and a named consequence. A rail that stops answering becomes SUBMITTED_UNKNOWN, which is queried rather than resent, because the one thing worse than an unknown payment is two of them.

What it guarantees.

Each of these is enforced rather than intended, and each is something you can sit down and try to break on a call. We would rather you did.

  • The sandbox runs the same build as production. It is seeded differently, not written differently, so a behaviour you see here is a behaviour you will get.
  • Simulators are deterministic. The same scenario produces the same sequence every time, which is what makes a test suite worth running.
  • Test data is generated to a seed, so two engineers can describe the same customer to each other by name.
  • Nothing in the sandbox can reach a real rail, a real provider or a real customer.

Ask for sandbox credentials.

You do not need a signed contract to start building against it, and we would rather you found the awkward parts early.