Simulate funding in the sandbox
The sandbox is Nodu's test environment. In the sandbox, you do not send a payment to fund a transfer or a relay. You simulate the payment with an API call, and Nodu continues as it does after a real payment.
The two operations
Simulate funding for a transfer and Simulate funding for a relay each simulate one incoming payment. Both answer with the status 204 and no body.
Both work only with a sandbox API key: see Environments and API keys. In production, Nodu refuses them with the status 403 and the code forbidden.
Fund a transfer
- Create the transfer as you do in production: see How transfers work. The transfer starts in
awaiting_funds. - Call Simulate funding for a transfer with the
idof the transfer, while it is inawaiting_funds. The request needs no body. - Receive transfer events as notifications of changes. Call Retrieve a transfer to read the transfer's current state.
curl --request POST 'https://api.sandbox.nodu.fi/v1/transfers/<transfer-id>/simulate-funding' \
--header 'Authorization: Bearer <your-api-key>'
The simulated payment has the amount of the transfer and the payment reference of its deposit instructions. Nodu then processes the transfer as it does after a real payment.
In the sandbox, Nodu asks for proof of ownership of the customer's own crypto wallet whatever the amount of the transfer. Such a transfer then waits in info_required: see Simulate crypto wallet verification in the sandbox.
Fund a relay
- Create the relay. Wait until it has
status=active. - Call Simulate funding for a relay with an
amount. The amount is a decimal string greater than zero, in the source currency of the relay. - Find the transfer that Nodu creates. Use the
v1.transfer.createdevent, or call List all transfers with thecustomerId.
curl https://api.sandbox.nodu.fi/v1/relays/<relay-id>/simulate-funding \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Idempotency-Key: <new-uuid>' \
--header 'Content-Type: application/json' \
--data '{"amount": "100.00"}'
Reuse the same key and exact body if this call times out. Use a new key only to simulate another payment. Nodu matches the simulated payment to the relay as it matches a real payment: see When funds arrive.
Choose the remitter
Both operations accept an optional remitter object, which describes the remitter: the party that makes the simulated payment. Without it, Nodu uses a default sandbox remitter.
| Part | What it sets |
|---|---|
accountOwner | The type and the name of the remitter: individual with firstName and lastName, or business with companyName. |
requisites | The account of the remitter, in the fields that the source rail uses. For example, iban for a SEPA payment, or wallet for a blockchain rail. |
Send one part or both. A part that you leave out keeps its default value. For example, this request funds a transfer from a chosen remitter and sending address:
curl https://api.sandbox.nodu.fi/v1/transfers/<transfer-id>/simulate-funding \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"remitter": {
"accountOwner": {"type": "individual", "firstName": "John", "lastName": "Doe"},
"requisites": {"wallet": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f"}
}
}'
For a SEPA payment, send the remitter's bank account instead, for example "requisites": {"iban": "DE89370400440532013000", "bic": "COBADEFFXXX"}.
On a blockchain rail, requisites.wallet is the address that the crypto comes from. Without it, the sandbox generates a new address, for which the customer has not proved ownership. To test a transfer that needs no proof, send an address for which this customer has already provided proof of ownership. To give a real proof with testnet coins, send the address of a crypto wallet that you control.
Check the funding scenarios
| Scenario | Setup | Check |
|---|---|---|
| New self-custody sender | Use a new remitter.requisites.wallet for this customer. | The transfer requests proof on side=source. |
| Previously verified sender | Use an address already verified for this customer. | The transfer continues without asking for that source proof again. Other requirements can still apply. |
| Declared third-party sender | Declare the originator when creating the transfer, then simulate that sender's details. | The transfer retains the declared originator; inspect its state and requirements rather than treating the sender as the customer. |
How the simulation behaves
- The payment matches the transfer. For a transfer, the simulated payment has the amount and the reference of the transfer. For a relay, you choose the amount.
- A transfer funded from a Nodu wallet takes the funds from the balance. To add test funds to a Nodu wallet, simulate the funding of a transfer whose destination is the Nodu wallet: see Fund and pay out from a Nodu wallet.
- Only a simulation funds a sandbox transfer. Coins that you send to a sandbox deposit address do not fund a transfer, and a sandbox payout sends no coins to the destination. Testnet coins work only for the proof of ownership of a crypto wallet: see Simulate crypto wallet verification in the sandbox.
- Each transfer is funded on its own. The payout of one sandbox transfer does not fund another sandbox transfer. Simulate the funding of each transfer.
- No real money. Do not use the deposit instructions of a sandbox transfer or relay to send real money.
When Nodu refuses the simulation
When a simulation is not possible, Nodu refuses the request with a business rule violation. For example, when rule=remitter_not_supported, send the request again without remitter. Errors and rule codes lists these rules, marked "Sandbox only".
If Nodu answers 403 to a request with a sandbox API key, the simulation is not available for this transfer or relay. Contact Nodu.
Next steps
- Simulate crypto wallet verification in the sandbox: resolve a test transfer that waits in
info_required. - Track and cancel a transfer: what each state after the funding means.