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
POST https://b2b2x-sandbox.youhodler.com/api/funding-endpoints
Authorization: Bearer <access_token>
Idempotency-Key: ars-endpoint-001
Content-Type: application/json
{
  "rail_class": "fiat",
  "account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
  "routing": {
    "asset": "ARS",
    "fiat_rail": "local_bank_transfer"
  }
}

See 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
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
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/json
{
  "rail_class": "fiat",
  "account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
  "amount": {
    "value": "4500000.00",
    "currency": "ARS"
  }
}

A successful request returns 202 Accepted with this shape:

{
  "simulation_id": "ddddddd4-dddd-4ddd-8ddd-ddddddddddd4",
  "accepted_at": "2026-10-22T10:00:00.000Z"
}

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

  1. 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.
  2. Simulate approval of your own enterprise using POST /sandbox/enterprises/{enterprise_id}/kyb-review with {"outcome":"approved"}. It fills the applicant's missing company data with synthetic Argentine details and approves it, keeping any details you entered yourself. Follow GET /kyc/flow and GET /kyc/status until verification finishes. A 202 response means the simulation was accepted; processing continues asynchronously, and another press for the same enterprise returns 409 simulation_target_not_ready while it runs.
  3. If testing a connected account, create the client and its verification session through the normal APIs. Call POST /sandbox/clients/{client_id}/kyc-review with {"outcome":"approved"}, then read GET /kyc/clients/{client_id}/status. Complete the client's normal account setup before proceeding.
  4. 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-review with rail_class, account_ref, and outcome: "approved". Poll the ordinary funding endpoint read until it is active. Crypto endpoints do not support issuance review.
  5. Send an incoming-transfer simulation as below. Follow GET /deposits for the selected account_ref and 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.
curl -X POST "https://b2b2x-sandbox.youhodler.com/api/sandbox/funding-endpoints/$FUNDING_ENDPOINT_ID/incoming-transfers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $INCOMING_TRANSFER_KEY" \
  -d '{"rail_class":"fiat","account_ref":"master-accounts/00000000-0000-4000-8000-000000000001","amount":{"value":"100.00","currency":"USD"},"reference":"Sandbox deposit"}'

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

  1. Create a withdrawal destination using the normal API. When fiat destination review is pending, call POST /sandbox/withdrawal-destinations/{destination_id}/review with {"account_ref":"<owning account reference>","outcome":"approved"}. Poll the ordinary destination read for its resulting state.
  2. Create a withdrawal through the normal flow, including any required preview, action token, fresh authentication and approval. Wait until the fiat payout is dispatched.
  3. Call POST /sandbox/withdrawals/{withdrawal_id}/settlement with {"outcome":"settled"}. Observe GET /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.