---
title: "Create a Bank Account"
method: POST
path: "/v2/bank-account"
---

# Create a Bank Account

`POST /v2/bank-account`

Create a new bank account for a customer. Requires at least one of the customer's verification profiles to be approved.

## Request body

- union
  - object
    - `customerId` string, required — The unique identifier of the customer who owns this bank account.
    - `bankName` string, required — The name of the financial institution where the account is held.
    - `accountName` string, required — A descriptive name for this bank account (e.g., "Checking Account", "Business Account").
    - `currency` 'usd', required — The currency of the bank account. When set to usd, accountDetails must contain either (accountNumber, routingNumber, accountType) for ACH/Wire or (accountNumber, bic) for SWIFT.
    - `accountDetails` unknown, required
    - `accountOwner` object, required — Information about the account owner, including their name, address, and relationship to the customer.
      - `accountHolderName` string, required — The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&'()+,-./:;<=>?@\_`~
      - `address` object, required — The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code).
        - `line1` string, required — The first line of the street address
        - `line2` string — The second line of the street address (apartment, suite, etc.)
        - `city` string, required — The city name
        - `state` string — The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes.
        - `postalCode` string — The postal or ZIP code. Required for countries that use postal codes
        - `country` string, required — The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries).
      - `relationship` 'self' | 'holding_company' | 'subsidiary_company' | 'branch_office' | 'business_partner' | 'supplier' | 'customer' | 'creditor' | 'debtor' | 'franchisee' | 'unknown' — The relationship of the account owner to the customer. Defaults to "self" if not provided.
    - `networks` union, required — The payment networks supported by this bank account. For USD ACH/Wire accounts, must include at least one of "ach" or "wire". For USD SWIFT accounts, must be exactly ["swift"].
      - string[]
      - string[]
  - object
    - `customerId` string, required — The unique identifier of the customer who owns this bank account.
    - `bankName` string, required — The name of the financial institution where the account is held.
    - `accountName` string, required — A descriptive name for this bank account (e.g., "Checking Account", "Business Account").
    - `currency` 'eur', required — The currency of the bank account. When set to eur, accountDetails must contain iban and bic.
    - `accountDetails` object, required — EUR/SEPA account details. Required fields: iban, bic.
      - `iban` string, required — The International Bank Account Number (IBAN) for SEPA transfers. This is required when currency is eur.
      - `bic` string, required — The Bank Identifier Code (BIC), also known as SWIFT code. This is required when currency is eur.
    - `accountOwner` object, required — Information about the account owner, including their name, address, and relationship to the customer.
      - `accountHolderName` string, required — The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&'()+,-./:;<=>?@\_`~
      - `address` object, required — The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code).
        - `line1` string, required — The first line of the street address
        - `line2` string — The second line of the street address (apartment, suite, etc.)
        - `city` string, required — The city name
        - `state` string — The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes.
        - `postalCode` string — The postal or ZIP code. Required for countries that use postal codes
        - `country` string, required — The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries).
      - `relationship` 'self' | 'holding_company' | 'subsidiary_company' | 'branch_office' | 'business_partner' | 'supplier' | 'customer' | 'creditor' | 'debtor' | 'franchisee' | 'unknown' — The relationship of the account owner to the customer. Defaults to "self" if not provided.
    - `networks` string[], required — The payment networks supported by this bank account. For EUR accounts, must be exactly ["sepa"].
  - object
    - `customerId` string, required — The unique identifier of the customer who owns this bank account.
    - `bankName` string, required — The name of the financial institution where the account is held.
    - `accountName` string, required — A descriptive name for this bank account (e.g., "Checking Account", "Business Account").
    - `currency` 'brl', required — The currency of the bank account. When set to brl, accountDetails must contain pixKey and pixKeyType.
    - `accountDetails` object, required — BRL/PIX account details. Required fields: pixKey, pixKeyType.
      - `pixKey` string, required — The PIX key for BRL bank accounts. Required when currency is brl. Format depends on pixKeyType: `email` must be a valid email address; `cpf` must contain exactly 11 digits (non-digits are stripped); `cnpj` must contain exactly 14 digits (non-digits are stripped); `phone` must contain 10-15 digits (non-digits are stripped); `random` accepts any non-empty string up to 512 characters (Banco Central typically issues a UUID, but no UUID format is enforced here).
      - `pixKeyType` 'cpf' | 'cnpj' | 'email' | 'phone' | 'random', required — The PIX key type associated with pixKey. Required when currency is brl. One of: `cpf` (Brazilian individual tax ID), `cnpj` (Brazilian business tax ID), `email`, `phone`, or `random` (UUID-style random key issued by Banco Central).
    - `accountOwner` object, required — The bank account holder details.
      - `accountHolderName` string, required — The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&'()+,-./:;<=>?@\_`~
      - `address` object, required — The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code).
        - `line1` string, required — The first line of the street address
        - `line2` string — The second line of the street address (apartment, suite, etc.)
        - `city` string, required — The city name
        - `state` string — The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes.
        - `postalCode` string — The postal or ZIP code. Required for countries that use postal codes
        - `country` string, required — The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries).
      - `relationship` 'self' | 'holding_company' | 'subsidiary_company' | 'branch_office' | 'business_partner' | 'supplier' | 'customer' | 'creditor' | 'debtor' | 'franchisee' | 'unknown' — The relationship of the account owner to the customer. Defaults to "self" if not provided.
    - `networks` string[], required — The payment networks supported by this bank account. For BRL accounts, must be exactly ["pix"].

## Response `201`

- union
  - object
    - `id` string, required — The unique identifier of the bank account.
    - `status` 'pending' | 'active' | 'inactive' | 'invalid', required — The current status of the bank account.
    - `customerId` string, required — The unique identifier of the customer who owns this bank account.
    - `created` string, required — The ISO 8601 timestamp when the bank account was created.
    - `updated` string, required — The ISO 8601 timestamp when the bank account was last updated.
    - `bankName` string, required — The name of the financial institution where the account is held.
    - `accountName` string, required — A descriptive name for this bank account.
    - `currency` 'usd', required — The currency of the bank account.
    - `accountDetails` union, required — USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic.
      - object
        - `accountNumber` string, required — The bank account number for the US bank account (masked, last 4 characters visible). Present when currency is usd.
        - `routingNumber` string, required — The 9-digit ABA routing number (also known as routing transit number) that identifies the US financial institution. Present when currency is usd.
        - `accountType` 'checking' | 'savings' | 'instapay' | 'pesonet', required — The type of US bank account. Present when currency is usd.
      - object
        - `accountNumber` string, required — The account number for SWIFT transfers (masked, last 4 characters visible). Present when currency is usd and networks is ["swift"].
        - `bic` string, required — The BIC/SWIFT code of the beneficiary bank. Present when currency is usd and networks is ["swift"].
        - `intermediaryBics` string[] — Ordered list of BIC/SWIFT codes for intermediary correspondent banks, if any were set on this account. Omitted from the response when no intermediary BICs are set.
    - `accountOwner` object, required — Information about the account owner, including their name and relationship to the customer.
      - `accountHolderName` string, required — The name of the account holder as it appears on the bank account.
      - `relationship` 'self' | 'holding_company' | 'subsidiary_company' | 'branch_office' | 'business_partner' | 'supplier' | 'customer' | 'creditor' | 'debtor' | 'franchisee' | 'unknown', required — The relationship of the account owner to the customer.
    - `networks` union, required — The payment networks supported by this bank account. For USD ACH/Wire accounts, includes at least one of "ach" or "wire". For USD SWIFT accounts, is exactly ["swift"].
      - string[]
      - string[]
  - object
    - `id` string, required — The unique identifier of the bank account.
    - `status` 'pending' | 'active' | 'inactive' | 'invalid', required — The current status of the bank account.
    - `customerId` string, required — The unique identifier of the customer who owns this bank account.
    - `created` string, required — The ISO 8601 timestamp when the bank account was created.
    - `updated` string, required — The ISO 8601 timestamp when the bank account was last updated.
    - `bankName` string, required — The name of the financial institution where the account is held.
    - `accountName` string, required — A descriptive name for this bank account.
    - `currency` 'eur', required — The currency of the bank account.
    - `accountDetails` object, required — EUR/SEPA account details including iban and bic.
      - `iban` string, required — The International Bank Account Number (IBAN) for SEPA transfers (masked). Country code, check digits, and last 4 characters are unmasked. Present when currency is eur.
      - `bic` string, required — The Bank Identifier Code (BIC), also known as SWIFT code. Present when currency is eur.
    - `accountOwner` object, required — Information about the account owner, including their name and relationship to the customer.
      - `accountHolderName` string, required — The name of the account holder as it appears on the bank account.
      - `relationship` 'self' | 'holding_company' | 'subsidiary_company' | 'branch_office' | 'business_partner' | 'supplier' | 'customer' | 'creditor' | 'debtor' | 'franchisee' | 'unknown', required — The relationship of the account owner to the customer.
    - `networks` string[], required — The payment networks supported by this bank account. For EUR accounts, is exactly ["sepa"].
  - object
    - `id` string, required — The unique identifier of the bank account.
    - `status` 'pending' | 'active' | 'inactive' | 'invalid', required — The current status of the bank account.
    - `customerId` string, required — The unique identifier of the customer who owns this bank account.
    - `created` string, required — The ISO 8601 timestamp when the bank account was created.
    - `updated` string, required — The ISO 8601 timestamp when the bank account was last updated.
    - `bankName` string, required — The name of the financial institution where the account is held.
    - `accountName` string, required — A descriptive name for this bank account.
    - `currency` 'brl', required — The currency of the bank account.
    - `accountDetails` object, required — BRL/PIX account details including pixKey and pixKeyType.
      - `pixKey` string, required — The masked PIX key for Brazilian PIX transfers. Present when currency is brl.
      - `pixKeyType` 'cpf' | 'cnpj' | 'email' | 'phone' | 'random', required — The type of PIX key. Present when currency is brl.
    - `accountOwner` object, required — Information about the account owner, including their name and relationship to the customer.
      - `accountHolderName` string, required — The name of the account holder as it appears on the bank account.
      - `relationship` 'self' | 'holding_company' | 'subsidiary_company' | 'branch_office' | 'business_partner' | 'supplier' | 'customer' | 'creditor' | 'debtor' | 'franchisee' | 'unknown', required — The relationship of the account owner to the customer.
    - `networks` string[], required — The payment networks supported by this bank account. For BRL accounts, is exactly ["pix"].

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `422` — Unprocessable Entity - Validation Error

---

[API](https://skmtc.net/spherepay/apis/docs-spherepay-co.md) · [All operations](https://skmtc.net/spherepay/apis/docs-spherepay-co/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/spherepay/docs-spherepay-co/versions/4f3f5484aed3/schema)