Generate a virtual account

post

https://api.sandbox.alfredpay.io/v1/customers/{customerId}/virtual_accounts

Issues a collection instrument in the customer's own name, with ACH, wire and SWIFT coordinates.

Two things have to be true first: the customer holds the endorsement the chosen purpose needs, and that purpose is among the accountPurposes they declared at onboarding.

purpose is fixed at generation and decides what happens to every deposit that ever lands here. There's no way to change it later.

Idempotency is scoped to (customerId, label). Repeating a label returns the account you already have. Repeating it with a different purpose is a 409.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

customerId

string

required

Body Params

purpose

string

enum

required

On a virtual account it routes every deposit. On the customer profile (plural) it is the declared intent that gates which may be created.

Allowed:

currency

string

enum

required

Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require chain.

label

string

required

length ≤ 64

The instrument's identity. Idempotency scope is (customerId, label).

Headers

Idempotency-Key

uuid

required

Required on every state-changing POST, simulators included; the only exempt POST is …/verifications/preflight.
Replay (same key, same body) returns the original response with Idempotent-Replayed: true; same key with a
different body → 409 idempotency_conflict. Keys are UUIDs, scoped to the API key, retained for 24 hours.

Responses

Language

Credentials

Loading…

Response

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

application/json

201Created

403endorsement_not_enabled: the purpose's endorsement is not APPROVED, or the purpose is not among the customer's declared accountPurposes.

409Label already exists with a different purpose or currency.