Bank Accounts

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

Bank accounts are owned by your customers or application. They can be used as the source or destination in the creation of transfers.

Sphere verifies every bankAccounts on creation. On creation bankAccounts will have a pending status until verified by Sphere. They will move to a status of active once verified.

For convenience, developers may add bankAccounts to customers in any kycStatus. They will remain in a status of pending until the kycStatus and tosStatus of the associated customer are set to approved.

The Bank Account object

The following is the json object respresentation of a Sphere bankAccount.

Properties

  • Name
    id
    Type
    string
    Description

    A unique identifier for the object.

  • Name
    status
    Type
    string
    Description

    The status of the bank account.

    • pending: The account is pending verification by Sphere. On creation, set to pending.
    • active: The account has been verified and is ready for use.
    • inactive: The account has been deleted or deactivated by Sphere.
    • invalid: The account has failed validation and likely contains bad information.
  • Name
    customer
    Type
    string
    Description

    The id of the customer associated with the bank account.

  • Name
    bankName
    Type
    string
    Description

    Name of the bank account associated with the routing number. (e.g. BOFA).

  • Name
    accountName
    Type
    string
    Description

    The name of the account associated with the bank account object.

  • Name
    accountType
    Type
    enum
    Description

    The type of bank account. Either checking or savings.

  • Name
    currency
    Type
    string
    Description

    Base currency that the bank account operates in. Either usd or eur. Defaults to usd.

  • Name
    accountNumber
    Type
    string
    Description

    The account number of the bank account. (censored on GET requests)

  • Name
    routingNumber
    Type
    string
    Description

    The routing number of the bank account.

  • Name
    last4
    Type
    string
    Description

    The last four digits of either the bank account accountNumber or IBAN.

  • Name
    bic
    Type
    string
    Description

    The Business/Bank Identifier Code of the bank account. Assigned to a bank by SWIFT and used to facilitate international transfers. Relevant for Euro bank accounts.

  • Name
    iban
    Type
    string
    Description

    The International bank account number of the bank account. Used for transfers between banks and financial institutions. Relevant for Euro bank accounts.

  • Name
    accountHolderName
    Type
    string
    Description

    The name of the customer that owns the bank account.

  • Name
    meta
    Type
    object
    Description

    Set of key-value pairs (JSON) that you can attach to a bank account object which can be useful for storing additional information about the object.

  • Name
    lookupKey
    Type
    string
    Description

    The lookup key of a bank account. A lookup key allows you to list all resources associated with a given key.

  • Name
    beneficiaryAddress
    Type
    object
    Description

    The address of the beneficiary of the bank account.

    • Name
      line1
      Type
      string
      Description

      Address line 1 (e.g., street, PO Box, or company name).

    • Name
      line2
      Type
      string
      Description

      Address line 2 (e.g., apartment, suite, unit, or building).

    • Name
      city
      Type
      string
      Description

      City, district, suburb, town, or village.

    • Name
      postalCode
      Type
      string
      Description

      ZIP or postal code.

    • Name
      state
      Type
      string
      Description

      Two-letter state code (ISO3166 subdivision code)

    • Name
      country
      Type
      string
      Description

      Three-letter country code (ISO 3166-1 alpha-3).

  • Name
    updated
    Type
    string
    Description

    Datetime at which the account was last updated.

  • Name
    created
    Type
    string
    Description

    Datetime at which the account was created.

  • Name
    deleted
    Type
    string
    Description

    Datetime at which the account was deleted. The deletion of a bank account is actually a soft deletion which sets the status to inactive.

BankAccount Object

{
  "id": "bankAccount_2863bb63b87342f1a6376fa0e8ffcbce",
  "status": "active",
  "customer": "customer_f5bd32a916584675b739b8e2301f1480",
  "bankName": "Citibank",
  "accountName": "Citibank Checking Account",
  "accountType": "checking",
  "currency": "usd",
  "routingNumber": "091409571",
  "last4": "4823",
  "iban": null,
  "bic": null,
  "accountHolderName": "John Doe",
  "meta": {},
  "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
  "updated": "2024-08-12T21:29:34.661Z",
  "created": "2024-08-12T21:29:34.661Z",
  "deleted": null
}
POST/v1/bankAccount

Create a bank account

Parameters

  • Name
    customer
    Type
    string
    Description

    The id of the customer associated with the bank account. If not provided, the application customer will be used instead.

  • Name
    bankName
    Type
    string
    Description

    The name of the bank associated with the bank account.

  • Name
    accountName
    Type
    string
    Description

    The name of the account associated with the bank account object.

  • Name
    accountType
    Type
    enum
    Description

    The type of bank account. Either checking or savings.

  • Name
    currency
    Type
    enum
    Description

    The currency of the bank account. Either usd or eur. Defaults to usd.

  • Name
    currency
    Type
    string
    Description

    Base currency that the bank account operates in. Either usd or eur. Defaults to usd.

  • Name
    accountNumber
    Type
    string
    Description

    The account number of the bank account. Relevant for currency usd accounts.

  • Name
    routingNumber
    Type
    string
    Description

    The routing number of the bank account. Relevant for currency usd accounts.

  • Name
    iban
    Type
    string
    Description

    The IBAN of the bank account. Relevant forcurrency eur accounts.

  • Name
    bic
    Type
    string
    Description

    The BIC of the bank account. Relevant for currency eur accounts.

  • Name
    accountHolderName
    Type
    string
    Description

    The name of the beneficiary of the bank account.

  • Name
    meta
    Type
    object
    Description

    Set of key-value pairs (JSON) that you can attach to a bank account object which can be useful for storing additional information about the object.

  • Name
    meta
    Type
    object
    Description

    Set of key-value pairs (JSON) that you can attach to a bank account object which can be useful for storing additional information about the object.

  • Name
    lookupKey
    Type
    string
    Description

    The lookup key of a bank account. A lookup key allows you to list all resources associated with a given key.

  • Name
    beneficiaryAddress
    Type
    object
    Description

    The address of the beneficiary of the bank account.

    • Name
      line1
      Type
      string
      Description

      Address line 1 (e.g., street, PO Box, or company name).

    • Name
      line2
      Type
      string
      Description

      Address line 2 (e.g., apartment, suite, unit, or building).

    • Name
      city
      Type
      string
      Description

      City, district, suburb, town, or village.

    • Name
      postalCode
      Type
      string
      Description

      ZIP or postal code.

    • Name
      state
      Type
      string
      Description

      Two-letter state code (ISO3166 subdivision code)

    • Name
      country
      Type
      string
      Description

      Three-letter country code (ISO 3166-1 alpha-3).

Request

POST
/v1/bankAccount
curl https://api.spherepay.co/v1/bankAccount \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{
    \"accountName\": \"Example bank account\",
    \"bankName\": \"Bank of America\",
    \"accountType\": \"checking\",
    \"accountNumber\": \"123456789\",
    \"routingNumber\": \"987654321\"
  }"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccount": {
      "id": "bankAccount_2863bb63b87342f1a6376fa0e8ffcbce",
      "status": "active",
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "bankName": "Citibank",
      "accountName": "Citibank Checking Account",
      "accountType": "checking",
      "currency": "usd",
      "routingNumber": "091409571",
      "last4": "4823",
      "iban": null,
      "bic": null,
      "accountHolderName": "John Doe",
      "meta": {},
      "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
      "updated": "2024-08-12T21:29:34.661Z",
      "created": "2024-08-12T21:29:34.661Z",
      "deleted": null
    }
  },
  "ts": "2024-08-12T21:29:34.683Z",
  "request": "request_286ec04fadcf439fa1294317417b7e6d"
}
GET/v1/bankAccount/:id

Retrieve a bank account

Request

GET
/v1/bankAccount/:id
curl https://api.spherepay.co/v1/bankAccount/bankAccount_9320f293cfcc400caddf8bc9170eedd0 \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccount": {
      "id": "bankAccount_2863bb63b87342f1a6376fa0e8ffcbce",
      "status": "active",
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "bankName": "Citibank",
      "accountName": "Citibank Checking Account",
      "accountType": "checking",
      "currency": "usd",
      "routingNumber": "091409571",
      "last4": "4823",
      "iban": null,
      "bic": null,
      "accountHolderName": "John Doe",
      "meta": {},
      "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
      "updated": "2024-08-12T21:29:34.661Z",
      "created": "2024-08-12T21:29:34.661Z",
      "deleted": null
    }
  },
  "ts": "2024-08-12T21:41:54.167Z",
  "request": "request_1315a2d4288e4eb98827a8d90cdf99fe"
}
GET/v1/bankAccount

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
    customer
    Type
    string
    Description

    List transfers from a given customer id.

  • 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
/v1/bankAccount
curl -G https://api.spherepay.co/v1/bankAccount \
  -H "Authorization: Bearer {token}" \
  -d customer="customer_f5bd32a916584675b739b8e2301f1480" \
  -d limit=2

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccounts": [
      {
        "id": "bankAccount_2863bb63b87342f1a6376fa0e8ffcbce",
        "status": "active",
        "customer": "customer_f5bd32a916584675b739b8e2301f1480",
        "bankName": "Citibank",
        "accountName": "Citibank Checking Account",
        "accountType": "checking",
        "currency": "usd",
        "routingNumber": "091409571",
        "last4": "4823",
        "iban": null,
        "bic": null,
        "accountHolderName": "John Doe",
        "meta": {},
        "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
        "updated": "2024-08-12T21:29:34.661Z",
        "created": "2024-08-12T21:29:34.661Z",
        "deleted": null
      },
      {
        "id": "bankAccount_d6b206dc878a43da850049dc8d925f88",
        // ...
      }
    ]
  },
  "ts": "2024-08-12T21:35:19.018Z",
  "request": "request_4c42d2abf8644090a3954aa94fec900b"
}
DELETE/v1/bankAccount/: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/v1/bankAccount/bankAccount_9320f293cfcc400caddf8bc9170eedd0 \
-H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "bankAccount": {
      "id": "bankAccount_2863bb63b87342f1a6376fa0e8ffcbce",
      "status": "active",
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "bankName": "Citibank",
      "accountName": "Citibank Checking Account",
      "accountType": "checking",
      "currency": "usd",
      "routingNumber": "091409571",
      "last4": "4823",
      "iban": null,
      "bic": null,
      "accountHolderName": "John Doe",
      "meta": {},
      "lookupKey": "b9a34cf6004a4e8383492c50d56a375b",
      "updated": "2024-08-12T21:29:34.661Z",
      "created": "2024-08-12T21:29:34.661Z",
      "deleted": null
    }
  },
  "ts": "2024-08-12T21:42:52.896Z",
  "request": "request_28e5a85abec74e0f8b4683f156b2b0de"
}

Was this page helpful?