Skip to main content

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​

  1. Create the transfer as you do in production: see How transfers work. The transfer starts in awaiting_funds.
  2. Call Simulate funding for a transfer with the id of the transfer, while it is in awaiting_funds. The request needs no body.
  3. 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​

  1. Create the relay. Wait until it has status=active.
  2. 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.
  3. Find the transfer that Nodu creates. Use the v1.transfer.created event, or call List all transfers with the customerId.
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.

PartWhat it sets
accountOwnerThe type and the name of the remitter: individual with firstName and lastName, or business with companyName.
requisitesThe 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​

ScenarioSetupCheck
New self-custody senderUse a new remitter.requisites.wallet for this customer.The transfer requests proof on side=source.
Previously verified senderUse 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 senderDeclare 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​