Skip to main content
POST
Simulate Payin
Sandbox and development only. Production does not register this route: a call there returns 404 RESOURCE_NOT_FOUND in the standard error envelope, and the endpoint is absent from the production OpenAPI document. Credits a balance as though funds had arrived, so you can exercise the receive side of your integration without a bank transfer or an on-chain send. The payin runs through the same lifecycle a real deposit does, lands completed, and raises the same payin.received webhook. No provider is contacted and no funds are swept. The credit is real money in sandbox terms: it lands on the balance and can fund a payout, a transfer or an FX trade. Requires write on the payments scope.

Path Parameters

string
required
The account’s external ID (starts with acct_)

Headers

string
required
Canonical 8-4-4-4-12 UUID, scoped to the account and compared byte-for-byte, as on every idempotent endpoint: A1B2… and a1b2… are different keys. A replay with the same body returns 200 with the original payin; with a different body, 409 IDEMPOTENCY_CONFLICT. See Idempotency.

Request Body

object
required
The balance to credit: {"type": "trading_account"} or {"type": "virtual_account", "virtual_account_id": "va_…"}.A virtual account must belong to this account, be active, and hold currency.
string
required
Currency code. For a trading_account destination it must be enabled for payins on the account; a currency that is not returns 422 CURRENCY_NOT_ENABLED. A virtual_account destination is checked against the virtual account’s own currency instead.
string
required
Greater than 0, at most 18 digits and 6 decimal places, and within the currency’s own precision. See Handling currencies.
string
Name to record as the sender, max 140 characters. Surfaces as sender_name on the payin.
string
Remittance reference to record, 1 to 255 characters. Defaults to Simulated deposit.
Unknown fields are rejected with 422 VALIDATION_ERROR.

Response

201 with the completed Payin on creation, 200 with the original on an idempotent replay. The payin is indistinguishable from a real one. Set sender_name or note if you need to tell simulated credits apart when reconciling a sandbox account.

Errors

Examples

What this unblocks

Sandbox has no way to make a real deposit arrive, so before this endpoint the receive side could only be exercised against real provider activity. With it you can test:
  • A payin.received webhook reaching your handler, signed the same way a production delivery is. See Webhook security.
  • Funding a sandbox account for a payout, transfer or FX test without asking support to top it up.
  • Crediting a named virtual account, including the deposit_destination shape your reconciliation reads.
  • Fiat credits, which have no sandbox equivalent at all: no bank sends money to a sandbox deposit instruction.
It does not simulate a payout completing or failing, a deposit being returned, or a virtual account activating. Those still need real provider activity.