ALalfredpay
Virtual Accounts

Generate a virtual account

Changed on

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.

Wait on virtual_account.activated. See Webhooks and events.

post/v1/customers/{customerId}/virtual_accounts

Request

  • Base URL
    https://api.sandbox.alfredpay.io
  • URL
    https://api.sandbox.alfredpay.io/v1/customers/{customerId}/virtual_accounts
  • Auth
    • HTTP bearer
    • or API key in header api-key and API key in header api-secret

Headers

Idempotency-Keystring 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.

Request body

purpose'CONVERSION' | 'BALANCE' | 'PAYMENT' 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.

currency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT' required

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

labelstring required

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

Response

Created

idstring
customerIdstring
purpose'CONVERSION' | 'BALANCE' | 'PAYMENT'

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

currency'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT'

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

labelstring
status'active' | 'suspended' | 'migrating' | 'closed'
createdAtstring date-time

Changes