Aliases

This guide walks through a complete alias integration end to end: from confirming prerequisites, through ordering aliases and tracking provisioning, to receiving funds and managing the alias lifecycle. For the conceptual overview, see .

Prerequisites

Before ordering aliases, make sure:

The target account is a Volt Account held by a Business account holder. Aliases cannot be issued under Named Accounts or under individual holders.

The relevant notification channels are configured in Fuzebox: (to track alias provisioning) and (to reconcile incoming funds).

API authentication

Authentication Method: You must authenticate to obtain an access token before making any API calls.

Endpoint: Authenticate using the standard Volt OAuth endpoint. Include the token as a bearer token on every request, alongside the X-Volt-Api-Version header.

Integration checklist

Order aliases

Endpoint: Place an alias order using the endpoint POST /orders/account-aliases, specifying the accountId and the number of aliases to create (count, 1–1000). Ordering is asynchronous.

Requirement: Always send an Idempotency-Key, and retry with the same key on failure to avoid duplicate orders. Optionally pass a communication field to override the webhook destination for this order.

Expected outcome:

You receive an order id immediately, and the Location header points to the order status resource.
Aliases are provisioned in the background. See for the full request and response.

Track provisioning

Endpoint: Poll the order at GET /orders/account-aliases/{orderId}, or react to the .

Expected outcome:

The order reports its status (PROCESSING → COMPLETED or FAILED), together with requested and completed counts.
When status is COMPLETED, follow _links.aliases to fetch the aliases created by the order.

Fetch the aliases

Endpoint: List the aliases at GET /accounts/{accountId}/aliases?orderId={orderId}, or fetch a single one at GET /account-aliases/{aliasId}.

Expected outcome:

Each alias exposes its identifications — the localized account identifiers your end customers can send funds to — along with its id, currency, name, accountId, orderId, and active flag.
Store the alias id and identifiers for reconciliation.

Receive funds

Endpoint: Funds arriving on an alias are reported through the channel.

Expected outcome:

The funds are credited to the parent Volt Account and you receive a payment notification containing the alias id for reconciliation.

Sandbox testing: In the sandbox, you can test various alias pay-in scenarios:

Receiving a payment on an alias — see .
Refunding a payment received on an alias — see .

Manage the alias lifecycle

Endpoint: PATCH /account-aliases/{aliasId} with { "active": false \| true } to deactivate or reactivate (reversible), or POST /account-aliases/{aliasId}/close to close (permanent and terminal).

Requirement: All management calls require an Idempotency-Key, and your webhook receiver must stay idempotent. Deactivate / reactivate is rejected if the alias is already in that state or closed.

Expected outcome:

The alias state changes accordingly. See for full details.

Aliases

On this page