Bank Accounts

A bank account is an account held at a bank or other financial institution on behalf of your company or customers.

A bank account is owned either by your customers or your application. It can be used as a source or destination when creating transfers.

Sphere verifies every bank account upon creation. When a bank account is created, it will initially have a pending status until it is verified by Sphere. Once verified, its status will change to active.

Endpoints

POST

/v2/customers/:id/bank-account

GET

/v2/customers/:id/bank-account/:id

GET

/v2/customers/:id/bank-account

DELETE

/v2/bank-account/:id

Supported Currencies

The following table shows the supported currencies for bank accounts based on use case:

Currency	B2B	B2C	C2C
🇺🇸 USD	✅	✅	✅
🇪🇺 EUR	✅	✅	✅
🇧🇷 BRL	✅	✅	✅
🇲🇽 MXN	✅	✅	✅
🇵🇭 PHP	✅	✅	✅
🇨🇴 COP	✅	✅	Coming Soon
🇬🇧 GBP	✅	✅	Coming Soon
🇮🇳 INR	✅	✅	Coming Soon
🇸🇬 SGD	✅	✅	Coming Soon
🇻🇳 VND	✅	✅	Coming Soon
🇹🇭 THB	✅	✅	Coming Soon
🇮🇩 IDR	✅	✅	Coming Soon

The Bank Account object

The following is the json object representation of a Sphere bank-account.

Properties

Name: id
Type: string
Description: A unique identifier assigned to the bank account object, which allows it to be distinctly recognized within the system.

Name

status

Type

string

Description

Indicates the current state of the bank account:

pending: The account is awaiting verification by Sphere. This is the default status upon creation.
active: The account has been successfully verified and is operational.
inactive: The account has been deactivated or soft-deleted by Sphere.
invalid: The account did not pass validation due to incorrect or incomplete information.

Name: customer
Type: string
Description: Represents the unique id of the customer associated with the bank account.

Name: currency
Type: enum
Description: Defines the operating currency for the bank account.

Name

accountDetails

Type

object

Description

Contains detailed information about the user's bank account, varying based on the selected currency.

Select Option:

Name: bankName
Type: string
Description: Specifies the name of the bank associated with the account, such as "Bank of America."

Name: accountHolderName
Type: string
Description: The full name of the individual or entity that owns the bank account.

Name: accountName
Type: string
Description: The name or alias of the account used for identification purposes.

Name: accountNumber
Type: string
Description: The unique number identifying the bank account (masked in retrieval operations).

Name: routingNumber
Type: string
Description: The nine-digit routing number used to identify the bank and process transactions within the United States.

Name: accountType
Type: enum
Description: Specifies the type of bank account. Valid values are checking or savings.

Name: lookupKey
Type: string
Description: A unique key that allows for quick retrieval of resources associated with the bank account.

Name: meta
Type: object
Description: A JSON object containing additional custom information about the bank account in key-value pairs.

Name

beneficiaryAddress

Type

object

Description

Contains the address details of the account's beneficiary.

Name
line1
Type
string
Description
The first line of the address, such as the street name, PO Box, or company name.
Name
line2
Type
string
Description
The second line of the address, such as the apartment, suite, or unit number.
Name
city
Type
string
Description
The city, district, suburb, or town where the beneficiary resides.
Name
postalCode
Type
string
Description
The ZIP or postal code of the beneficiary's address.
Name
state
Type
string
Description
The two-letter state or province code, following the ISO-3166 subdivision code.
Name
country
Type
string
Description
The three-letter country code of the beneficiary's address, adhering to ISO-3166-1 alpha-3.

Name: updated
Type: string
Description: The timestamp of the last update made to the bank account, formatted as an ISO 8601 string.

Name: created
Type: string
Description: The timestamp of when the bank account was first created, formatted as an ISO 8601 string.

Name: deleted
Type: string
Description: The timestamp of when the bank account was deactivated or deleted. Deletion is performed as a soft delete, setting the account status to inactive.

BankAccount Object

{
"id": "bankAccount_123e4567-e89b-12d3-a456-426614174000",
"status": "active",
"customer": "cus_abc123",
"currency": "usd",
"accountDetails": {
  "bankName": "Bank of America",
  "accountHolderName": "John Doe",
  "accountName": "Primary Checking Account",
  "accountNumber": "****5678",
  "routingNumber": "123456789",
  "accountType": "checking"
},
"lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
"meta": {
  "purpose": "Payroll Account",
  "notes": "Main bank account for business transactions"
},
"beneficiaryAddress": {
  "line1": "123 Elm Street",
  "line2": "Suite 500",
  "city": "San Francisco",
  "postalCode": "94107",
  "state": "CA",
  "country": "USA"
},
"updated": "2025-01-24T12:34:56Z",
"created": "2025-01-01T09:00:00Z",
"deleted": null
}

POST/v2/customer/:id/bankAccount

Create a bank account

Create a new bank account object.

Parameters

Name: bankName
Type: string
Required: Required
Description: The name of the financial institution where the bank account is held.

Name: accountName
Type: string
Required: Required
Description: A descriptive or user-defined name for the bank account, often used for identification purposes.

Name: currency
Type: enum
Required: Required
Description: The currency in which the bank account operates, defined as an ISO 4217 currency code.

Name

beneficiaryAddress

Type

object

Required

Required

Description

Contains the physical address details of the account's beneficiary.

Name
line1
Type
string
Description
The primary address line, such as a street name, PO Box, or building name.
Name
line2
Type
string
Description
Additional address details, such as an apartment, suite, or unit number.
Name
city
Type
string
Description
The name of the city, town, or municipality where the beneficiary resides.
Name
postalCode
Type
string
Description
The postal or ZIP code for the beneficiary's address.
Name
state
Type
string
Description
A two-letter state or province code following the ISO-3166 subdivision standard.
Name
country
Type
string
Description
A three-letter ISO-3166 country code representing the beneficiary's location.

Name: meta
Type: object
Description: A customizable set of key-value pairs that allows additional metadata to be stored about the bank account.

Name: lookupKey
Type: string
Description: A unique identifier used to query or retrieve resources linked to a specific bank account.

Name

thirdPartyBeneficiaryInfo

Type

object

Description

Details about a third-party beneficiary, which vary depending on whether they are an individual or a business.

Select Option:

Name

accountDetails

Type

object

Required

Required

Description

Contains detailed attributes of the bank account, tailored to the specified currency.

Select Option:

Name: accountNumber
Type: string
Description: The unique number identifying the bank account (masked in retrieval operations for security).

Name: routingNumber
Type: string
Description: The nine-digit routing number for identifying banks and processing domestic transactions in the United States.

Name: accountType
Type: enum
Description: Specifies the type of account, with valid values being checking or savings.

Request

POST

/v2/customers/:id/bank-account

curl https://api.spherepay.co/v2/customers/:id/bank-account \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "accountName": "John Doe Savings",
    "bankName": "Bank of America",
    "currency": "USD",
    "beneficiaryAddress": {
      "line1": "123 Elm Street,
      "line2": "suite 456",
      "city": "New York",
      "postalCode": "10001",
      "state": "NY",
      "country": "USA"
    },
    "meta": {
      "purpose": "Payroll Account",
      "notes": "Main account for business transactions"
    }
    "lookupKey": "10000000001",
    "accountDetails": {
      "accountType": "checking",
      "accountNumber": "123456789",
      "routingNumber": "987654321"
    }
  }'

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccount": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "customer": "cus_abc123",
      "currency": "usd",
      "accountDetails": {
        "bankName": "Bank of America",
        "accountHolderName": "John Doe",
        "accountName": "Primary Checking Account",
        "accountNumber": "****5678",
        "routingNumber": "123456789",
        "accountType": "checking"
      },
      "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
      "meta": {
        "purpose": "Payroll Account",
        "notes": "Main bank account for business transactions"
      },
      "beneficiaryAddress": {
        "line1": "123 Elm Street",
        "line2": "Suite 500",
        "city": "San Francisco",
        "postalCode": "94107",
        "state": "CA",
        "country": "USA"
      },
      "updated": "2025-01-24T12:34:56Z",
      "created": "2025-01-01T09:00:00Z",
      "deleted": null
    }
  },
  "ts": "2024-08-12T21:29:34.683Z",
  "request": "request_286ec04fadcf439fa1294317417b7e6d"
}

GET/v2/customers/:id/bank-account/:id

Retrieve a bank account

This endpoint allows you to retrieve a detailed breakdown of the bankAccount object. You can use the id of the bank account to retrieve the object.

Request

GET

/v2/customers/:id/bank-account/:id

curl https://api.spherepay.co/v2/customers/:id/bank-account/:id \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccount": {
      "bankAccount": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "customer": "cus_abc123",
        "currency": "usd",
        "accountDetails": {
          "bankName": "Bank of America",
          "accountHolderName": "John Doe",
          "accountName": "Primary Checking Account",
          "accountNumber": "****5678",
          "routingNumber": "123456789",
          "accountType": "checking"
        },
        "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
        "meta": {
          "purpose": "Payroll Account",
          "notes": "Main bank account for business transactions"
        },
        "beneficiaryAddress": {
          "line1": "123 Elm Street",
          "line2": "Suite 500",
          "city": "San Francisco",
          "postalCode": "94107",
          "state": "CA",
          "country": "USA"
        },
        "updated": "2025-01-24T12:34:56Z",
        "created": "2025-01-01T09:00:00Z",
        "deleted": null
      }
    }
  },
  "ts": "2024-08-12T21:41:54.167Z",
  "request": "request_1315a2d4288e4eb98827a8d90cdf99fe"
}

GET/v2/customers/:id/bank-account

List bank accounts

This endpoint allows you to retrieve a paginated list of all your contacts. By default, a maximum of ten contacts are shown per page.

Parameters

Name: lookupKey
Type: string
Description: List transfers from a given lookup key.

Name: limit
Type: number
Description: Limit the number of bank accounts returned. The maximum value per query is 200. Defaults to 25.

Name: startDate
Type: string
Description: The start datetime of the bank accounts to retrieve.

Name: endDate
Type: string
Description: The end datetime of the bank accounts to retrieve.

Request

GET

/v2/customers/:id/bank-account

curl -G https://api.spherepay.co/v2/customers/:id/bank-account \
  -H "Authorization: Bearer {token}" \
  -d limit=2

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccounts": [
      {
        "id": "bankAccount_123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "customer": "cus_abc123",
        "currency": "usd",
        "accountDetails": {
          "bankName": "Bank of America",
          "accountHolderName": "John Doe",
          "accountName": "Primary Checking Account",
          "accountNumber": "****5678",
          "routingNumber": "123456789",
          "accountType": "checking"
        },
        "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
        "meta": {
          "purpose": "Payroll Account",
          "notes": "Main bank account for business transactions"
        },
        "beneficiaryAddress": {
          "line1": "123 Elm Street",
          "line2": "Suite 500",
          "city": "San Francisco",
          "postalCode": "94107",
          "state": "CA",
          "country": "USA"
        },
        "updated": "2025-01-24T12:34:56Z",
        "created": "2025-01-01T09:00:00Z",
        "deleted": null
      },
      {
        "id": "bankAccount_d6b206dc878a43da850049dc8d925f88",
        // ...
      }
    ]
  },
  "ts": "2024-08-12T21:35:19.018Z",
  "request": "request_4c42d2abf8644090a3954aa94fec900b"
}

DELETE/v2/customers/:id/bank-account/:id

Delete a bankAccount

This endpoint allows you to delete a bank account by its id. Deleting a bank account sets its status to inactive. You can not fetch a deleted bank account.

Request

DELETE

/v1/bankAccount/:id

curl -X DELETE https://api.spherepay.co/v2/customers/:id/bank-account/:id \
-H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccount": {
      "id": "bankAccount_123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "customer": "cus_abc123",
      "currency": "usd",
      "accountDetails": {
        "bankName": "Bank of America",
        "accountHolderName": "John Doe",
        "accountName": "Primary Checking Account",
        "accountNumber": "****5678",
        "routingNumber": "123456789",
        "accountType": "checking"
      },
      "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
      "meta": {
        "purpose": "Payroll Account",
        "notes": "Main bank account for business transactions"
      },
      "beneficiaryAddress": {
        "line1": "123 Elm Street",
        "line2": "Suite 500",
        "city": "San Francisco",
        "postalCode": "94107",
        "state": "CA",
        "country": "USA"
      },
      "updated": "2025-01-24T12:34:56Z",
      "created": "2025-01-01T09:00:00Z",
      "deleted": "2025-01-04T09:00:00Z"
    }
  },
  "ts": "2024-08-12T21:42:52.896Z",
  "request": "request_28e5a85abec74e0f8b4683f156b2b0de"
}