Create & Manage Wallets

Wallets are named, fiat-only sub-ledgers that sit alongside (not inside) Cardholder Accounts. They're the right tool for pooling funds at a group level — corporate treasury pools, department budgets, family accounts, or any scenario where funds need to be held centrally and distributed to individual cards. This guide covers creation, funding, and retrieval.

Key characteristics before you start

Step 1: Create a wallet

POST /wallets

Only one field is required:

{ "name": "Acme Corp — EMEA Operations" }

📘

Choose wallet names that are meaningful within your own system — they're visible to your application and useful for reconciliation, but have no effect on the underlying ledger mechanics. Common naming conventions: {Company} — {Department}, {Client Name} — {Program Year}, {Use Case} — {Currency ISO}.

Response:

{
  "status": "success",
  "walletId": 3301
}

Save walletId — it's the key for all subsequent wallet operations including funding and transfers.

Step 2: Fund the wallet via bank transfer

Wallets are funded via the bank-rail deposit endpoint. The flow is the same as for cards, including the optional trace notification:

POST /wallets/{walletId}/bank-deposit

All fields are optional — include as much matching information as available:

Example

{
  "transactionAmount": 500000,
  "transactionReference": "CORP-TRANSFER-20240614",
  "senderAccountName": "Acme Financial LLC",
  "senderAccountNumber": "GB29NWBK60161331926819",
  "senderRoutingNumber": "NWBKGB2L"
}

Response:

{
  "depositId": 8851,
  "statusText": "pending"
}

🚧

Your Program's inbound bank credentials (the account number, routing details, and reference format to which the sender directs the transfer) are available only in Account Management in the production environment — not via the program-level API. Retrieve them from Account Management and communicate them to the sender. See Funding & Deposits.

As with card-level bank deposits, allow 3–5 business days for the transfer to clear through correspondent banking before the wallet balance becomes available. See Fund a Card via Bank Transfer for the full clearing timeline and troubleshooting guidance — the mechanics are identical.

Step 3: Retrieve a wallet

Single wallet

GET /wallets/{walletId}

{
  "walletId": 3301,
  "name": "Acme Corp — EMEA Operations",
  "walletCurrencyId": 0,
  "isActive": true,
  "isDeleted": false,
  "dateCreated": "1718358000",
  "dateLastModified": "1718358000"
}

📘

No balance field on the wallet object. WalletView does not include ledgerBalance or availableBalance. Current wallet balance is surfaced via GET /wallets/transactions — query the transaction history and sum the net movements, or retrieve the balance directly from the wallet transaction totals. A dedicated balance endpoint for wallets is not present in the current spec; raise a support ticket or contact your Axys account team if this is a blocker.

All wallets in the Program

GET /wallets

Returns all wallets in the Program as a flat array — there are no filter parameters or pagination on this endpoint. If your Program has a large number of wallets, implement client-side filtering on the response.

{
  "items": [
    {
      "walletId": 3301,
      "name": "Acme Corp — EMEA Operations",
      "walletCurrencyId": 0,
      "isActive": true,
      "isDeleted": false,
      "dateCreated": "1718358000",
      "dateLastModified": "1718358000"
    }
  ]
}

Corporate use case: wallet as a company funds pool

The canonical pattern for corporate clients combines a Wallet (the company's fund pool) with multiple Cardholder-level Cards (individual employee or director expense cards):

flowchart TD
    BANK["Bank transfer\n(corporate treasury)"]
    WAL["Wallet\n'Acme Corp — Operations'"]
    CARD1["Card — Director A\nJordan Reyes"]
    CARD2["Card — Director B\nAlex Chen"]
    CARD3["Card — Finance Manager\nSam Okafor"]

    BANK -->|"POST /wallets/{id}/bank-deposit"| WAL
    WAL -->|"POST /wallets/transfer\ndestinationType=1 (card)"| CARD1
    WAL -->|"POST /wallets/transfer\ndestinationType=1 (card)"| CARD2
    WAL -->|"POST /wallets/transfer\ndestinationType=1 (card)"| CARD3

Steps:

1. Create a Wallet for the corporate client's operating funds
2. Fund the Wallet via bank transfer (single large inbound transfer per period)
3. For each authorized individual, onboard them as a Cardholder and issue a Card
4. Transfer funds from the Wallet to each Card as needed (POST /wallets/transfer) — see Transfer Funds Between Wallets and Cards
5. Monitor individual Card balances and top up from the Wallet on request or on a schedule

What's next

• Transfer Funds Between Wallets and Cards
• Reconcile Transactions & Fees
• Accounts, Wallets & Deposit Addresses
• Program Architecture: Corporate use cases