Create a Bank Account

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

Authorization

bearer

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

customerId*string

The unique identifier of the customer who owns this bank account.

Length1 <= length

bankName*string

The name of the financial institution where the account is held.

Length1 <= length

accountName*string

A descriptive name for this bank account (e.g., "Checking Account", "Business Account").

Length1 <= length

currency*string

The currency of the bank account. When set to usd, accountDetails must contain accountNumber, routingNumber, and accountType.

Value in"usd"

accountDetails*

USD account details. Required fields: accountNumber, routingNumber, accountType.

accountOwner*

Information about the account owner, including their name, address, and relationship to the customer.

networks*array<>

The payment networks supported by this bank account. For USD accounts, must include at least one of "ach" or "wire" (specify both wire and ach if unsure).

Items1 <= items

customerId*string

The unique identifier of the customer who owns this bank account.

Length1 <= length

bankName*string

The name of the financial institution where the account is held.

Length1 <= length

accountName*string

A descriptive name for this bank account (e.g., "Checking Account", "Business Account").

Length1 <= length

currency*string

The currency of the bank account. When set to eur, accountDetails must contain iban and bic.

Value in"eur"

accountDetails*

EUR/SEPA account details. Required fields: iban, bic.

accountOwner*

Information about the account owner, including their name, address, and relationship to the customer.

networks*array<>

The payment networks supported by this bank account. For EUR accounts, must be exactly ["sepa"].

customerId*string

The unique identifier of the customer who owns this bank account.

Length1 <= length

bankName*string

The name of the financial institution where the account is held.

Length1 <= length

accountName*string

A descriptive name for this bank account (e.g., "Checking Account", "Business Account").

Length1 <= length

currency*string

The currency of the bank account. When set to brl, accountDetails must contain pixKey and pixKeyType.

Value in"brl"

accountDetails*

BRL/PIX account details. Required fields: pixKey, pixKeyType.

accountOwner*

The bank account holder details.

networks*array<>

The payment networks supported by this bank account. For BRL accounts, must be exactly ["pix"].

Response Body

`application/json`

curl -X POST "https://api.spherepay.co/v2/bank-account" \  -H "Content-Type: application/json" \  -d '{    "customerId": "customer_66c4168d418a410eae282b83883bdc39",    "bankName": "Bank of America",    "accountName": "Checking Account",    "currency": "usd",    "accountDetails": {      "accountNumber": "9876543210",      "routingNumber": 26009593,      "accountType": "checking"    },    "accountOwner": {      "accountHolderName": "Sarah Johnson",      "address": {        "line1": "233 South Wacker Drive",        "city": "Chicago",        "country": "USA"      }    },    "networks": [      "wire",      "ach"    ]  }'

{
  "id": "bankAccount_ce745ef7f3df4b9a8bff1301ce24b045",
  "status": "active",
  "bankName": "Bank of America",
  "accountName": "Checking Account",
  "customerId": "customer_66c4168d418a410eae282b83883bdc39",
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-01-01T00:00:00Z",
  "currency": "usd",
  "accountDetails": {
    "accountNumber": "****7890",
    "routingNumber": "021000021",
    "accountType": "checking"
  },
  "accountOwner": {
    "accountHolderName": "John Doe",
    "relationship": "self"
  },
  "networks": [
    "wire",
    "ach"
  ]
}

{
  "status": 400,
  "detail": "Invalid request parameters",
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 404,
  "detail": "Resource not found",
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}

{
  "status": 422,
  "detail": "Validation failed",
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ]
}

Create a Bank Account

Authorization

Request Body

Response Body

201application/json

400application/json

404application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`