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
The amount triggers below apply to transfers, not identity verification. See Identity verification for KYC/KYB testing.
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 | Remains pending setup; does not advance automatically. |
2.xx | AWAITING_FUNDS | Pending, simulating network latency or an unfulfilled wire deposit. Blocks on the CUSTOMER. |
3.xx | IN_PROGRESS | Completes asynchronously after funding instructions are generated. |
4.xx | IN_REVIEW | Remains in review, blocked on the PROVIDER. Status checks do not advance it. |
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.
Automatic 3.xx completion requires an available ACME sandbox webhook connection. If it is not configured or is temporarily unavailable, the transfer remains pending and resumes automatically when the connection is ready. Contact Heron if it remains pending; do not create a replacement transfer just to retry delivery.
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.
Identity verification
ACME (FAKE in the API) auto-approves a valid initial sandbox KYC/KYB submission by default. Repeated status checks preserve that approval. Additional categorized documents can be sent manually by default, without a provider requirement. No real provider receives these files.
Sandbox data reset
Contact Heron to request a sandbox reset. Some organizations cannot be reset because their payment history must be retained. Resetting Heron sandbox data does not reset activity or balances held by an external provider.
Sandbox provider accounts
Custom accounts for sandbox-only providers are available only in sandbox organizations.