Sandbox login
Guides
Start typing to search…

Virtual Bank Account

The Virtual Bank Account API enables businesses to request a Virtual bank account(VBA) to send and receive payments. Businesses can wire funds into a VBA, and send payments to their vendors and suppliers. Currently, only USD and CAD virtual bank accounts are supported. Support for other currencies will be added in the future.

Prerequisites

Before creating a virtual bank account, ensure the following conditions are met:

  • Business Ownership Information must be attested
  • Required documents must be submitted and approved:
    • Government-issued Photo ID
    • Business Registration Certificate
    • Proof of Address Veem will perform additional validations before enabling a Virtual Bank Accounts

Authorization

OAuth2 token is required in the Authorization header.

📘

Headers

Three headers are required to use this endpoint.

Required Headers

Name

Type

Required

Description

Authorization

string

Yes

Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: Bearer c047594b-082c-4da1-be89-08fe3770f4b3

See Get Access Token section to generate your Bearer token

X-Request-Id

string

Yes

This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows:
48855846-628d-4177-b071-80332a116f0a

Content-Type

string

Yes

The content type of the request. Must be application/json

Sandbox Endpoints

Veem's Sandbox environment provides a number of endpoints that can be used to configure testing scenarios.

Use the base URL to access the endpoints in sandbox environment.

POST https://sandbox-api.veem.com/veem/

Open Virtual Bank Account (Business)

Opens a new virtual bank account for a business in a specified currency.

POST /v1.2/virtual-bank-account
{
  "currencies" : [
    "USD"
	],
  "virtualBankAccountName" : "Business name",
  "virtualBankAccountBusinessInfo": {
      "geographySendingCountries": "US",
      "geographyReceivingCountries": "US",
      "purposeOfAccount": "Business's VBA USA for providers",
      "monthlyExpectedActivity": 9999999.99,
      "annualRevenue": 9999999.99,
      "businessRegistrationNumber": "123",
      "businessIncorporationDate": "2010-01-01",
      "sourceOfFunds": "It Services"
  }
}
{
  "virtualBankAccountBusinessInfo": {
        "id":66,
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "Business's VBA USA for providers",
        "monthlyExpectedActivity": 9999999.99,
        "annualRevenue": 9999999.99,
        "businessRegistrationNumber": "123",
        "businessIncorporationDate": 1262304000000,
        "businessRegistrationCountry": "US",
        "businessRegistrationAddressLine1": "Evergreen Terrace",
        "businessRegistrationAddressLine2": "Av. 123",
        "businessRegistrationStateProv": "CA",
        "businessRegistrationPostalCode": "94116",
        "businessRegistrationCity": "San francisco",
        "sourceOfFunds": "It Services",
        "businessWebsite": "htttps://mybusiness.com"
    }
}

Request Parameters

Parameter

Mandatory

Format/Values

Size/Type

currencies

Yes

Must be "USD", "CAD", or both in an array format.
"EUR" and "GBP" support is coming soon.
Use ISO 4217 currency codes

3 characters each

virtualBankAccountName

Yes

Name of the virtual bank account. Letters only (no numbers or symbols).

255 characters

virtualBankAccountBusinessInfo

Yes

Business information of the entity opening the virtual bank account

.geographySendingCountries

Yes

Country codes the account holder intends to send to. ISO 3166-1 alpha-2 standard, comma-separated, e.g. "US,CA"

255 characters

.geographyReceivingCountries

Yes

Country codes the account holder intends to receive from. ISO 3166-1 alpha-2 standard, comma-separated, e.g. "US,CA"

255 characters

.purposeOfAccount

Yes

One of the values from the list of supported purpose of account, see Purpose of Account Values (Business), e.g. 'vendor_supplier_payments'

255 characters

.monthlyExpectedActivity

No

Account's expected activity (amount)

BigDecimal

.annualRevenue

No

Annual revenue of the business

BigDecimal

.businessRegistrationNumber

Yes

Registration number of the business

255 characters

.businessIncorporationDate

Yes

Incorporation date of the business

YYYY-MM-DD

.sourceOfFunds

Yes

One of the values from the list of supported source of funds, see Source of Funds Values (Business) , e.g. 'investment_capital'

255 characters

.businessWebsite

No

Valid URL of the business website

255 characters

Purpose of Account Values (Business)

Pass one of the values listed below into the virtualBankAccountBusinessInfo.purposeOfAccount

ValueDescription
vendor_supplier_paymentsVendor / Supplier Payments
payroll_salary_disbursementsPayroll / Salary Disbursements
employee_reimbursementsEmployee Reimbursements
tax_regulatory_paymentsTax or Regulatory Payments
collections_from_customersCollections from Customers (e.g., invoice payments)
refunds_chargebacksRefunds / Chargebacks
escrow_marketplace_settlementsEscrow / Marketplace Settlements
internal_fund_transfersInternal Fund Transfers
holding_pooling_customer_fundsHolding / Pooling of Customer Funds
liquidity_managementLiquidity Management
import_export_settlementsImport / Export Settlements
international_customer_collectionsInternational Customer Collections
overseas_supplier_paymentsOverseas Supplier Payments
otherOther

Source of Funds Values (Business)

Pass one of the values listed below into the virtualBankAccountBusinessInfo.sourceOfFunds

ValueDescription
revenue_from_business_operationsRevenue from Business Operations – Income from selling products or services.
merchant_sales_transactionsMerchant Sales & Transactions – Proceeds from e-commerce, retail, or service-based transactions.
investment_capitalInvestment Capital – Funds received from venture capital, private equity, or angel investors.
loans_credit_linesLoans & Credit Lines – Capital obtained from financial institutions or lenders.
grants_government_subsidiesGrants & Government Subsidies – Funding from government programs or industry grants.
sale_of_business_assetsSale of Business Assets – Proceeds from selling property, equipment, or intellectual property.
shareholder_contributionsShareholder Contributions – Capital infused by business owners or existing shareholders.
franchise_licensing_feesFranchise or Licensing Fees – Revenue from franchise agreements or intellectual property licensing.
subscription_membership_feesSubscription & Membership Fees – Revenue from recurring billing models.

Open Virtual Bank Account (Sole Proprietor)

Opens a new virtual bank account for sole proprietor type of Veem account in a specified currency.

POST /v1.2/virtual-bank-account
{        
    "currencies" : [
      "USD"
    ],
    "virtualBankAccountName" : "Account name",
    "virtualBankAccountIndividualInfo": {
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "Sole proprietor's VBA USA for providers",
        "monthlyExpectedActivity": 9999999.99,
        "annualIncome": 9999999.99,
        "occupation": "Accountant",
        "sourceOfFunds": "It Services",
        "websiteSocialMediaLink": "https://mybusiness.com"
    }
}
{
  "virtualBankAccountIndividualInfo": {
            "id":66,
            "geographySendingCountries": "US",
            "geographyReceivingCountries": "US",
            "purposeOfAccount": "Individual's VBA USA for providers",
            "monthlyExpectedActivity": 9999999.99,
            "annualIncome": 9999999.99,
            "occupation": "Accountant",
            "sourceOfFunds": "It Services",
            "websiteSocialMediaLink": "htttps://mybusiness.com"
    }
}

Request Parameters

Parameter

Mandatory?

Format/Values

Size/Type

currencies

Yes

Must be "USD", "CAD", or both in an array format.
"EUR" and "GBP" support is coming soon.
Use ISO 4217 currency codes

3 characters each

virtualBankAccountName

Yes

Name of the virtual bank account. Letters only (no numbers or symbols).

255 characters

virtualBankAccountIndividualInfo

Yes

Information of the Sole Proprietor opening the virtual bank account

.geographySendingCountries

Yes

Country codes the account holder intends to send to. ISO 3166-1 alpha-2 standard, comma-separated, e.g. "US,CA"

255 characters

.geographyReceivingCountries

Yes

Country codes the account holder intends to receive from. ISO 3166-1 alpha-2 standard, comma-separated, e.g. "US,CA"

255 characters

.purposeOfAccount

Yes

One of the values from the list of supported purpose of account, see Purpose of Account Values (Sole Proprietor) , e.g. 'internal_fund_transfers'

255 characters

.monthlyExpectedActivity

Yes

Account's expected activity (amount)

BigDecimal

.annualIncome

Yes

Annual income of the account holder

BigDecimal

.occupation

Yes

Occupation of the account holder

255 characters

.sourceOfFunds

Yes

One of the values from the list of supported source of funds, see Source of Funds Values (Sole Proprietor) , e.g. 'peer_to_peer_transfers'

255 characters

.websiteSocialMediaLink

No

Link to account holder's social media links(if available)

255 characters

Purpose of Account Values (Sole Proprietor)

Pass one of the values listed below into the virtualBankAccountBusinessInfo.purposeOfAccount

ValueDescription
vendor_supplier_paymentsVendor / Supplier Payments
payroll_salary_disbursementsPayroll / Salary Disbursements
employee_reimbursementsEmployee Reimbursements
tax_regulatory_paymentsTax or Regulatory Payments
collections_from_customersCollections from Customers (e.g., invoice payments)
refunds_chargebacksRefunds / Chargebacks
escrow_marketplace_settlementsEscrow / Marketplace Settlements
internal_fund_transfersInternal Fund Transfers
holding_pooling_customer_fundsHolding / Pooling of Customer Funds
liquidity_managementLiquidity Management
import_export_settlementsImport / Export Settlements
international_customer_collectionsInternational Customer Collections
overseas_supplier_paymentsOverseas Supplier Payments
otherOther

Source of Funds Values (Sole Proprietor)

Pass one of the values listed below into the virtualBankAccountBusinessInfo.sourceOfFunds

ValueLabel
salary_wagesSalary & Wages – Regular employment income.
freelance_consulting_incomeFreelance & Consulting Income – Payments from contract work.
peer_to_peer_transfersPeer-to-Peer Transfers – Money received from family, friends, or others.
investments_crypto_earningsInvestments & Crypto Earnings – Proceeds from stocks, crypto trading, or dividends.
real_estate_sales_rentalsReal Estate Sales or Rentals – Income from property sales or rental payments.
inheritanceInheritance – Funds received from an estate.
gifts_donationsGifts & Donations – Personal gifts or one-time transfers.
royalties_licensingRoyalties & Licensing – Revenue from intellectual property rights (e.g., music, patents, books).
pension_retirement_fundsPension or Retirement Funds – Withdrawals from pension accounts.

Activate a New Currency for Your Virtual Bank Account

Once you’ve opened a USD Virtual Bank Account, you can activate an additional currency using the same API endpoint.

POST /v1.2/virtual-bank-account

Description

To activate a Virtual Bank Account in another currency, send a request to the same endpoint used to open your USD Virtual Bank Account. Include the new currency code in the request body (currency field). You do not need to resend virtualBankAccountBusinessInfo or virtualBankAccountIndividualInfo, as these were already collected from your initial application.

Requirements

  • You must already have an active USD Virtual Bank Account.
  • The only additional supported currency is Canadian Dollars (CAD). EUR and GBP support is coming soon.
{
    "currencies" : ["CAD"]
}
{
    "virtualBankAccountName": "Account Name",
    "virtualBankAccountBusinessInfo": {
        "id": 145,
        "currency": "USD, CAD",
        "virtualBankAccountIds": [
            55182,
            55183
        ],
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "business transactions",
        "monthlyExpectedActivity": 1000.00,
        "annualRevenue": 1000000.00,
        "businessRegistrationNumber": "46-5104750",
        "businessIncorporationDate": "2009-12-31",
        "businessRegistrationCountry": "US",
        "businessRegistrationAddressLine1": "Adress line 1",
        "businessRegistrationAddressLine2": "Addres line 1",
        "businessRegistrationStateProv": "CA",
        "businessRegistrationPostalCode": "94116",
        "businessRegistrationCity": "San Francisco",
        "sourceOfFunds": "business savings"
    },
    "virtualBankAccount": {
        "accountId": 945080,
        "fundingMethodId": 55183,
        "id": "2cedde96-39af-4309-825a-f17db16d42c7",
        "accountName": "Account Name",
        "status": "SUCCESS",
        "currency": "CAD",
        "timeCreated": 1761682261781
    }
}

Common Errors When Opening/Activating an Account

Business Ownership Information Incomplete

{
    "code": 10000010,
    "message": "It was an error on the open vba process, Virtual bank account cannot be opened because: BOI attestation is missing.",
    "logTag": "0df34606-05d1-437a-a3a9-f3352130806f",
    "timestamp": "2025-05-14T01:50:01.220",
    "fileName": "AccountServiceImpl.java",
    "lineNumber": 230
}

Internal Veem validations

{
    "code": 10000004,
    "message": "This account is not Verified, cannot open a virtual bank account",
    "logTag": "eeed5569-4452-47d2-b410-2a9585c8dc3f",
    "timestamp": "2025-05-14T18:14:44.662",
    "fileName": "AccountServiceImpl.java",
    "lineNumber": 216
}
{
    "code": 10000010,
    "message": "Adverse media check is not completed.",
    "logTag": "0df34606-05d1-437a-a3a9-f3352130806f",
    "timestamp": "2025-05-14T01:50:01.220",
    "fileName": "AccountServiceImpl.java",
    "lineNumber": 230
}
{
    "code": 10000010,
    "message": "Cannot open virtual bank account due to the next reasons: Adverse media check is not completed, Photo ID is not uploaded, Liveliness check is not completed, doesnt have a DB strong match, Business registration document type is not completed, Proof of address document is not completed, Drivers license document is not present.",
    "logTag": "0df34606-05d1-437a-a3a9-f3352130806f",
    "timestamp": "2025-05-14T01:50:01.220",
    "fileName": "AccountServiceImpl.java",
    "lineNumber": 230
}
{
    "code": 10000019,
    "message": "Currency GBP is not supported",
    "logTag": "f3348a36-4b2b-4057-a2d6-204e47508371",
    "timestamp": "2025-10-29T17:51:36.764",
    "fileName": "AccountServiceImpl.java",
    "lineNumber": 205
}
{
    "code": 10000015,
    "message": "Currency already exists for this account",
    "logTag": "251530b3-e903-47c7-8911-adee059db2f9",
    "timestamp": "2025-10-29T18:11:52.670",
    "fileName": "AccountServiceImpl.java",
    "lineNumber": 147
}

Update Virtual Bank Account Information

After a Virtual bank account has been created a PATCH request can be sent to make updates to VBA information.

PATCH /v1.2/virtual-bank-account
{
    "virtualBankAccountBusinessInfo": {
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "Business's VBA USA for providers",
        "monthlyExpectedActivity": 9999999.99,
        "annualRevenue": 9999999.99,
        "businessRegistrationNumber": "123",
        "businessIncorporationDate": "2010-01-01",
        "businessRegistrationCountry": "US",
        "businessRegistrationAddressLine1": "Evergreen Terrace",
        "businessRegistrationAddressLine2": "Av. 123",
        "businessRegistrationStateProv": "CA",
        "businessRegistrationPostalCode": "94116",
        "businessRegistrationCity": "San francisco",
        "sourceOfFunds": "It Services",
        "businessWebsite": "htttps://mybusiness.com"
    }
}
{
    "virtualBankAccountBusinessInfo": {
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "Business's VBA USA for providers",
        "monthlyExpectedActivity": 9999999.99,
        "annualRevenue": 9999999.99,
        "businessRegistrationNumber": "123",
        "businessIncorporationDate": "2010-01-01",
        "businessRegistrationCountry": "US",
        "businessRegistrationAddressLine1": "Evergreen Terrace",
        "businessRegistrationAddressLine2": "Av. 123",
        "businessRegistrationStateProv": "CA",
        "businessRegistrationPostalCode": "94116",
        "businessRegistrationCity": "San francisco",
        "sourceOfFunds": "It Services",
        "businessWebsite": "htttps://mybusiness.com"
    }
}
{        
    "virtualBankAccountIndividualInfo": {
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "Business's VBA USA for providers",
        "monthlyExpectedActivity": 9999999.99,
        "annualIncome": 9999999.99,
        "occupation": "Accountant",
        "sourceOfFunds": "It Services",
        "websiteSocialMediaLink": "htttps://mybusiness.com"
    }
}
{        
    "virtualBankAccountIndividualInfo": {
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "Business's VBA USA for providers",
        "monthlyExpectedActivity": 9999999.99,
        "annualIncome": 9999999.99,
        "occupation": "Accountant",
        "sourceOfFunds": "It Services",
        "websiteSocialMediaLink": "htttps://mybusiness.com"
    }
}

Get Virtual Bank Account Summary

Use the following request to get summary information of the virtual account. The summary information provide basic information about the account including time created, status of the account and currency of the account.

Funding method ID returned as part of the response can be used to send payments.

GET /v1.2/virtual-bank-account
{
    "virtualBankAccountName": "Account Name",
    "virtualBankAccountBusinessInfo": {
        "id": 145,
        "currency": "USD",
        "virtualBankAccountIds": [
            55182,
            55183
        ],
        "geographySendingCountries": "US",
        "geographyReceivingCountries": "US",
        "purposeOfAccount": "business transactions",
        "monthlyExpectedActivity": 1000.00,
        "annualRevenue": 1000000.00,
        "businessRegistrationNumber": "46-5104750",
        "businessIncorporationDate": "2009-12-31",
        "businessRegistrationCountry": "US",
        "businessRegistrationAddressLine1": "Adress line 1",
        "businessRegistrationAddressLine2": "Addres line 1",
        "businessRegistrationStateProv": "CA",
        "businessRegistrationPostalCode": "94116",
        "businessRegistrationCity": "San Francisco",
        "sourceOfFunds": "business savings"
    },
    "virtualBankAccounts": [
        {
            "accountId": 945080,
            "fundingMethodId": 55182,
            "id": "632c4775-5730-488e-8543-48ab1c56ee67",
            "status": "SUCCESS",
            "currency": "USD",
            "timeCreated": 1761682203650
        },
        {
            "accountId": 945080,
            "fundingMethodId": 55183,
            "id": "2cedde96-39af-4309-825a-f17db16d42c7",
            "status": "SUCCESS",
            "currency": "CAD",
            "timeCreated": 1761682261781
        }
    ]
}
👍

Partner Notes:

  • A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.
  • onBehalfAccountId is an optional query string parameter, this needs to be included in the request URL in case of partner making an API request on behalf of their customer. This is the customer Veem accountId, e.g ?onBehalfAccountId=457725

Get Virtual Bank Account Balance

Balance endpoint provides the current balance in the account. It is advisable to check balance in the account before sending payments to ensure that payment does not fail due to insufficient funds.

// Example request: GET /v1.2/virtual-bank-account/balance/72f03bec-e95e-408d-9167-78d9899b1049
GET /v1.2/virtual-bank-account/balance/{id}

    {
        "accountId": 943802,
        "fundingMethodId": 55073,
        "id": "72f03bec-e95e-408d-9167-78d9899b1049",
        "balanceAmount": {
            "number": 950.00,
            "currency": "USD"
        },
        "timeUpdated": 1745448383244
    }
👍

Partner Notes:

  • A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.
  • onBehalfAccountId is an optional query string parameter, this needs to be included in the request URL in case of partner making an API request on behalf of their customer. This is the customer Veem accountId, e.g ?onBehalfAccountId=457725

Get Virtual Bank Account Details

Details endpoint provides all details associated with a particular virtual bank account by id.

USD Virtual Bank Account Details

// Example request: GET /v1.2/virtual-bank-account/details/72f03bec-e95e-408d-9167-78d9899b1049
GET /v1.2/virtual-bank-account/details/{id}
{
    "id": "72f03bec-e95e-408d-9167-78d9899b1049",
    "fundingMethodId": 55182,
    "isoCurrencyCode": "USD",
    "isoCountryCode": "US",
    "info": {
        "bankInfo": {
            "funding_accounts": [
                {
                    "account_number": "0337658150",
                    "routing_code_type": "ach_routing_number",
                    "account_holder_name": "Account Name",
                    "bank_address": "5 Penn Plaza, 14th Floor, New York, NY 10001, US",
                    "created_at": 1761682198000,
                    "bank_country": "US",
                    "routing_code": "026073150",
                    "payment_type": "regular",
                    "updated_at": 1761682198000,
                    "bank_name": "Community Federal Savings Bank",
                    "currency": "USD",
                    "account_number_type": "account_number",
                    "id": "7450fce7-b599-4c9c-8bfb-af38d6caa2ea"
                },
                {
                    "account_number": "0337658150",
                    "routing_code_type": "wire_routing_number",
                    "account_holder_name": "Account Name",
                    "bank_address": "5 Penn Plaza, 14th Floor, New York, NY 10001, US",
                    "created_at": 1761682198000,
                    "bank_country": "US",
                    "routing_code": "026073008",
                    "payment_type": "regular",
                    "updated_at": 1761682198000,
                    "bank_name": "Community Federal Savings Bank",
                    "currency": "USD",
                    "account_number_type": "account_number",
                    "id": "9dfc707e-c086-4e94-b373-96b3f1f74a50"
                },
                {
                    "account_number": "GB07TCCL12345698449853",
                    "routing_code_type": "bic_swift",
                    "account_holder_name": "Account Name",
                    "bank_address": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
                    "created_at": 1761682198000,
                    "bank_country": "GB",
                    "routing_code": "TCCLGB3L",
                    "payment_type": "priority",
                    "updated_at": 1761682198000,
                    "bank_name": "The Currency Cloud Limited",
                    "currency": "USD",
                    "account_number_type": "iban",
                    "id": "91de1124-b8a3-40f9-a984-8aff75887fe1"
                }
            ]
        }
    }
}

CAD Virtual Bank Account Details

// Example request: GET /v1.2/virtual-bank-account/details/2cedde96-39af-4309-825a-f17db16d42c7
GET /v1.2/virtual-bank-account/details/{id}
{
    "id": "2cedde96-39af-4309-825a-f17db16d42c7",
    "fundingMethodId": 55183,
    "isoCurrencyCode": "CAD",
    "isoCountryCode": "CA",
    "info": {
        "bankInfo": {
            "funding_accounts": [
                {
                    "account_number": "803612430",
                    "routing_code_type": "routing_code",
                    "account_holder_name": "Account Name",
                    "bank_address": "736 Meridian Road N.E, Calgary, Alberta, CA",
                    "created_at": 1761682198000,
                    "bank_country": "CA",
                    "routing_code": "034512345",
                    "payment_type": "regular",
                    "updated_at": 1761682198000,
                    "bank_name": "Digital Commerce Bank",
                    "currency": "CAD",
                    "account_number_type": "account_number",
                    "id": "94551b6c-73a5-4a97-adc5-38d8f73ef6ba"
                },
                {
                    "account_number": "GB07TCCL12345698449853",
                    "routing_code_type": "bic_swift",
                    "account_holder_name": "Account Name",
                    "bank_address": "12 Steward Street, The Steward Building, London, E1 6FQ, GB",
                    "created_at": 1761682198000,
                    "bank_country": "GB",
                    "routing_code": "TCCLGB3L",
                    "payment_type": "priority",
                    "updated_at": 1761682198000,
                    "bank_name": "The Currency Cloud Limited",
                    "currency": "CAD",
                    "account_number_type": "iban",
                    "id": "91de1124-b8a3-40f9-a984-8aff75887fe1"
                }
            ]
        }
    }
}

Get Virtual Bank Account Transactions

Transactions endpoint provides a list of transactions during the queried time period.

There can be a delay( a few mins) between your transaction completion and your transaction reflecting in the response of the API.

// Example request: GET /v1.2/virtual-bank-account/transactions/1?pageNumber=0&pageSize=25&startDate=2025-05-01&endDate=2025-05-22

GET /v1.2/virtual-bank-account/transactions/{fundingMethodId}
{    
    "content": [
        {
            "id": 318,
            "accountId": 943802,
            "paymentId": 463116,
            "transactionId": 7438211,
            "fundingMethodId": 55073,
            "balanceId": "72f03bec-e95e-408d-9167-78d9899b1049",
            "currency": "USD",
            "amount": 50.50,
            "balanceAmount": 899.50,
            "type": "debit",
            "status": "completed",
            "action": "transfer",
            "settlesAt": 1747104286000,
            "createdAt": 1747104286000,
            "updatedAt": 1747104287000,
            "completedAt": 1747104287000
        }
    ],
    "number": 0,
    "size": 25,
    "totalPages": 1,
    "numberOfElements": 1,
    "totalElements": 1,
    "previousPage": false,
    "nextPage": false,
    "first": true,
    "last": true
}

Query String Parameters

ParameterMandatory?Format/ValuesSize
pageNumberNoPage index to retrieve (0-based). Default is 0.Integer
pageSizeNoNumber of records per page. Default is 25. Maximum is 25.Integer
startDateNoFilter transactions from this date (inclusive). Format: YYYY-MM-DD.10 chars
endDateNoFilter transactions up to this date (inclusive). Format: YYYY-MM-DD.10 chars
onBehalfAccountIdNoCustomer Veem account ID. This needs to be included in the request URL in case of partner making an API request on behalf of their customer.Integer
👍

Partner Notes:

  • A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.
  • onBehalfAccountId is an optional query string parameter, this needs to be included in the request URL in case of partner making an API request on behalf of their customer. This is the customer Veem accountId, e.g ?onBehalfAccountId=457725

Sending Payments

Claimless-payments can be used to send payments from the virtual bank account.

When sending payment, FundingMethod is required. The fundingMethod was returned as part of response when virtual bank account was created. Refer to VBA account section.

fundingMethod can also be retrieved by getting the balance or the details endpoints.

POST /v1.2/claimless-payments
{
    "purposeOfPayment": "Goods",
    "payee":{
        "email": "[email protected]",
        "firstName": "USA First Name",
        "lastName": "USA Last Name",
        "countryCode": "US",
        "phone": "4152306359",
        "phoneCountryCode": "+1",
        "type": "Business",
        "industry": "Software, IT and Telecommunications",
        "subIndustry": "Software",
        "businessName": "USA 123",
        "business": {
            "address": {
                "countryCode": "US",
                "street": "300 Folsom",
                "city": "San Francisco",
                "postalCode": "94105",
                "province": "CA"
            },
            "entity": "Corporation",
            "taxIdNumber": "33-1867308"
        }
    },
    "amount": {
        "number": 50.50,
        "currency": "USD"
    },
    "fundingMethod": {
        "id": 55073,
        "type": "VirtualBank"
    },
    "sweepToWalletId" : 123,
    "notes" : "Payment notes"
}
{
    "requestId": "3c74a767-3416-4d0a-88fe-5869dcfb1239",
    "notes": "Payment notes",
    "payee": {
        "email": "[email protected]",
        "countryCode": "US",
        "phone": "tel:+1-415-230-6359"
    },
    "payeeAmount": {
        "number": 50.50,
        "currency": "USD"
    },
    "status": "Sent",
    "goodFundsPayment": false,
    "realTimePayment": false,
    "sweepToWalletId": 2037,
    "extraInfo": {
        "customInfo": null,
        "isPayeeCoveringCardFee": null
    },
    "id": 463116,
    "exchangeRate": {
        "fromAmount": 50.50,
        "fromCurrency": "USD",
        "toAmount": 50.50,
        "toCurrency": "USD"
    },
    "feeInformation": {
        "payerInfo": {
            "originalAmount": 50.50,
            "feeAmount": 0.00,
            "totalAmount": 50.50,
            "currency": "USD"
        },
        "payeeInfo": {
            "originalAmount": 50.50,
            "feeAmount": 0.00,
            "totalAmount": 50.50,
            "currency": "USD"
        }
    },
    "timeCreated": "2025-05-12T19:43:53.915-07:00",
    "timeUpdated": "2025-05-12T19:43:55.418-07:00",
    "claimLink": "https://api.dev.veem.com/api/c/VLiN8xbV",
    "debitCreditTxn": {
        "debitTxn": null,
        "creditTxn": null,
        "refundTxn": null
    },
    "fastTransfer": false,
    "cancelable": false,
    "payerFundingMethodType": "VirtualBank",
    "receiverFundingMethodType": "Wallet",
    "originalRequestId": "3c74a767-3416-4d0a-88fe-5869dcfb1239"
}

Here is an example of sending a payment from VBA, for more detail of this endpoint refer to Send Money - Claimless.

VBA Webhooks

For creating a webhook to be notified when a VBA event occurs you should use the following endpoint.

POST https://sandbox-api.veem.com/veem/v1.2/webhooks

📘

Headers

Three headers are required to use this endpoint.

Required Headers

Name

Type

Required

Description

Authorization

string

Yes

Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: Bearer c047594b-082c-4da1-be89-08fe3770f4b3

See Get Access Token section to generate your Bearer token

X-Request-Id

string

Yes

This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows:
48855846-628d-4177-b071-80332a116f0a

Content-Type

string

Yes

The content type of the request. Must be application/json

In addition to the webhooks described on the Webhok Notification page, you can subscribe to three VBA-related events:

EventDescription
VBA_ACCOUNT_STATUS_UPDATEDWill notify you when your Virtual Bank Account application changes status.
VBA_TRANSACTIONWill notify you when there is a transaction in or out of your Virtual Bank Account.

VBA Account Status Webhook

  • VBA_ACCOUNT_STATUS_UPDATED

To subscribe to this webhook notification, use the following request:

{
    "callbackURL": "https://webhook-test.com/958892dcc2b3076fffd136adb127ac55",
    "event": "VBA_ACCOUNT_STATUS_UPDATED"
}
{
    "id": 92,
    "event": "VBA_ACCOUNT_STATUS_UPDATED",
    "callbackUrl": "https://webhook-test.com/958892dcc2b3076fffd136adb127ac55",
    "status": "Active"
}

You will get a notification in the following format:

{
  "type": "VBA_ACCOUNT_STATUS_UPDATED",
  "data": "{\"accountId\":944914,\"fundingMethodId\":55146,\"accountReference\":\"9fb7d64s-a67a-4d28-9655-ace57ba95f5a\",\"currency\":\"USD\",\"status\":\"SUCCESS\"}"
}

Event information is contained in the data field, in a stringified JSON format.

Field

Description

accountId

Account ID

fundingMethodId

Funding method ID

accountReference

Unique identifier of the VBA account

currency

VBA's currency

status

One of the Virtual Bank Account statuses:

  • ACCEPTED: The VBA application has been accepted and is now under review
  • SUCCESS: The VBA has successfully been activated
  • REJECTED: The VBA application has been rejected
  • ERROR: An error happened during VBA activation
  • DEACTIVATED: The VBA account has been disabled

VBA Transaction Status Webhook

  • VBA_TRANSACTION

To subscribe to this webhook notification, use the following request:

{
    "callbackURL":"https://webhook-test.com/958892dcc2b3076fffd136adb127ac55",
    "event":"VBA_TRANSACTION"
}
{
    "id": 31,
    "event": "VBA_TRANSACTION",
    "callbackUrl": "https://typedwebhook.tools/webhook/b8d85c63-b0fe-4c31-8c27-ccfeff52da59",
    "status": "Active"
}

You will get a notification in the following format:

{
  "type": "VBA_TRANSACTION",
  "data": "{\"accountId\":\"944208\",\"fundingMethodId\":\"55089\",\"paymentId\":\"468062\",\"counterParty\":{\"name\":\"USA 21111c8e-a3d2-4fdf-ae4e-8d05b5e858a9\",\"accountNumber\":\"1234567\",\"bankCode\":\"122105155\",\"bankName\":\"Access Credit Union\",\"method\":\"bank\"},\"balance\":{\"currency\":\"USD\",\"amount\":461.50},\"transaction\":{\"currency\":\"USD\",\"amount\":50.00,\"status\":\"Complete\",\"direction\":\"debit\",\"transactionDate\":1755743729000,\"reference\":\"\",\"additionalReference\":\"Goods:Products\"}}"
}

Event information is contained in the data field, in a stringified JSON format.

FieldDescription
fundingMethodIdFunding method ID
paymentIdPaymentId for Veem Initiated Payments
accountIdAccount ID
balanceVBA Balance information
balance.currencyVBA currency code
balance.amountVBA balance
counterPartyCounter party information
counterParty.nameCounter party's name
counterParty.accountNumberCounter party's bank account number if available
counterParty.routingCodeCounter party's bank routing code if available
counterParty.bicCounter party's bank bic if available
counterParty.bankCodeCounter party's bank code if available
counterParty.bankNameCounter party's bank name if available
counterParty.addressCounter party's address if available
counterParty.methodCounter party's payment method (bank, wallet, etc)
counterParty.ibanCounter party's iban if available
transactionTransaction information
transaction.currencyTransaction currency
transaction.transactionTransaction amount
transaction.statusTransaction status, possible values: Complete, InProgress, Closed
transaction.directiondebit or credit
transaction.transactionDateTransaction date
transaction.referenceTransaction reference/notes
transaction.additionalReferenceAdditional transaction reference/notes
transaction.railTransaction's rail

updated at (2025-12-02T01:11:23.327Z)

Updated about 17 hours ago