Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.Try now
ChargebeechargebeeAPI

Create a virtual bank account using permanent token

Idempotency Supported

Creates a virtual bank account (VBA) for a customer using a permanent token obtained from a payment gateway.

Use this operation when you have already created a payment source at the gateway and obtained a permanent token (reference ID) for it.

Prerequisites & Constraints

  • The customer must not already have an active VBA for the same scheme. For example, if the customer already has a VBA with scheme set to us_automated_bank_transfer, you cannot create another VBA with the same scheme.

Impacts

Virtual bank account

  • A new virtual bank account resource is created and associated with the customer. The virtual bank account includes details such as bank account number, routing number (or IBAN), bank name, and other payment instructions retrieved from the gateway using the provided reference ID.
  • The email address for the VBA is set at the gateway from the customer.email attribute. Later, if the email address is updated for the customer, the email address for the VBA is also updated.

Implementation Notes

  • Check if the customer already has a virtual bank account for the same scheme by calling the List virtual bank accounts API with the customer ID filter. If a virtual bank account exists for the same scheme, the API returns a payment_method_already_exists error.

  • Validate that the required currency for the scheme is enabled. Use the List currencies API to check if the currency is enabled.

Sample Request

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/virtual_bank_accounts/create_using_permanent_token

Input Parameters

customer_id
required, string, max chars=50

The unique identifier of the customer for whom you want to create a virtual bank account.

reference_id
required, string, max chars=150

The identifier (permanent token) used to fetch the payment source details from the gateway. For example, in Stripe it may be only the Stripe Customer ID (for example, cus_63MnDn0t6kfDW7), or a combination of Stripe Customer ID and Stripe Source ID separated by a forward slash (for example, cus_63MnDn0t6kfDW7/src_6WjCF20vT9WN1G).

Constraints

  • If gateway_account_id is provided, the reference_id must belong to the gateway account.
  • If the gateway_account_id is not provided, the reference_id must belong to the gateway account selected based on the gateway routing rules for the payment method type and currency combination.
gateway_account_id
optional, string, max chars=50

Identifier of the payment gateway account to use when creating the virtual bank account.

Default behavior When not provided, Chargebee selects an applicable gateway account for the chosen scheme. Selection follows your site's Smart Routing rules.

scheme
optional, enumerated string, default=ach_credit

The type of automated bank transfer scheme for the virtual bank account.

Prerequisites

  • If billing address validation is enabled for your site, the customer must have a billing address with a country code.
Enum Values
ach_credit

Deprecated

  • This scheme is deprecated. Use us_automated_bank_transfer instead.

ACH Credit Transfer scheme for US-based customers.

sepa_credit

Deprecated

  • This scheme is deprecated. Use eu_automated_bank_transfer instead.

SEPA Credit Transfer scheme for customers in the European Union.

us_automated_bank_transfer

US Automated Bank Transfer scheme for US-based customers.

Prerequisites

US Automated Bank Transfer

gb_automated_bank_transfer

UK Automated Bank Transfer scheme for UK-based customers.

Prerequisites

eu_automated_bank_transfer

EU Automated Bank Transfer scheme for customers in the European Union.

Prerequisites

jp_automated_bank_transfer

Japan Automated Bank Transfer scheme for Japan-based customers.

Prerequisites

mx_automated_bank_transfer

Mexico Automated Bank Transfer scheme for Mexico-based customers.

Prerequisites

Returns

virtual_bank_account
Virtual bank account object
Resource object representing virtual_bank_account
customer
Customer object
Resource object representing customer