# Sandbox testing

> Sandbox simulation routes for ARS, EUR, USD, and crypto, with an Argentine peso deposit example.

Source: https://business-api-docs.youhodler.com/guides/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](/api/reference/sandbox),
[sandbox OpenAPI YAML](/openapi-sandbox.yaml), or
[sandbox OpenAPI JSON](/openapi-sandbox.json). The shared
[OpenAPI download](/openapi.yaml) 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](/api/reference/crypto-networks/eligible-crypto-networks-list).
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](/api/reference/legal/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**
```http
POST https://b2b2x-sandbox.youhodler.com/api/funding-endpoints
Authorization: Bearer <access_token>
Idempotency-Key: ars-endpoint-001
Content-Type: application/json
```

```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](/api/reference/funding-endpoints/funding-endpoints-create).
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**
```http
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**
```http
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
```

```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:

```json
{
  "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](/api/reference/deposits/deposits-list) and the account's
[balances](/api/reference/balances/client-accounts-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](/api/reference/auth) for token issuance and
[KYC](/api/reference/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](/api/reference/funding-endpoints) 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.

```bash
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](/api/reference/withdrawal-destinations)
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](/api/reference/withdrawals) through the normal flow,
including any required preview, [action token](/api/reference/action-tokens),
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](/api/reference/webhook-subscriptions), and discover
the current public event catalog through [Events](/api/reference/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.
