Bank Accounts

A Bank Account is an account held at a bank or other financial institution on behalf of your Customers.

They can be used in two ways:

  1. As the source or destination in payouts.
  2. As the destination in the creation of bank wallets.

All bank accounts are created with a status of 'pending'.

Bank accounts can be added to customers in any kycStatus. Bank accounts will remain in a status of 'pending' until the customer’s KYC status is verified and approved.

The Bank Account object

Properties

  • Name
    id
    Type
    string
    Description

    A unique identifier for the bank account. Auto-generated by Sphere upon creation.

  • Name
    status
    Type
    string
    Description

    The status of the bank account.

    • pending: The default status on creation.
    • active: The status after the bank account has been verified and is ready for use in payouts.
    • inactive: The status after the bank account has been deleted (soft deleted).
    • invalid: The status after the bank account creation fails (e.g., due to a failed verification).
    • On bank account creation, the status is pending until it is either set to active or invalid.
    • On bank account deletion, the status is either active, inactive, or pending, until it is set to inactive. Possible values are pending, active, inactive and invalid.
  • 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
    customer
    Type
    string
    Description

    The id of the customer associated with the bank account.

  • Name
    currency
    Type
    string
    Description

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

  • Name
    accountHolderName
    Type
    string
    Description

    The name of the customer that owns the bank account.

  • Name
    accountNumber
    Type
    string
    Description

    The account number of the bank account

  • Name
    routingNumber
    Type
    string
    Description

    The routing number of the bank account

  • Name
    bic
    Type
    string
    Description

    The BIC of the bank account. Relevant for Euro bank accounts.

  • Name
    iban
    Type
    string
    Description

    The IBAN of the bank account. Relevant for Euro bank accounts.

  • Name
    bankAddressString
    Type
    string
    Description

    The bank address string of the bank account. Primarily used to display the bank address for deposit instructions.

  • Name
    last4
    Type
    string
    Description

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

  • 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
    provider
    Type
    enum
    Description

    The bank provider of the bank account. Either bridge, teller, or plaid. Defaults to bridge.

  • 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
    mock
    Type
    boolean
    Description

    Whether the bank account is a mock bank account. Defaults to false. It is recommended to keep this value as false, even for testing purposes as it will not affect payouts.

  • Name
    accountType
    Type
    enum
    Description

    The type of bank account. Either checking or savings.

  • Name
    walletBankAccounts
    Type
    object array
    Description

    A list of walletBankAccount objects linked to this bank account. A wallet bank account is a wallet which whenever funded a given currency on a network, it flushes that balance to the bank account it is linked to.

    • Name
      id
      Type
      string
      Description

      Unique identifier for the wallet bank account. Auto-generated by Sphere upon creation.

    • Name
      wallet
      Type
      object
      Description

      The wallet object that is linked to the bank account. This is the source object.

      • Refer to the Wallet object for more details.
    • Name
      bankAccount
      Type
      object
      Description

      The bankAccount object that is linked to the wallet. This is the destination object.

    • Name
      sourceCurrency
      Type
      enum
      Description

      The currency that the wallet will receive. Either usdc or usdt.

    • Name
      destinationCurrency
      Type
      enum
      Description

      The currency that the bank account will receive. Defaults to usd.

    • Name
      sourceNetwork
      Type
      enum
      Description

      The network of the wallet. Either sol, ethereum, or `optimism.

    • Name
      destinationNetwork
      Type
      enum
      Description

      The network of that the bank account will receive funds through. Either ach or wire.

    • Name
      wireMessage
      Type
      string
      Description

      The wire message that is used when initiating a wire transfer to the bank account. Can at most be 3 lines long, separated by \n, each with a maximum length of 35 characters.

  • 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": "pending",
  "bankName": "U2FsdGVkX18SK4oQk58TGmA5PjSftTvNUWBKDYSm0Ao=",
  "accountHolderName": "***",
  "accountName": "U2FsdGVkX18eBhtzsFIRM+oanNp5cfQMyzYTZWr1e5a4hF+1JvU7OZVx92XH/vZK",
  "accountNumber": "***",
  "customer": "customer_f5bd32a916584675b739b8e2301f1480",
  "last4": "pO0=",
  "routingNumber": "***",
  "bic": null,
  "iban": null,
  "bankAddressString": null,
  "meta": {},
  "lookupKey": null,
  "currency": "usd",
  "provider": "bridge",
  "beneficiaryAddress": {
    "line1": "123 N Main St",
    "line2": "",
    "city": "San Francisco",
    "postalCode": "94103",
    "state": "CA",
    "country": "USA"
  },
  "walletBankAccounts": [],
  "mock": false,
  "accountType": "U2FsdGVkX19q6ymtoGrZ5GE1anrDHZ8xaZVI0cNqGW4=",
  "updated": "2024-08-12T21:29:34.661Z",
  "created": "2024-08-12T21:29:34.661Z",
  "deleted": null
}
POST/v1/bankAccount

Create a bank account

This endpoint allows you to create a new bank account.

Parameters

  • Name
    accountNumber
    Type
    string
    Required
    Required
    Description

    The account number of the bank account.

    • Either accountNumber and routingNumber (for usd currency) or iban and bic (for eur currency) are required.
  • Name
    routingNumber
    Type
    string
    Required
    Required
    Description

    The routing number of the bank account.

    • Either accountNumber and routingNumber (for usd currency) or iban and bic (for eur currency) are required.
  • Name
    iban
    Type
    string
    Required
    Required
    Description

    The IBAN of the bank account. Relevant for Euro bank accounts.

    • Either accountNumber and routingNumber (for usd currency) or iban and bic (for eur currency) are required.
  • Name
    bic
    Type
    string
    Required
    Required
    Description

    The BIC of the bank account. Relevant for Euro bank accounts.

    • Either accountNumber and routingNumber (for usd currency) or iban and bic (for eur currency) are required.
  • 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.

  • Name
    customer
    Type
    string
    Description

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

  • Name
    currency
    Type
    enum
    Description

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

  • Name
    accountType
    Type
    enum
    Description

    the type of the account, either checking or savings.

  • Name
    accountHolderName
    Type
    string
    Description

    The name of the beneficiary of the bank account. If not fielded, the customer's peronsalInfo.firstName and personalInfo.lastName will be used instead.

  • 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
    beneficiaryAddress
    Type
    object
    Description

    The address beneficiary of the bank account. If not provided, the address of the customer will be used. If not fielded, the customer's personalInfo.address will be used instead.

  • 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
    provider
    Type
    enum
    Description

    The bank account provider. One of 'bridge', 'teller', or 'plaid'. Defaults to 'bridge'.

  • Name
    bankAddressString
    Type
    string
    Description

    The bank address string of the bank account. Primarily used to display the bank address for deposit instructions.

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": "pending",
      "bankName": "U2FsdGVkX18SK4oQk58TGmA5PjSftTvNUWBKDYSm0Ao=",
      "accountHolderName": "***",
      "accountName": "U2FsdGVkX18eBhtzsFIRM+oanNp5cfQMyzYTZWr1e5a4hF+1JvU7OZVx92XH/vZK",
      "accountNumber": "***",
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "last4": "pO0=",
      "routingNumber": "***",
      "bic": null,
      "iban": null,
      "bankAddressString": null,
      "meta": {},
      "lookupKey": null,
      "currency": "usd",
      "provider": "bridge",
      "beneficiaryAddress": {
        "line1": "123 N Main St",
        "line2": "",
        "city": "San Francisco",
        "postalCode": "94103",
        "state": "CA",
        "country": "USA"
      },
      "walletBankAccounts": [],
      "mock": false,
      "accountType": "U2FsdGVkX19q6ymtoGrZ5GE1anrDHZ8xaZVI0cNqGW4=",
      "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

This endpoint allows you to retrieve a bank account by its id.

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_9320f293cfcc400caddf8bc9170eedd0",
      "status": "active",
      "bankName": "Bank of America",
      "accountHolderName": "***",
      "accountName": "Example bank account",
      "accountNumber": "***",
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "last4": "6789",
      "routingNumber": "***",
      "bic": null,
      "iban": null,
      "bankAddressString": null,
      "meta": {},
      "lookupKey": null,
      "currency": "usd",
      "provider": "bridge",
      "beneficiaryAddress": {
        "line1": "123 N Main St",
        "line2": "",
        "city": "San Francisco",
        "postalCode": "94103",
        "state": "CA",
        "country": "USA"
      },
      "walletBankAccounts": [],
      "mock": false,
      "accountType": "checking",
      "updated": "2024-08-12T21:41:30.598Z",
      "created": "2024-08-12T21:41:30.188Z",
      "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 payouts from a given customer id.

  • Name
    lookupKey
    Type
    string
    Description

    List payouts 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_3d67e78e590c4270bdebee7fc6d5075c",
        "status": "active",
        "bankName": "Wells Fargo",
        "accountHolderName": "***",
        "accountName": "EVERYDAY CHECKING",
        "accountNumber": "***",
        "customer": "customer_f5bd32a916584675b739b8e2301f1480",
        "last4": "1234",
        "routingNumber": "***",
        "bic": null,
        "iban": null,
        "bankAddressString": null,
        "meta": {},
        "lookupKey": null,
        "currency": "usd",
        "provider": "teller",
        "beneficiaryAddress": {
          "line1": "123 Main St",
          "line2": "",
          "city": "San Francisco",
          "postalCode": "94107",
          "state": "CA",
          "country": "USA"
        },
        "walletBankAccounts": [
          {
            "id": "wallet_076e5c74f1f84c918f867a4a6251c66f",
            "wallet": {
              "id": "wallet_b4ce88539101491493fe1a4c6a41660b",
              "address": "DQ2uSuokFLfK6mtprR5PvHrftJEUwbF7ai1k7B4fEmjC",
              "network": "sol",
              "nickname": null,
              "risk": null,
              "primary": false,
              "feePayer": false,
              "signed": false,
              "mock": false,
              "lookupKey": null,
              "customer": null,
              "owner": "bridge",
              "exported": null,
              "created": "2024-06-07T13:47:54.838Z",
              "updated": "2024-06-07T13:47:54.838Z",
              "deleted": null
            },
            "bankAccount": {
              "customer": null,
              "last4": "",
              "beneficiaryAddress": {
                "id": null,
                "line1": null,
                "line2": null,
                "city": null,
                "postalCode": null,
                "state": null,
                "country": null,
                "application": null
              },
              "walletBankAccounts": [],
              "deleted": null
            },
            "sourceCurrency": "usdc",
            "sourceNetwork": "sol",
            "destinationCurrency": "usd",
            "destinationNetwork": "ach",
            "wireMessage": null
          }
        ],
        "mock": false,
        "accountType": "checking",
        "updated": "2024-01-19T19:00:03.749Z",
        "created": "2024-01-19T04:45:36.554Z",
        "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_9320f293cfcc400caddf8bc9170eedd0",
      "status": "inactive",
      "bankName": "U2FsdGVkX18Gyg0GiuRT6XIF/+4uwo9QfecwVUSrheM=",
      "accountHolderName": "***",
      "accountName": "U2FsdGVkX19aXrblnlCSit0xAEQMpraH0MLIEDUtyq5NZ2K02CI/sucEYFlbhvGY",
      "accountNumber": "***",
      "customer": "customer_f5bd32a916584675b739b8e2301f1480",
      "last4": "BEo=",
      "routingNumber": "***",
      "bic": null,
      "iban": null,
      "bankAddressString": null,
      "meta": {},
      "lookupKey": null,
      "currency": "usd",
      "provider": "bridge",
      "beneficiaryAddress": {
        "id": null,
        "line1": null,
        "line2": null,
        "city": null,
        "postalCode": null,
        "state": null,
        "country": null,
        "application": null
      },
      "walletBankAccounts": [],
      "mock": false,
      "accountType": "U2FsdGVkX1+IpNBUkepy6Nrv4vMD0x53oTJP7yFoKJs=",
      "updated": "2024-08-12T21:42:52.889Z",
      "created": "2024-08-12T21:41:30.188Z",
      "deleted": "2024-08-12T21:42:52.886Z"
    }
  },
  "ts": "2024-08-12T21:42:52.896Z",
  "request": "request_28e5a85abec74e0f8b4683f156b2b0de"
}

Was this page helpful?