Sandbox & Testing
When building your integration, it is crucial to test your application against the various lifecycle stages and edge cases of the Heron API without actually moving real funds.
Heron provides an integrated mock environment via our FAKE provider. This environment predictably simulates varying transfer speeds, network delays, compliance reviews, and outright failures.
Mocking the Provider
The FAKE provider is available in sandbox mode only. When your flow allows explicit provider selection, set providerCode to "FAKE" to force deterministic simulated behavior.
First-Digit Triggers
Our sandbox simulates transfer behaviors based on the first digit of the integer part of the inbound amount used for the simulated leg.
Using the FAKE provider with an amount whose integer part starts with one of the digits below will simulate the corresponding TransferLegStatus:
| First Digit | Triggered Mock Status | Expected Behavior |
|---|---|---|
1.xx | PENDING_SETUP | Fails to progress; remains staged in the local system awaiting manual confirmation. |
2.xx | AWAITING_FUNDS | Pending, simulating network latency or an unfulfilled wire deposit. Blocks on the CUSTOMER. |
3.xx | IN_PROGRESS | Actively processing with simulated time delay. |
4.xx | IN_REVIEW | Transaction gets paused, simulating a compliance AML or KYC flag. Blocks on the PROVIDER. |
5.xx | COMPLETED | Successful, happy-path completion. |
6.xx | FAILED | Hard rejection due to an immediate mock failure on the partner rail. Reason code: fake_simulated_failure. |
7.xx | RETURNED | Transfer clears the rail but is returned by the destination participant. |
8.xx | REFUNDED | Actively refunded and bounced back to the originating user. |
9.xx | CANCELED | Cancelled directly by the simulated provider before execution could begin. |
TIP
Any amount whose first digit falls outside this mapping defaults to a COMPLETED happy-path execution.
Simulating Compliance Reviews
When you simulate an IN_REVIEW status (for example, with an amount whose integer part starts with 4), the transfer leg's blockingParty shifts to "PROVIDER". If you consume customer webhooks, watch the resulting transfer.status_changed and transfer.leg_status_changed events and surface the review state in your own tooling.