Bank Accounts

Overview

Linking a bank account lets your organization move real money between the traditional banking system and your Wallgent wallets. Linked accounts are used as the source for ACH deposits into a wallet and as the destination for ACH withdrawals from a wallet.

Bank account routes use REST directly — there is no SDK resource for bank accounts in the current SDK version. Use fetch or your HTTP client of choice with your API key in the Authorization header.

Linking a Bank Account

POST /v1/bank-accounts

Request Body

Field	Type	Required	Description
`routingNumber`	`string`	Yes	9-digit ABA routing number
`accountNumber`	`string`	Yes	Account number (4–17 digits)
`accountHolderName`	`string`	Yes	Name on the account (max 256 chars)
`accountType`	`string`	Yes	`CHECKING` or `SAVINGS`
`nickname`	`string`	No	Friendly label (max 256 chars)
`bankName`	`string`	No	Bank name for display (max 256 chars)

const response = await fetch('https://api.wallgent.com/v1/bank-accounts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    routingNumber: '021000021',
    accountNumber: '9876543210',
    accountHolderName: 'Acme Corp',
    accountType: 'CHECKING',
    nickname: 'Chase Operating Account',
    bankName: 'JPMorgan Chase',
  }),
})

const account = await response.json()
console.log('Bank account ID:', account.id)

If the same routing/account number combination already exists for your organization, the server returns the existing record (HTTP 200) rather than creating a duplicate (HTTP 201).

Listing Linked Bank Accounts

GET /v1/bank-accounts

const response = await fetch('https://api.wallgent.com/v1/bank-accounts', {
  headers: { 'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}` },
})

const { data } = await response.json()

for (const account of data) {
  console.log(`${account.nickname ?? account.bankName}: ...${account.accountNumber.slice(-4)} (${account.status})`)
}

Getting a Specific Account

GET /v1/bank-accounts/:id

const response = await fetch(`https://api.wallgent.com/v1/bank-accounts/${bankAccountId}`, {
  headers: { 'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}` },
})

const account = await response.json()

Removing a Bank Account

DELETE /v1/bank-accounts/:id

await fetch(`https://api.wallgent.com/v1/bank-accounts/${bankAccountId}`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}` },
})

Removing a bank account does not affect transactions that have already been processed using that account.

Verification Status

When you link an account, it starts in a PENDING verification state. Wallgent verifies the account details with the banking network before allowing it to be used for transfers. Once verified, the status becomes VERIFIED.

Status	Description
`PENDING`	Account has been submitted; verification in progress
`VERIFIED`	Account is verified and ready for use
`FAILED`	Verification failed; recheck routing and account numbers

Using Linked Bank Accounts with Transfers

Once an account is VERIFIED, reference it by ID when funding a wallet or withdrawing:

// Deposit from bank account into wallet
const response = await fetch(`https://api.wallgent.com/v1/wallets/${walletId}/fund`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: '1000.00',
    bankAccountId: 'acc_01J...',
  }),
})

// Withdraw from wallet to bank account
const withdrawResponse = await fetch(`https://api.wallgent.com/v1/wallets/${walletId}/withdraw`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: '500.00',
    bankAccountId: 'acc_01J...',
  }),
})

API Endpoints

Method	Path	Description
`POST`	`/v1/bank-accounts`	Link a bank account
`GET`	`/v1/bank-accounts`	List linked bank accounts
`GET`	`/v1/bank-accounts/:id`	Get a specific bank account
`DELETE`	`/v1/bank-accounts/:id`	Remove a bank account

Permissions

Permission	Required For
`wallets:write`	Link and remove bank accounts
`wallets:read`	List and view bank accounts

Overview

Linking a Bank Account

Listing Linked Bank Accounts

Getting a Specific Account

Removing a Bank Account

Verification Status

Using Linked Bank Accounts with Transfers

API Endpoints

Permissions

Transfers

Compliance

Webhooks

On this page