Fund an entity's test wallet with sandbox test money

Credits an entity's sandbox test wallet in a given currency, so you can simulate having funds available without a real inflow. This endpoint only exists on sandbox servers — it always fails with a 500 error on the live server. The caller's secret API key carries no entity_id of its own (the sandbox master key is shared across entities), so entity_id is supplied in the request body and ownership is verified explicitly: the authenticated identity must have can_edit_entity (or wildcard) access on the target entity. On first use for a given currency, a dedicated 'Sandbox Test Wallet' account is created for the entity if one does not already exist (identified by the client_reference sandbox-test-wallet-{currency}); on subsequent calls the existing wallet is reused and simply credited again. The credit itself is posted as a ledger transfer from an internal SandboxTestMoneyFaucet account, which must be pre-configured on the enabled currency's system metadata — if it isn't, the request fails with a 500 error rather than partially crediting the wallet. Supplying client_reference makes the funding idempotent per entity: retrying with the same client_reference after a successful funding returns a 409 conflict instead of double-crediting the wallet.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location '/sandbox-test-money-fundings' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "entity_id": "01HQZR2BKPFQ8MXJVT3G7LWNE", "currency": "NGN", "amount": 500000 }'

{ "message": "Sandbox test money funding created successfully", "status": "success", "data": { "id": "01J8Z3K9F8YV7Q6R2N4T6W1XYZ", "entity_id": "01HQZR2BKPFQ8MXJVT3G7LWNE", "account_id": "01HQZR9F3K7Q8MXJVT3G7LABC", "currency": "NGN", "amount": 500000, "status": "successful", "created": 1735689600000 } }

Fund an entity's test wallet with sandbox test money

Request

Responses