> ## Documentation Index > Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt > Use this file to discover all available pages before exploring further. # Register a Customer Bank Account for Transfers > Create a new bank account for a customer. Requires at least one of the customer's verification profiles to be approved. Use this endpoint to register a customer's existing fiat bank account with SpherePay. SpherePay does not open or manage bank accounts — it links an account your customer already holds to their SpherePay profile so it can be used as the source or destination for fiat transfers. You must register at least one bank account before creating a transfer that involves fiat currency. The customer must have at least one approved verification profile before you can register a bank account on their behalf. ## OpenAPI ````yaml openapi/spherepay.yaml POST /v2/bank-account openapi: 3.0.0 info: title: '' description: '' version: 1.0.0 contact: {} servers: - url: https://api.spherepay.co description: Production security: - bearer: [] tags: [] paths: /v2/bank-account: post: summary: Create a Bank Account description: >- Create a new bank account for a customer. Requires at least one of the customer's verification profiles to be approved. parameters: [] requestBody: required: true content: application/json: schema: oneOf: - type: object properties: customerId: description: >- The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string minLength: 1 bankName: description: >- The name of the financial institution where the account is held. example: Bank of America type: string minLength: 1 accountName: description: >- A descriptive name for this bank account (e.g., "Checking Account", "Business Account"). example: Checking Account type: string minLength: 1 currency: description: >- 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. example: usd type: string enum: - usd accountDetails: description: >- USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber, bic. accountOwner: description: >- Information about the account owner, including their name, address, and relationship to the customer. type: object properties: accountHolderName: description: >- The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&'()+,-./:;<=>?@\_`~ example: Sarah Johnson type: string minLength: 1 maxLength: 35 pattern: ^[ \w!"#$%&'()+,\-./:;<=>?@\\_`~]*$ address: description: >- The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code). type: object properties: line1: description: The first line of the street address example: 233 South Wacker Drive type: string minLength: 4 maxLength: 35 line2: description: >- The second line of the street address (apartment, suite, etc.) example: Suite 4700 type: string maxLength: 35 city: description: The city name example: Chicago type: string minLength: 1 maxLength: 35 state: description: >- The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: IL type: string postalCode: description: >- The postal or ZIP code. Required for countries that use postal codes example: '60606' type: string country: description: >- The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: USA type: string required: - line1 - city - country relationship: description: >- The relationship of the account owner to the customer. Defaults to "self" if not provided. example: self type: string enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown default: self required: - accountHolderName - address networks: description: >- 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"]. example: - wire - ach oneOf: - type: array minItems: 1 items: type: string enum: - ach - wire - type: array items: oneOf: - type: string enum: - swift required: - customerId - bankName - accountName - currency - accountDetails - accountOwner - networks - title: EUR type: object properties: customerId: description: >- The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string minLength: 1 bankName: description: >- The name of the financial institution where the account is held. example: Deutsche Bank type: string minLength: 1 accountName: description: >- A descriptive name for this bank account (e.g., "Checking Account", "Business Account"). example: Hauptkonto type: string minLength: 1 currency: description: >- The currency of the bank account. When set to eur, accountDetails must contain iban and bic. example: eur type: string enum: - eur accountDetails: description: 'EUR/SEPA account details. Required fields: iban, bic.' type: object properties: iban: description: >- The International Bank Account Number (IBAN) for SEPA transfers. This is required when currency is eur. example: FR1420041010050500013M02606 type: string bic: description: >- The Bank Identifier Code (BIC), also known as SWIFT code. This is required when currency is eur. example: BNPAFRPPXXX type: string required: - iban - bic accountOwner: description: >- Information about the account owner, including their name, address, and relationship to the customer. type: object properties: accountHolderName: description: >- The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&'()+,-./:;<=>?@\_`~ example: Lukas Müller type: string minLength: 1 maxLength: 35 pattern: ^[ \w!"#$%&'()+,\-./:;<=>?@\\_`~]*$ address: description: >- The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code). type: object properties: line1: description: The first line of the street address example: Unter den Linden 77 type: string minLength: 4 maxLength: 35 line2: description: >- The second line of the street address (apartment, suite, etc.) example: Suite 4700 type: string maxLength: 35 city: description: The city name example: Berlin type: string minLength: 1 maxLength: 35 state: description: >- The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: BE type: string postalCode: description: >- The postal or ZIP code. Required for countries that use postal codes example: '10117' type: string country: description: >- The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: DEU type: string required: - line1 - city - country relationship: description: >- The relationship of the account owner to the customer. Defaults to "self" if not provided. example: self type: string enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown default: self required: - accountHolderName - address networks: description: >- The payment networks supported by this bank account. For EUR accounts, must be exactly ["sepa"]. example: - sepa type: array items: type: string enum: - sepa required: - customerId - bankName - accountName - currency - accountDetails - accountOwner - networks - title: BRL type: object properties: customerId: description: >- The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string minLength: 1 bankName: description: >- The name of the financial institution where the account is held. example: Itaú type: string minLength: 1 accountName: description: >- A descriptive name for this bank account (e.g., "Checking Account", "Business Account"). example: Conta PIX Alice Santos type: string minLength: 1 currency: description: >- The currency of the bank account. When set to brl, accountDetails must contain pixKey and pixKeyType. example: brl type: string enum: - brl accountDetails: description: >- BRL/PIX account details. Required fields: pixKey, pixKeyType. type: object properties: pixKey: description: >- 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). example: alice@spherepay.co type: string pixKeyType: description: >- 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). example: email type: string enum: - cpf - cnpj - email - phone - random required: - pixKey - pixKeyType accountOwner: description: The bank account holder details. title: Account Owner (Basic) type: object properties: accountHolderName: description: >- The name of the account holder as it appears on the bank account. Only alphanumeric characters, spaces, and the following special characters are allowed: !"#$%&'()+,-./:;<=>?@\_`~ example: Alice Santos type: string minLength: 1 maxLength: 35 pattern: ^[ \w!"#$%&'()+,\-./:;<=>?@\\_`~]*$ address: description: >- The address of the account owner. Must be a valid address format (ISO3166-1 Alpha-3 country code). type: object properties: line1: description: The first line of the street address example: Rua Augusta 100 type: string minLength: 4 maxLength: 35 line2: description: >- The second line of the street address (apartment, suite, etc.) example: Suite 4700 type: string maxLength: 35 city: description: The city name example: São Paulo type: string minLength: 1 maxLength: 35 state: description: >- The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces. See State Codes. example: SP type: string postalCode: description: >- The postal or ZIP code. Required for countries that use postal codes example: 01304-001 type: string country: description: >- The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN). See [Country Codes](/concepts/reference/supported-countries). example: BRA type: string required: - line1 - city - country relationship: description: >- The relationship of the account owner to the customer. Defaults to "self" if not provided. example: self type: string enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown default: self required: - accountHolderName - address networks: description: >- The payment networks supported by this bank account. For BRL accounts, must be exactly ["pix"]. example: - pix type: array items: type: string enum: - pix required: - customerId - bankName - accountName - currency - accountDetails - accountOwner - networks responses: '201': description: '' content: application/json: schema: oneOf: - title: USD type: object properties: id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string status: description: The current status of the bank account. example: active type: string enum: - pending - active - inactive - invalid x-enumNames: - Pending - Active - Inactive - Invalid customerId: description: >- The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string created: description: >- The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string updated: description: >- The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string bankName: description: >- The name of the financial institution where the account is held. example: Bank of America type: string accountName: description: A descriptive name for this bank account. example: Checking Account type: string currency: description: The currency of the bank account. example: usd type: string enum: - usd accountDetails: description: >- USD account details. For ACH/Wire: accountNumber, routingNumber, accountType. For SWIFT: accountNumber (masked), bic. oneOf: - type: object properties: accountNumber: description: >- The bank account number for the US bank account (masked, last 4 characters visible). Present when currency is usd. example: '****7890' type: string routingNumber: description: >- The 9-digit ABA routing number (also known as routing transit number) that identifies the US financial institution. Present when currency is usd. example: '021000021' type: string accountType: description: >- The type of US bank account. Present when currency is usd. example: checking type: string enum: - checking - savings - instapay - pesonet x-enumNames: - Checking - Savings - Instapay - Pesonet required: - accountNumber - routingNumber - accountType - type: object properties: accountNumber: description: >- The account number for SWIFT transfers (masked, last 4 characters visible). Present when currency is usd and networks is ["swift"]. example: '******7890' type: string bic: description: >- The BIC/SWIFT code of the beneficiary bank. Present when currency is usd and networks is ["swift"]. example: DEUTDEFF type: string intermediaryBics: description: >- 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. example: - CHASUS33 type: array items: type: string required: - accountNumber - bic accountOwner: description: >- Information about the account owner, including their name and relationship to the customer. type: object properties: accountHolderName: description: >- The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: >- The relationship of the account owner to the customer. example: self type: string enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown required: - accountHolderName - relationship networks: description: >- 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"]. example: - wire - ach oneOf: - type: array items: type: string enum: - ach - wire - type: array items: oneOf: - type: string enum: - swift required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks - title: EUR type: object properties: id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string status: description: The current status of the bank account. example: active type: string enum: - pending - active - inactive - invalid x-enumNames: - Pending - Active - Inactive - Invalid customerId: description: >- The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string created: description: >- The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string updated: description: >- The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string bankName: description: >- The name of the financial institution where the account is held. example: Deutsche Bank type: string accountName: description: A descriptive name for this bank account. example: Hauptkonto type: string currency: description: The currency of the bank account. example: eur type: string enum: - eur accountDetails: description: EUR/SEPA account details including iban and bic. type: object properties: iban: description: >- 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. example: GB29****************6819 type: string bic: description: >- The Bank Identifier Code (BIC), also known as SWIFT code. Present when currency is eur. example: COBADEFFXXX type: string required: - iban - bic accountOwner: description: >- Information about the account owner, including their name and relationship to the customer. type: object properties: accountHolderName: description: >- The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: >- The relationship of the account owner to the customer. example: self type: string enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown required: - accountHolderName - relationship networks: description: >- The payment networks supported by this bank account. For EUR accounts, is exactly ["sepa"]. example: - sepa type: array items: type: string enum: - sepa required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks - title: BRL type: object properties: id: description: The unique identifier of the bank account. example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045 type: string status: description: The current status of the bank account. example: active type: string enum: - pending - active - inactive - invalid x-enumNames: - Pending - Active - Inactive - Invalid customerId: description: >- The unique identifier of the customer who owns this bank account. example: customer_66c4168d418a410eae282b83883bdc39 type: string created: description: >- The ISO 8601 timestamp when the bank account was created. example: '2025-01-01T00:00:00Z' type: string updated: description: >- The ISO 8601 timestamp when the bank account was last updated. example: '2025-01-01T00:00:00Z' type: string bankName: description: >- The name of the financial institution where the account is held. example: Itaú type: string accountName: description: A descriptive name for this bank account. example: Conta PIX Alice Santos type: string currency: description: The currency of the bank account. example: brl type: string enum: - brl accountDetails: description: >- BRL/PIX account details including pixKey and pixKeyType. type: object properties: pixKey: description: >- The masked PIX key for Brazilian PIX transfers. Present when currency is brl. example: a*c@g***l.com type: string pixKeyType: description: The type of PIX key. Present when currency is brl. example: email type: string enum: - cpf - cnpj - email - phone - random required: - pixKey - pixKeyType accountOwner: description: >- Information about the account owner, including their name and relationship to the customer. type: object properties: accountHolderName: description: >- The name of the account holder as it appears on the bank account. example: John Doe type: string relationship: description: >- The relationship of the account owner to the customer. example: self type: string enum: - self - holding_company - subsidiary_company - branch_office - business_partner - supplier - customer - creditor - debtor - franchisee - unknown required: - accountHolderName - relationship networks: description: >- The payment networks supported by this bank account. For BRL accounts, is exactly ["pix"]. example: - pix type: array items: type: string enum: - pix required: - id - status - customerId - created - updated - bankName - accountName - currency - accountDetails - accountOwner - networks '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Bad Request: summary: Bad Request value: status: 400 detail: Invalid request parameters code: address/invalid correlationId: 28c61e885c6e5eaa78c1a2183a9b883c '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Not Found: summary: Not Found value: status: 404 detail: Resource not found code: resource/not-found correlationId: 28c61e885c6e5eaa78c1a2183a9b883c '422': description: Unprocessable Entity - Validation Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetailsDto' examples: Validation Error: summary: Validation Error value: status: 422 detail: Validation failed code: validation/failed correlationId: 28c61e885c6e5eaa78c1a2183a9b883c errors: - detail: Invalid email format pointer: /email - detail: Name is required pointer: /name components: schemas: ProblemDetailsDto: type: object properties: title: type: string status: type: integer detail: type: string code: type: string errors: type: array items: type: object properties: detail: type: string pointer: type: string parameter: type: string header: type: string required: - detail correlationId: type: string required: - status - detail securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````