Accounts and wallets

Every account belongs to one customer. Choose it using two dimensions: who manages it and whether it is a wallet or bank account. Customer-account collection operations are scoped under /v3/customers/{customerId}/accounts; item operations append /{accountId}. There is no reverse lookup from accountId to customerId. Store the customerId alongside every accountId you receive so later requests can address the account.

Choose an account

Account	Use it for
Issued wallet	Hold a custodial stablecoin balance, fund a payout, receive a pay-in, or settle an issued bank account.
Issued bank account	Give the customer reusable bank details that settle into an issued wallet.
External wallet	Record a blockchain address owned by the customer.
External bank account	Record a bank account owned by the customer for a first-party payout.

issued means Swipelux creates and manages the resource. external records an endpoint owned by the customer. A third-party endpoint belongs under a recipient and destination, not under the customer account list. Before you start the merchant panel’s First pay-in walkthrough for card or Apple Pay, create a Polygon wallet under that customer. The walkthrough offers only that Polygon wallet and cannot continue without it. This prerequisite applies to the merchant panel walkthrough; direct API integrations must use only the currencies, networks, methods, and account types returned for the current customer and capability.

Create the account

Use POST /v3/customers/{customerId}/accounts. Send these headers with one of the request bodies below:

X-API-Key: ${SWIPELUX_API_KEY}
Idempotency-Key: account-create-001
Content-Type: application/json

Issued wallet
Issued bank account
External wallet
External bank account

{
  "origin": "issued",
  "type": "wallet",
  "currency": "USDC",
  "network": "base",
  "label": "Settlement wallet"
}

{
  "origin": "issued",
  "type": "bank",
  "method": "ach",
  "country": "US",
  "currency": "USD",
  "settlement": {
    "accountId": "${SETTLEMENT_WALLET_ID}"
  },
  "label": "USD account"
}

{
  "origin": "external",
  "type": "wallet",
  "currency": "USDC",
  "network": "polygon",
  "details": {
    "address": "0x4997b0a68bebc1b0d80a93567ba7002be92b8b11"
  },
  "label": "Customer Polygon wallet"
}

{
  "origin": "external",
  "type": "bank",
  "methods": ["ach", "wire"],
  "country": "US",
  "currency": "USD",
  "details": {
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "accountType": "checking",
    "bankName": "Example Bank",
    "accountHolderName": "Acme Payments SAS"
  },
  "label": "Customer operating account"
}

Use only currencies, networks, methods, and account types returned for the current customer and capability. Do not copy availability from another customer or environment.

Wait for the account to be usable

Store data.id, data.status, and data.openTaskIds from the create response. Read the latest account with GET /v3/customers/{customerId}/accounts/{accountId} before you quote a transfer or show bank details. Use the account only when its current status permits the next operation. If task IDs are open, complete them through Capabilities and tasks. An issued bank account can return details: null while provisioning. Present bank details only after a current read returns the complete set. If details.referenceRequired is true, show the exact details.reference with the bank coordinates.

Keep account roles explicit

For a payout, the issued wallet is the source in in.accountId. A customer-owned bank account is the destinationId. For an issued bank account, settlement.accountId is the issued wallet that receives matched deposits. Next, use a ready account in Receive funds, Send funds, or Issue a bank account.

Get started

Onboard customers

Build money flows

Launch

Accounts and wallets

Choose an account

Create the account

Wait for the account to be usable

Keep account roles explicit

​Choose an account

​Create the account

​Wait for the account to be usable

​Keep account roles explicit

Choose an account

Create the account

Wait for the account to be usable

Keep account roles explicit