Integration guides

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 Introduction to Aliases.

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.
  • For AUD accounts, allowed payId email domains are configured.
  • The relevant notification channels are configured in Fuzebox: Account ordering (to track alias provisioning) and Payments (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.
  • AUD accounts: Also pass the email PayIDs to register in identifications, one per alias. See PayID aliases.
  • 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 Ordering aliases for the full request and response.

Track provisioning

  • Endpoint: Poll the order at GET /orders/account-aliases/{orderId}, or react to the alias order webhook.
  • 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. For PayID orders, check failedIdentifications for any PayIDs that weren't registered.

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 Payments notifications 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:

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:

How is this guide?

Last updated on

Payments

Previous Page

Linking mechanism

Next Page