In a payment provider's sandbox, why must a test use the provider's designated inputs?

## Why designated inputs exist at all A sandbox has to let every customer reach outcomes that, in the real system, depend on circumstances nobody can arrange on demand: a travel pass that has lapsed, an inspection device that has fallen offline, a payment instrument the issuer refuses, a risk check that holds a transaction for review. The provider cannot expose a general switch for those, because the environment is shared with everybody else on it, and because such a switch would immediately become a public interface they must support forever. So they do something simpler. They publish a small set of **designated inputs**, and the sandbox branches on the input itself: send the value the provider designates for a lapsed pass, and the sandbox answers as though the pass had lapsed. The behaviour is theirs, the mapping is theirs, and the only part you supply is the value. ## What that changes about how you write a test - **Realistic is not the same as designated.** Data that looks plausible is not a trigger. A well-formed but ordinary value takes the ordinary success path, which is why a test that expects a refusal and asserts a refusal can fail while looking entirely correct. - **The trigger travels in the request, not in configuration.** There is nothing to set up beforehand and nothing to tear down afterwards. The outcome is chosen by what you send, every time you send it. - **The list belongs to the provider.** It can grow, shrink or change meaning without any commit in your repository, so a value hard-coded long ago may quietly stop meaning what it used to mean. - **Some outcomes have no trigger.** If the provider never published a way to reach a state, you cannot reach it. That gap is filled by a stand-in you run yourself, not by cleverness against the sandbox. - **A trigger proves less than it appears to.** It proves your client handles the provider's refusal shape. It does not prove the real system refuses under the circumstances you had in mind when you reached for the trigger. ## Where the values belong in your code - Put them in a named fixture or constant whose name states the **outcome**, not the value: a reader should see "lapsed pass" and never need to know what was actually sent. - Keep them firmly on the test side of the boundary. A designated trigger that finds its way into production configuration is a live defect, waiting for the day somebody points that configuration at the real service. - Do not treat them as secrets — the provider publishes them — but do not treat them as harmless either. They are inputs that force unusual behaviour, and unusual behaviour in production is exactly what you do not want to be able to summon by accident. - Assert on the outcome you expected **and** on the fact that the call took the unusual path. A test that silently passes because a trigger stopped working is worse than a test that fails loudly. ## Why the arrangement is defensible It is easy to read the designated-input arrangement as a limitation, and it is, but it is also a deliberate trade the provider has made on behalf of everyone using the environment. - It keeps the sandbox stateless with respect to your team: nothing you configure can leak into another customer's run, because there is nothing to configure. - It keeps branch selection auditable: the provider can tell from the request alone which path a call took, which makes their own support conversations tractable. - It keeps the surface small: a published list of values is far cheaper to maintain than a configuration interface with its own permissions, lifecycle and support burden. The cost lands on you, and it lands in a predictable place. Your coverage of the provider's unhappy paths is capped at whatever they chose to publish, and the shape of your tests must accommodate values that are meaningless outside their environment. ## The habit to build Treat the designated list as an external dependency with its own change risk. Read the provider's published material rather than copying values out of an older test in the repository. Keep the mapping from outcome to value in a single place, so a change costs a single edit rather than a search across the suite. Review it when the provider announces anything, because the announcement is the only warning you will get. And when you find yourself wanting an outcome the provider has not published a trigger for, stop trying to coax it out of their environment. That is the moment to stand in for the call with a server you operate, where any reply at all — including replies the provider would never send, and failures below the level of a reply — is yours to write, repeat and run in parallel.