Accounts

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

Synctera supports four types of accounts:

CHECKING and SAVING accounts are Demand Deposit Accounts (DDA), and hold funds deposited by the account holder.
A LINE_OF_CREDIT account represents unsecured credit extended to the account holder.
A CHARGE_SECURED account is a secured credit account. For a Synctera Smart card, this is secured by another DDA.

In addition to the four 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.

Creating an Account

🚧
Our guides mostly refer to V1 routes; however, when creating accounts, please refer to V0 specifications. We're hard at work bringing our entire specification to V1.

The following curl example will walk you through the creation of an account and getting it ready to use with other features such Cards and ACH. This assumes you have set up baseurl and apikey environment variables. See Base URL and Authentication for instructions.

If you don't already have a business or personal customer, create one now. Replace the {CUSTOMER_ID} with the customer's id.

Call POST /v0/accounts to create the account, linking to the existing customer.

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

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

{
  "access_status": "ACTIVE",
  "access_status_last_updated_time": "2022-10-06T14:03:54.962704Z",
  "account_number": "790954299503",
  "account_number_masked": "790*****9503",
  "account_type": "SAVING",
  "balances": [
    {
      "balance": 0,
      "type": "ACCOUNT_BALANCE"
    },
    {
      "balance": 0,
      "type": "AVAILABLE_BALANCE"
    }
  ],
  "bank_routing": "112233445",
  "creation_time": "2022-10-06T14:03:54.963162Z",
  "currency": "USD",
  "customer_ids": [
    "110acc45-0b53-4d21-b624-29f88879c6a0"
  ],
  "customer_type": "PERSONAL",
  "id": "ce439ca4-8eb6-45e6-955c-46441af33770",
  "is_account_pool": false,
  "is_ach_enabled": false,
  "is_card_enabled": false,
  "is_p2p_enabled": false,
  "is_wire_enabled": false,
  "last_updated_time": "2022-10-06T14:03:54.963162Z",
  "status": "ACTIVE_OR_DISBURSED"
}

Account Relationships

A customer can be related to an account in different ways:

relationship_type	Description
PRIMARY_ACCOUNT_HOLDER	Required, only 1 allowed
ACCOUNT_HOLDER	Deprecated alias for PRIMARY_ACCOUNT_HOLDER
JOINT_ACCOUNT_HOLDER	For joint accounts, specifies the secondary account holders
AUTHORIZED_SIGNER	For 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

You can add/update/delete these relationships using the Account Relationships API.

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

Status

The account object contains two status attributes:

access_status: can be set to FROZEN to temporarily freeze an account.
status represents the lifecycle of the account. A FinTech can progress the account from APPLICATION_SUBMITTED to ACTIVE_OR_DISBURSED to IN_CLOSING to CLOSED if the balance of the account is zero. The Synctera platform also updates this attribute, e.g. setting it to RESTRICTED when the account holder has not been verified. Note that authorized signers do not need to be verified.
An account with a status of IN_CLOSING is only allowed to transition to CLOSED. Account status update to any other status from IN_CLOSING is not allowed.

To participate in money movement transactions, issue cards, etc, the account must have an access_status of ACTIVE and a status of ACTIVE_OR_DISBURSED.

Balance Floor and Ceiling

The optional balance_floor and balance_ceiling attributes control what happens when the account balance goes below or above a set level. This can be used to implement 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 and CHARGE_SECURED 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. For LINE_OF_CREDIT, this is equal to the credit limit minus ACCOUNT_BALANCE minus any pending debits. For CHARGE_SECURED, this is the available balance of the security account.

Account Products and Templates

Synctera supports the concepts of Account Products and Account Templates to so you don't need to specify all the details when creating similar accounts.

Account Products

An account product is a set of attributes that define how interest is calculated 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 when creating an account template.

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.

Specifying an account template when creating an account is optional. If one isn't specified, there must be a single account template that matches the requested account's type. As part of initial the FinTech setup, a simple account template for each account type is automatically created.

Specify the type of account (for example, CHECKING), 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 when creating 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 sweep accounts. Please see the Balance Floor and Ceiling guide.

Closing an Account

As end customers unenroll from a fintech’s service, their accounts with Synctera will need to be closed. Synctera’s Initiate Closure API allows fintechs to close a customer account as well as all products in use by the customer and ensure all underlying transactions are handled appropriately, with just one API call. Once the call is placed - Synctera will payout any interest that is due to the customer and transfer the funds to a destination. Additionally, Synctera will deactivate cards and tokens, end recurring transactions, write off negative balances and handle many other use cases. Any future transactions will not be allowed except for authorized payments and refunds, and interest will stop accruing.

Integrating with Account Closure:

The following curl example will walk you through integrating with Synctera’s account closure functionality, via the Initiate Closure API. This assumes you have set up baseurl and apikey environment variables. See Base URL and Authentication for instructions.

Closing an account requires the following integrations:

Integrate with Synctera’s Initiate Closure API: This API call will start the closure process and the customer account’s status will be set to IN_CLOSING. The fintech will have to provide a destination account for customer funds to be transferred to.
Subscribe to the Account.UPDATED webhook: This webhook will transmit updates on the status of the account. Once any underlying transactions have completed and any products in use have been deactivated, the customer’s account will be set to a status of CLOSED.

The following example illustrates how to format an Initiate Closure request:

Call POST/v0/accounts/{account_id}/initiate_closure to close the account.

curl \
  -X POST \
  $baseurl/v0/accounts/{$ACCOUNT_ID}/initiate_closure \
  -H "Idempotency-Key $IDEMPOTENCY_KEY" \
  -H "Authorization: Bearer $apikey" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary '
    {
      "destination_id": "ebdc0c82-3dae-4a85-b941-7bb9f0abd829",
      "payment_method": "ACH",
      "reason": “CUSTOMER_REQUEST_TRANSFER”,
      "reason_details": “End customer is moving off our service ”,
   }’

The following example illustrates the format of an Initiate Closure response:

{
  "access_status": "ACTIVE",
  "access_status_last_updated_time": "2024-08-20T22:24:46.722385Z",
  "account_closure": {
    "case_ids": [],
    "destination_id": "ebdc0c82-3dae-4a85-b941-7bb9f0abd829",
    "payment_method": "ACH",
    "reason": "CUSTOMER_REQUEST_TRANSFER",
    "reason_details": "End customer is moving off our service",
    "validation_responses": []
  },
  "account_number": "203749521694",
  "account_purpose": "Demo account",
  "account_type": "CHECKING",
  "bank_account_id": "i7bc9089-3f5g-1cb0-a533-d19364fd2263",
  "bank_routing": "931937896",
  "creation_time": "2024-08-20T22:24:46.691379Z",
  "currency": "USD",
  "customer_type": "PERSONAL",
  "id": "a4cad06c-0b28-42ea-bcd7-dead9373b82d",
  "is_account_pool": false,
  "is_ach_enabled": true,
  "is_card_enabled": false,
  "is_eft_ca_enabled": false,
  "is_external_card_enabled": false,
  "is_p2p_enabled": true,
  "is_sar_enabled": false,
  "is_security": false,
  "is_synctera_pay_enabled": false,
  "is_wire_enabled": false,
  "last_updated_time": "2024-08-20T22:47:57.323435Z",
  "nickname": "ACCOUNT CLOSURE DEMO ACCOUNT",
  "open_date": "2024-08-20",
  "status": "IN_CLOSING",
  "tenant": "wrelqwerb_yhqwrkrp"
}

Please see the webhooks guide for further details on subscribing to the ACCOUNT.UPDATED webhook.

Account Closure FAQ’s

Will we be able to transfer the funds in multiple payments? Yes. We are able to transfer the funds in multiple payments.
Will the balance transfer happen immediately? If there are no transactions on hold and no pending transactions, then the transfer will happen immediately after the Initiate Closure API was called. If there are transactions on hold or pending transactions, then the transfer will occur after these clear and the account will be closed.
What happens if there is a return / refund after the account is closed? Synctera will manually send a check to the last known address for any funds that come in after the account is closed.
Can customers still raise a dispute after the account is closed? Yes, customers can raise a dispute after the account is closed. For card transactions, disputes can be filed up to 60 days from the statement date of the transaction in question. For ACH transactions, disputes can be raised up to 60 days from the settlement date of the transaction in question. If the investigation results in a chargeback, Synctera will manually send a check to the last known address for the transaction amount.
Will a statement be issued after the account is closed? Yes a statement will be issued at the end of the month, even after the account is closed. Smart cards will remain IN_CLOSING, until the customer pays off the balance listed in the statement generated at the end of the month.
Are there any controls to ensure that the funds are sent to a valid recipient? Although we enforce industry standard fraud controls in our platform, we do not verify that the recipient is valid. We encourage the fintech to verify the recipient is valid, using its own data and or third party platforms.
If you close an account without any underlying pending transactions or anything else that needs to be closed - how long until you receive the ‘closed’ webhook event? You will receive it the next business day.