Create a virtual account

post

https://api.cert.zerohash.com/virtual_accounts

Requests a virtual account for a participant. The account is created asynchronously: this endpoint returns 202 Accepted with status: PENDING and no bank_details, and the account becomes ACTIVE once the banking partner issues it. Poll GET /virtual_accounts/{id} for the transition. Idempotency is keyed solely on the required Idempotency-Key header, which also becomes the account id — replaying the same key returns 200 OK with the existing record, while a different key against the same participant creates a second, distinct account. An optional account_label routes every deposit into the account, and any auto-convert-and-withdraw payout, to that labeled account; it is set once at creation.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

participant_code

string

required

The participant the virtual account is issued to. The platform is taken from the authenticated API key and must not be supplied.

settlement_policy

required

Required. There is no default; the platform must choose explicitly. For AUTO_CONVERT_AND_WITHDRAW, provide asset and external_account_id; for HOLD, no additional fields are allowed.

provider_type

string

enum

Banking partner to back the account. Optional; defaults to CRB, the only supported value. Any other value is rejected with 400.

Allowed:

virtual_account_name

string

length ≤ 255

Optional label for the account, used verbatim as the title on the banking partner’s own record. Omit it and the title is derived from the participant’s name as before. Set once at creation: a replay of the same Idempotency-Key returns the originally-stored name and does not update it.

named_account

boolean

Optional; defaults to false. Persisted and echoed back, but drives no behaviour today — reserved for a future named-account feature.

account_label

string

length ≤ 40

Optional. Routes deposits and AUTO_CONVERT_AND_WITHDRAW payouts to a named account instead of general. No leading/trailing special chars; max 40 chars. Invalid value returns 400. Immutable.

Headers

X-SCX-SIGNED

string

required

HMAC-SHA256 signature of the request, base64-encoded. See the Authentication guide for the exact signing formula.

X-SCX-TIMESTAMP

string

required

Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.

Idempotency-Key

uuid

required

A UUID v4 chosen by the caller. Becomes the virtual account id. Omitting it returns 400 MISSING_IDEMPOTENCY_KEY; a non-UUIDv4 value returns 400 INVALID_IDEMPOTENCY_KEY.

Responses

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The Idempotency-Key was already used; the existing record is returned unchanged.

202Accepted. The virtual account was created and is PENDING issuance by the banking partner.

400Bad Request

403Forbidden

404Not Found

409The participant cannot be onboarded to the banking partner, for example because the underlying customer record is in a terminal state.

500Internal Server Error

503Service Unavailable