Sandbox testing
Simulations let you supply an external review or transfer outcome and then
observe the platform's normal processing. They require a sandbox account,
a bearer token with sandbox_simulator.run, and access to the target resource.
All six simulation routes return 404 in production.
Use the Sandbox API reference, sandbox OpenAPI YAML, or sandbox OpenAPI JSON. The shared OpenAPI download excludes these routes.
Currency and route support
Sandbox support depends on the provider selected by the deployed route binding. New ARS endpoints use BIND; new EUR/USD endpoints use Conduit. Older ARS CVUs issued by mock-fiat continue to use their original simulator.
| Currency / asset | rail_class |
routing.fiat_rail |
Provider / receive route | Incoming transfer | Issuance review | Destination review / payout settlement |
|---|---|---|---|---|---|---|
| ARS (Argentine peso) | fiat |
local_bank_transfer |
BIND / Argentine CVU | Yes | No | No |
| EUR | fiat |
sepa_credit_transfer |
Conduit / virtual account with IBAN | Yes | Yes | Yes |
| USD | fiat |
fedwire |
Conduit / virtual US bank account | Yes | Yes | Yes |
| USD | fiat |
swift |
Conduit / virtual account with SWIFT details | Yes | Yes | Yes |
| Crypto (for example, USDC) | crypto |
Not applicable; use routing.network |
Eligible custody provider / active crypto endpoint | If the provider supports simulation | No | No |
For fiat endpoint creation, send routing.asset and routing.fiat_rail from
the table. For crypto, send routing.asset and routing.network; discover
available pairs through
Eligible crypto networks.
An asset appearing in the catalog does not guarantee every rail or simulation
is available to your account.
Conduit endpoints can remain under review until you call the issuance-review
simulation. The same provider supports destination review and payout settlement;
use the ordinary resource reads to observe each result. BIND and legacy mock-fiat
support incoming transfers only. An unsupported route returns
422 simulation_not_supported_for_route. For a fiat target the platform checks
the target's state before it asks the provider, so a target that is not ready
returns 409 simulation_target_not_ready, even on a route that cannot simulate
that event. A request the simulated provider refuses returns
422 simulation_rejected.
Both BIND and Conduit read the enterprise's company profile from its
verification applicant when they provision an endpoint. An applicant must exist
first: start verification with POST /kyc/access-token. Then
POST /sandbox/enterprises/{enterprise_id}/kyb-review with
{"outcome":"approved"} fills that applicant with synthetic Argentine company
data, including a valid CUIT and a Buenos Aires address, and approves it.
Without an applicant the simulation returns 409 simulation_target_not_ready.
The fill adds only what is missing; every company field the applicant already
holds is kept. If you entered your own company details, they are what the
providers read: a company address outside Argentina fails a BIND endpoint with
party_not_supported, and missing company facts fail it with
party_profile_incomplete.
ARS deposit example
1. Create an ARS funding endpoint
Before provisioning a new ARS CVU, approve your enterprise's KYB as described
above, so BIND can read an Argentine company profile. If the profile is
incomplete or not Argentine, the endpoint becomes failed with
failure.code set to party_profile_incomplete or party_not_supported.
A CVU carries its own legal terms. A human access token must accept them before
the create request: list them with
GET /legal/requirements?trigger=payment_account_cvu and accept the pending
documents through Record legal acceptances.
Until then the create returns 422 not_admissible with data.reason
legal_acceptance_required and the documents to accept. A service-account
token skips this check.
Use an active account belonging to your sandbox enterprise. Replace the account reference below with your own. Each new request needs its own idempotency key.
Create the receive route
POST https://b2b2x-sandbox.youhodler.com/api/funding-endpoints
Authorization: Bearer <access_token>
Idempotency-Key: ars-endpoint-001
Content-Type: application/jsonSee Create funding endpoint.
Save the returned id. Read the endpoint until its status is active and
its fiat_routing.bank_details contains the receive coordinates. The CVU is
published as account_number in those bank details.
Read the endpoint
GET https://b2b2x-sandbox.youhodler.com/api/funding-endpoints/<funding_endpoint_id>?account_ref=client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1&rail_class=fiat
Authorization: Bearer <access_token>2. Simulate an incoming ARS transfer
Use the returned funding endpoint id in the URL and the same account_ref.
The endpoint determines the rail; the simulation body does not take fiat_rail.
Money uses value as a decimal string, paired with currency.
Simulate a 4.5 million peso deposit
POST https://b2b2x-sandbox.youhodler.com/api/sandbox/funding-endpoints/<funding_endpoint_id>/incoming-transfers
Authorization: Bearer <access_token>
Idempotency-Key: ars-deposit-001
Content-Type: application/jsonA successful request returns 202 Accepted with this shape:
Acceptance means processing has started. Observe the resulting deposit through
List deposits and the account's
balances. Reuse the same
idempotency key when retrying the same simulation; use a new key for a new
deposit. BIND accepts positive ARS values with at most two decimal places that remain
exact when represented by its numeric notification format; values that lose
precision, and a currency other than the endpoint's, are rejected with
422 simulation_rejected. It has no fixed 1000000000 cap. That limit belongs
to legacy mock-fiat only; Conduit applies its own provider rules. The ARS
simulator ignores the optional reference, so reconcile using the deposit
resource and provider evidence rather than that field.
For crypto incoming simulations, use the same /incoming-transfers route with
rail_class: "crypto", the crypto endpoint's account and currency, and omit
reference.
From signup to a credited deposit
- Create a sandbox workspace through signup and obtain an API access token.
Follow Authentication for token issuance and
KYC to start the workspace's verification flow with
POST /kyc/access-token; the simulation needs the applicant it creates. - Simulate approval of your own enterprise using
POST /sandbox/enterprises/{enterprise_id}/kyb-reviewwith{"outcome":"approved"}. It fills the applicant's missing company data with synthetic Argentine details and approves it, keeping any details you entered yourself. FollowGET /kyc/flowandGET /kyc/statusuntil verification finishes. A202response means the simulation was accepted; processing continues asynchronously, and another press for the same enterprise returns409 simulation_target_not_readywhile it runs. - If testing a connected account, create the client and its verification
session through the normal APIs. Call
POST /sandbox/clients/{client_id}/kyc-reviewwith{"outcome":"approved"}, then readGET /kyc/clients/{client_id}/status. Complete the client's normal account setup before proceeding. - Create a funding endpoint for the
selected account. If fiat issuance waits for an external review, call
POST /sandbox/funding-endpoints/{funding_endpoint_id}/issuance-reviewwithrail_class,account_ref, andoutcome: "approved". Poll the ordinary funding endpoint read until it is active. Crypto endpoints do not support issuance review. - Send an incoming-transfer simulation as below. Follow
GET /depositsfor the selectedaccount_refand read that account's balances. Normal screening, admission and approval controls still run; a hold must be resolved through its ordinary workflow before funds become available.
Replace the example account reference with the endpoint's owning account.
The endpoint must receive the requested currency. For a crypto deposit use
rail_class: "crypto" and omit reference.
From balance to a settled withdrawal
- Create a withdrawal destination
using the normal API. When fiat destination review is pending, call
POST /sandbox/withdrawal-destinations/{destination_id}/reviewwith{"account_ref":"<owning account reference>","outcome":"approved"}. Poll the ordinary destination read for its resulting state. - Create a withdrawal through the normal flow, including any required preview, action token, fresh authentication and approval. Wait until the fiat payout is dispatched.
- Call
POST /sandbox/withdrawals/{withdrawal_id}/settlementwith{"outcome":"settled"}. ObserveGET /withdrawals/{withdrawal_id}until it settles. To test failure, use{"outcome":"failed","reason":"Sandbox test"}. Crypto settlement and an already-final withdrawal cannot be simulated here.
What to observe
| Simulation | Ordinary resource reads | Public webhook events |
|---|---|---|
| Enterprise KYB review | /kyc/flow, /kyc/status |
kyc.verification.reviewed.v1; read the resource for the resulting stage |
| Client KYC review | /kyc/clients/{client_id}/status |
kyc.verification.reviewed.v1 |
| Fiat funding endpoint issuance | /funding-endpoints/{funding_endpoint_id} |
No dedicated issuance event in the public catalog; poll the endpoint |
| Incoming transfer | /deposits, the account's balances |
rails.deposit.detected.v1, operations.deposit.*.v1; successful credit reaches operations.deposit.settled.v1 |
| Fiat withdrawal destination review | /withdrawal-destinations/{destination_id} |
No dedicated destination-review event in the public catalog; poll the destination |
| Fiat withdrawal settlement | /withdrawals/{withdrawal_id} |
operations.withdrawal.settled.v1 or operations.withdrawal.failed.v1 |
Use the resource's normal query parameters, including account_ref and
rail_class where required. Subscribe through
Webhook Subscriptions, and discover
the current public event catalog through Events.
POST /webhook-subscriptions/{subscription_id}/test checks webhook delivery
without changing financial state.
Retries and unsupported scenarios
Each simulation returns 202 {simulation_id, accepted_at}. Choose a separate
Idempotency-Key for each logical simulation and reuse it when retrying that
same action. The accepted simulation ID is not a deposit or withdrawal ID;
find the resulting operation through its ordinary resource read.
409 simulation_target_not_ready means the target has not reached the point
where that external outcome can be supplied. 422 simulation_not_supported_for_route
means the target route does not support that simulation. 422 simulation_rejected
means the simulated provider refused the request, such as an ARS amount BIND
cannot carry exactly. Resolve the missing setup, correct the request, or choose
a supported route before retrying. There is no guarantee that
every configured fiat route supports every simulation.