In the Synctera platform, an account represents a bank account of your business or personal customer. This guide explains how to create and use accounts.

Types of Accounts

There are three types of accounts. SAVING and CHECKING are Demand Deposit Accounts (DDA) and represent funds accrued by the account holder. A LINE_OF_CREDIT account represents credit extended to the account holder.

In addition to the three types of customer accounts, there are also:

  • Internal Accounts: a set of pre-defined general ledger accounts linked to the FinTech, not individual customers. See the Internal Account API.
  • External Accounts: a link to an account outside the Synctera platform. See the External Accounts guide.

Steps to Create an Account

The following steps will walk you through the creation of an account and getting it ready to use with other features such Cards and ACH.

The curl examples assume you have set up baseurl and apikey environment variables. See Base URL and Authentication for instructions. Some examples depend on identifiers generated by previous steps. These are indicated like {CUSTOMER_ID}.

1. Create Account Products

An account product is a set of attributes that define how interest is calculate for accounts. The account product resource acts as a profile that can apply to multiple accounts. Changes to the account product affects all accounts that reference it. Only interest-bearing accounts need to reference an account product. Details about interest calculation can be found here in the Interest Guide

Using an account product is optional. If no account product is specified when creating the account, no interest will be calculated.

The v0 API spec also includes a preview of fee product types. This product type is not yet supported - account fees will be implemented in the future.

To create an interest product_type, use POST /v0/accounts/products. Specify how you want the interest calculated (e.g. COMPOUNDED_MONTHLY), accured (e.g. DAILY) and paid (e.g. MONTHLY). You can specify that the interest rate varies over time by including multiple periods with different rates. The rate is specified using basis points (bps), i.e. 125 represents 1.25%.

curl \
  -X POST \
  $baseurl/v0/accounts/products \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '
    {
      "product_type": "INTEREST",
      "description": "Sample interest request body",
      "calculation_method": "COMPOUNDED_MONTHLY",
      "accrual_payout_schedule": "MONTHLY",
      "rates": [
        {
          "valid_from": "2021-06-15",
          "rate": 100,
          "accrual_period": "DAILY"
        },
        {
          "valid_from": "2021-06-01",
          "valid_to": "2021-06-15",
          "rate": 100,
          "accrual_period": "DAILY"
        }
      ]
    }'

This will return a response with the created account product, e.g.:

{
  "accrual_payout_schedule": "MONTHLY",
  "calculation_method": "COMPOUNDED_MONTHLY",
  "description": "Sample interest request body",
  "id": "52c80838-90b3-4afb-b3ff-98a97b5df96b",
  "product_type": "INTEREST",
  "rates": [
    {
      "accrual_period": "DAILY",
      "rate": 100,
      "valid_from": "2021-06-01",
      "valid_to": "2021-06-15"
    },
    {
      "accrual_period": "DAILY",
      "rate": 100,
      "valid_from": "2021-06-15"
    }
  ]
}

Note the returned id attribute. This is used for the next request to create an account template.

2. Create Account Templates

Account templates contain predefined values for creating an account. When creating an account with a template ID, the Accounts API copies all the template values to the account resource. Once you create an account, the API no longer references the template used to create it, and updates won’t affect existing accounts. To create an account template, call POST /v0/accounts/templates.

Specify the type of account (CHECKING, SAVING or LINE_OF_CREDIT), and the attributes for that type. The is_enabled attribute must be set to true to use this template when creating an account. This example will use a SAVING account.

Note the is_ach_enabled, is_card_enabled and is_p2p_enabled attributes. Synctera will enforce these controls as money movement requests could be generated both via the API and by your ops team on apps.synctera.com.

curl \
  -X POST \
  $baseurl/v0/accounts/templates \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '
    {
      "name": "sample template",
      "description": "Sample account template",
      "is_enabled": true,
      "template": {
        "account_type": "SAVING",
        "bank_country": "US",
        "currency": "USD",
        "is_ach_enabled": true,
        "is_card_enabled": true,
        "is_p2p_enabled": true,
        "interest_product_id": "{ACCOUNT_PRODUCT_ID}",
        "overdraft_limit": 0,
        "spending_limits": {
          "day": {
            "amount": 111
          }
        }
      }
    }'

This will return a response with the created account template, e.g.:

{
  "description": "Sample account template",
  "id": "{ACCOUNT_TEMPLATE_ID}",
  "is_enabled": true,
  "name": "sample template",
  "template": {
    "account_type": "SAVING",
    "bank_country": "US",
    "currency": "USD",
    "interest_product_id": "{ACCOUNT_PRODUCT_ID}",
    "is_ach_enabled": true,
    "is_card_enabled": true,
    "is_p2p_enabled": true,
    "overdraft_limit": 0,
    "spending_limits": {
      "day": {
        "amount": 111
      }
    }
  }
}

Note the returned id attribute. This is used for the next request to create an account.

Additional details:

  • interest_product_id is optional, and if specified, should be a valid ID for an account product resource.
  • spending_limits is optional. This will limit the amount of spending on a lifetime, monthly, weekly or transaction basis.
  • balance_floor and balance_ceiling are optional attributes that control what happens when a transaction would bring the account balance below or above a set amount. This can be used to implement overdraft protection and sweep accounts. Please see the Balance Floor and Ceiling guide.

3. Create an account

Next, create the account itself. This assumes you have a business or personal customer, see the Create a Personal Customer guide. Call POST /v0/accounts to create the account, linking to the existing customer and account template.

The relationships link the account to customers:

relationship_typeDescription
PRIMARY_ACCOUNT_HOLDERRequired, only 1 allowed
ACCOUNT_HOLDERDeprecated alias for PRIMARY_ACCOUNT_HOLDER
JOINT_ACCOUNT_HOLDERFor joint accounts, specifies the secondary account holders
AUTHORIZED_SIGNERFor accounts linked to cards, specifies the card holder, e.g. when the PRIMARY_ACCOUNT_HOLDER is a business and the AUTHORIZED_SIGNER is the employee card holder

The relationships should use the customer_id attribute if the account holder is a personal customer, and business_id if a business customer.

curl \
  -X POST \
  $baseurl/v0/accounts \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '
    {
      "account_template_id": "{ACCOUNT_TEMPLATE_ID}",
      "account_purpose": "Retirement",
      "account_nickname": "retirement",
      "relationships": [
        {
          "relationship_type": "PRIMARY_ACCOUNT_HOLDER",
          "customer_id": "{CUSTOMER_ID}"
        }
      ]
    }'

This will return a response with the created account, e.g.:

{
  "access_status": "ACTIVE",
  "account_number": "108819201708",
  "account_purpose": "Retirement",
  "account_type": "SAVING",
  "balances": [
    {
      "balance": 0,
      "type": "ACCOUNT_BALANCE"
    },
    {
      "balance": 0,
      "type": "AVAILABLE_BALANCE"
    }
  ],
  "bank_routing": "463138043",
  "creation_time": "2022-05-20T21:24:25.771993Z",
  "currency": "USD",
  "customer_type": "PERSONAL",
  "id": "15e88b14-5b1b-4ea6-9182-aea3d7c7e086",
  "interest_product_id": "52c80838-90b3-4afb-b3ff-98a97b5df96b",
  "is_account_pool": false,
  "is_ach_enabled": true,
  "is_card_enabled": true,
  "is_p2p_enabled": true,
  "is_wire_enabled": false,
  "last_updated_time": "2022-05-20T21:24:25.771993Z",
  "overdraft_limit": 0,
  "spending_limits": {
    "day": {
      "amount": 111
    }
  },
  "status": "ACTIVE_OR_DISBURSED"
}

Additional details

  • The account status depends on the status and verification_status of the account holders (but not the authorized signers)
  • You can add/update/delete the relationships using the /v0/accounts/relationships` endpoints.
  • The account response body includes the read-only balances, see below for details
  • balance_floor and balance_ceiling are optional attributes that control what happens when the account balance goes below or above a set level. This can be used to implement overdraft protection and sweep accounts. Please see the Balance Floor and Ceiling guide.

Balances

Accounts have two types of balances: ACCOUNT_BALANCE and AVAILABLE_BALANCE.

For SAVING and CHECKING accounts:

  • ACCOUNT_BALANCE: the amount of money in the account. Equal to the sum of credits minus debits for all posted transactions.
  • AVAILABLE_BALANCE: the account balance minus any pending debits.

For LINE_OF_CREDIT accounts:

  • ACCOUNT_BALANCE: the amount of credit currently in use. Equal to the sum of debits minus credits for all posted transactions.
  • AVAILABLE_BALANCE: the amount of credit available. Equal to the credit limit minus account_balance minus any pending debits.

Did this page help you?