Skip to main content
The sandbox runs on its own domain, with its own data. All money on the /v2 sandbox is test money. A /v2 sandbox request cannot move real funds. Sandbox keys and production keys are one group. Both start with jz_live_. The base URL selects test money or real money. Keep the two keys apart, and label each key clearly. The steps to get a sandbox key are the same as on /v1. See Test in the sandbox.
Jenzy operations must enable /v2 for your org in the sandbox, as in production. Until then, each /v2 request gets 404.

Add test funds

A payout draws down a balance, so you must fund the balance first. In the sandbox you simulate the collection yourself. Your sandbox org gets deposit addresses on ethereum and solana when Jenzy enables /v2. A simulation is a stablecoin transfer to your deposit address. It shows the wallet source.
  • Send USDC or USDT. For USD, see Simulate a USD deposit.
  • You can send network. USDC runs on ethereum and solana. USDT runs on ethereum only. For a different network, the request gets 422 with the code unsupported_network.
  • If you do not send network, Hermes uses the default network of your org.
A 202 means that the sandbox accepted the request. id is always null and status is always pending. This is the usual answer. It is not an error. The collection appears in GET /v2/collections in about 3 minutes, through the ordinary collection path. The credit is a real collection in every way that changes your code. It credits your balance, and it sends collection.settled to your endpoint.
This request is not idempotent. Do not send the request again. Read GET /v2/collections instead. A second request makes a second collection.
You can also do this in the sandbox dashboard. Open Multi-asset → Funding coordinates and use Simulate a collection. Select the network in Network.

Simulate a USD deposit

Some sandbox orgs get USD bank details. To find out if your org is one of them, read GET /v2/virtual-accounts?asset=USD. For these orgs, asset: "USD" simulates a bank transfer to your USD bank details.
  • Do not send network, or send ethereum. For a different network, the request gets 422 with the code unsupported_network.
  • The collection credits in USDC, with a bank source. The bank source shows the USD amount that arrived.
  • The credit is the USD amount, less the deposit fees. The fees are the same as in production.
  • If the amount is not more than the fees, the request gets 400 with the code validation_error.
As for a deposit address, id is always null and status is always pending. The collection appears in GET /v2/collections in about 3 minutes. Do not send the request again.
The sandbox deposit addresses start with 0x5a4d on ethereum and with Sandbox on solana. They are not on a real chain. Never send real coins to them. The coins do not arrive, and you cannot get them back.The sandbox USD bank details are not real. The bank name is Sandbox Bank — not a real account, and the SWIFT code is SNDBUS00XXX. Never give these details to a payer.
This endpoint is sandbox only. In production it answers 403 with the code sandbox_only.

Simulate USD beneficiaries and USD payouts

These steps are for orgs with USD bank details.

Beneficiaries

A USD beneficiary that you register is pending. In the sandbox, it becomes active in about 10 seconds. You get beneficiary.active. To test a different result, send outcome to POST /v2/beneficiaries/{id}/simulate:
The answer is the beneficiary, with its new status. A different start status gets 409 with the code conflict.

Payouts

A USD payout gets to succeeded about 60 seconds after its USDC leaves your balance. You get payout.succeeded. To test a failure or a return, send outcome to POST /v2/payouts/{id}/simulate:
The answer is the payout, before the change. The webhook comes after. About 3 minutes later, all the USDC of the payout comes back. It is a collection with a payout_refund source. Each payout can get one outcome only. A second call, or a payout in a different status, gets 409 with the code conflict.
You cannot see when the USDC of a payout leaves your balance. A failed call that is too early gets 409 with the code conflict. Send the call again each 5 seconds. The call usually succeeds in less than 60 seconds. If the payout becomes succeeded first, make a new payout and try again.
A payout to a third-party beneficiary needs an invoice. One invoice is correct for one payout only. For each test payout, upload a new invoice with POST /v2/documents. In the sandbox, each PDF, JPEG, or PNG file is correct. These endpoints are sandbox only. In production they answer 403 with the code sandbox_only.

Child orgs

In the sandbox, the review of a Child org gives a result that you select. The review uses the last name of a person, or the legal_name of a business. The review starts when you owe nothing. It gives its result about 30 seconds later. You get child_org.updated. The value is not case-sensitive, but it must be exact. In the sandbox, each document that you upload is correct, and each terms value is correct. There is no simulate endpoint for a Child org.

What the sandbox can show

Fees in the sandbox follow the same schedule as production.

What the sandbox cannot show

Orgs with USD bank details also have the gaps at the end of the table. For each gap, test in production with a small amount.
A hand-made event is a JSON body that you make yourself. Sign it with your sandbox secret and send it to your own endpoint. Take the shape from Webhooks and the resource pages. It tests your handler. It does not test Hermes.

Orders

The desk fills orders by hand, also in the sandbox. No real bank moves money in the sandbox, so some statuses are not possible there. To move a from-bank order to completed:
  1. Create the order. Wait for order.awaiting_funds.
  2. Upload a funding proof. Any PDF, JPEG, or PNG is correct in the sandbox.
  3. Simulate the stablecoin collection for to_amount in to_asset, with POST /v2/collections/simulate.
  4. Ask Jenzy operations to move your sandbox order.
Jenzy operations move each sandbox order by hand. Jenzy does not promise a time for this. For the other statuses, ask Jenzy operations to move your sandbox order.

Move to production

Your code does not change. Change the base URL and change the key. The asset list of your org in production comes from GET /v2/assets. Then do the steps in Go live.