Skip to content

Simulate deposits

TL;DR - Nothing arrives by wire in dev. To fund a customer's balance, inject a deposit on their virtual account with one call - the balance updates exactly as if the bank wire had landed. Injecting on a crypto (on-ramp) account starts the multi-step on-ramp lifecycle instead.

Find the virtual account id

You need the Magma id of the virtual account (not any provider-side id). Two places to get it:

  • Dashboard - the customer detail page shows the customer's virtual account.
  • API - GET /api/v1/organizations/{orgId}/virtual-accounts on the Product API.

The customer must be active - before that, no virtual account exists to deposit on. See Simulate KYC / KYB.

Inject a fiat deposit

curl -X POST \
  "https://dev.magma.builders/api/v1/sandbox/virtual-accounts/{vaId}/deposit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2500, "currency": "USD", "sender_name": "Acme Inc", "payment_rail": "WIRE"}'

Every body field is optional - an empty {} injects a completed $1,000 USD ACH deposit:

Field Default Notes
amount 1000 Number, in the account currency.
currency USD
status COMPLETED Pass PENDING or FAILED to create a deposit that does not credit the balance - only COMPLETED credits.
sender_name Sandbox Sender Shows as the wire's sender on the transaction.
payment_rail ACH E.g. WIRE.

What you'll see

A deposit_fiat transaction appears in the transactions list and the customer's available balance is credited immediately. This is the sandbox equivalent of the customer wiring funds to their account coordinates - the flow described in Top up a customer.

Crypto on-ramp deposits

Injecting a deposit on a crypto virtual account (the one paired with a saved wallet - see On-ramp) behaves differently: the status field is ignored and the deposit enters the multi-step on-ramp lifecycle, received → in_transit → in_destination.

With auto-advance on (the dev default) the steps fire by themselves a few seconds apart. To drive them manually, find the transaction id in the transactions list and advance it:

curl -X POST \
  "https://dev.magma.builders/api/v1/sandbox/transactions/{id}/deposit-advance?to=in_transit" \
  -H "Authorization: Bearer $TOKEN"
to Transaction status you'll see
in_transit processing
in_destination (default) completed

The status vocabulary is the production one - see the Status reference.

Settlement is one-way

Deposits only move forward. There is no way to walk an in_destination deposit back to in_transit, or to un-credit a completed fiat deposit - inject a fresh one instead.

What's next