> ## Documentation Index > Fetch the complete documentation index at: https://docs.synctera.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 multiple account types. * `SAVING` and `CHECKING` are Demand Deposit Accounts (DDA) and represent funds accrued by the account holder. * A `LINE_OF_CREDIT` account represents unsecured line of credit extended to the account holder. * A `CHARGE_SECURED` account represents secured non-revolving credit extended to the account holder, secured by a linked DDA. * A `CHARGE_UNSECURED `account represents an unsecured non-revolving credit extended to the account holder. * A `CREDIT_CARD` account represents a revolving line of credit for use with a credit card In addition to the various types of customer accounts, there are also: * `GENERAL_LEDGER` accounts - Internal GL accounts (settlement, reserve, P\&L, etc). These are created and managed by Synctera or the bank only and are not created directly by integrators in production. Other Important Concepts: * Internal Accounts - a set of pre-defined general ledger accounts linked to the FinTech, not individual customers. See the [Internal Account](https://docs.synctera.com/v2/reference/listinternalaccounts) API. * External Accounts: a link to an account outside the Synctera platform. See the [External Accounts](https://docs.synctera.com/v2/docs/external-accounts-guide) guide. ### Prerequisites This guide assumes that you have: 1. Created a [personal customer](/v2/docs/create-a-personal-customer) or [business customer](/v2/docs/create-a-business) 2. Created and recorded the required [disclosure](/v2/docs/record-disclosure-acceptance)s for the end customer, such as account agreements 3. [Verified a customer](/v2/docs/kyc-kyb-verification) by running KYC/KYB and obtaining the proper verification status In order to open an account and participate in money movement, all account holders, joint holders, and authorized signers are required to [undergo KYC or KYB verification](/v2/docs/kyc-kyb-verification) and have a `verification_status` of `ACCEPTED`. You should also have the following environment variables set, as described in **Need to Know**: * `baseurl` – points to the correct environment (sandbox or production). * `apikey` – API key for that environment. See: * [Need to Know – Environments](https://docs.synctera.com/v2/reference/need-to-know#environments) * [Need to Know – Authentication](https://docs.synctera.com/v2/reference/need-to-know#authentication) ### Customer Device Fingerprinting All Synctera API endpoints support **customer device fingerprinting** via the Customer-Device-Info HTTP header. For any request made **on behalf of an end-customer** (for example, opening an account from your mobile app), you should include this header with device telemetry: ```json theme={"system"} { "customer_id": "123e4567-e89b-12d3-a456-426614174000", "ip_address": "203.0.113.195", "device_type": "iOS", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1" } ``` For more details, see [Need to Know – Customer Device Fingerprinting](https://docs.synctera.com/v2/reference/need-to-know#customer-device-fingerprinting). ## Creating an Account This section will walk you through the creation of a basic 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](/v2/reference/need-to-know#environments) and [Authentication](/v2/reference/need-to-know#authentication) for instructions. Call [POST /v2/accounts](/v2/reference/createaccount) to create the account, linking to the existing customer. ```shell Shell theme={"system"} 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}" } ] }' ``` On success, the API will return a response with the created account, e.g.: ```json JSON theme={"system"} { "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" } ``` Once created, you can use this account with other APIs, e.g. * Cards - create a card on the account * Transaction rails your program supports (e.g. ACH, SyncteraPay, Internal Transfers, AFT/OCT, Wires, mRDC, etc) ### Account Relationships A customer can be related to an account in different ways: | relationship\_type | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PRIMARY\_ACCOUNT\_HOLDER | Required, must have one primary owner on the account. Requires an `ACCEPTED` verification status. | | JOINT\_ACCOUNT\_HOLDER | Joint owner with the same permissions as the Primary Account Holder. Requires an `ACCEPTED` verification status. | | AUTHORIZED\_SIGNER | The authorized signer is a person that can transact on the account but is not an account owner. Requires an `ACCEPTED` verification status. | | AUTHORIZED\_USER | The authorized user is a person that can only transact on the account. This person **does not** require an `ACCEPTED` verification status but an OFAC check will be completed by the platform using the customer's name and address. This means that you will not need to collect information typically used in KYC such as SSN, SIN, date of birth, but should collect name and address to minimize OFAC false positives. | You can create relationships inline when creating an account, or you can manage them separately using the [/v2/accounts/relationships](/v2/reference/createaccountrelationship) endpoints. The relationships should use the `customer_id` attribute if the account holder is a personal customer, and `business_id` if a business customer. Example: ```text theme={"system"} curl \ -X POST \ "$baseurl/v2/accounts/{ACCOUNT_ID}/relationships" \ -H "Authorization: Bearer $apikey" \ -H "Content-Type: application/json" \ --data-binary '{ "relationship_type": "JOINT_ACCOUNT_HOLDER", "customer_id": "{JOINT_CUSTOMER_ID}", "ownership_percentage": 50.0 }' ``` ### Status The account object contains two status attributes: * `access_status`: can be set to `FROZEN` to temporarily freeze an account. This is an operational access state. * `status` represents the lifecycle of the account. A FinTech can progress the account from `ACTIVE_OR_DISBURSED` to `IN_CLOSING` 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` . Accounts are transitioned to `CLOSED` by the system after account closure is initiated and all system checks pass (see below section) 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`. Account Statuses | **status** | **Description** | **Transactable** | | :------------------------ | :------------------------------------------------------------------------------- | :--------------- | | APPLICATION\_SUBMITTED | Deprecated application state. | N | | ACTIVE\_OR\_DISBURSED | Account is open and can transact. | Y | | ACCOUNT\_NEVER\_ACTIVE | Account was never activated. | N | | ACCOUNT\_NOT\_DESIRED | Credit account created but customer did not accept. | N | | ACTIVATED\_NOT\_DISBURSED | Credit account activated but funds not yet disbursed/used. | N | | FAILED\_KYC | We were unable to verify the account holder (failed KYC). | N | | RESTRICTED | Account holder has not successfully passed KYC; account is restricted. | N | | DELINQUENT | Credit account is delinquent (past due on required payments). | N | | SUSPENDED | Suspected fraudulent activity; blocked from further transactions. | N | | IN\_CLOSING | Account is in the process of being closed. Only allowed transition is to CLOSED. | N | | CLOSED | Account closed (balance must be zero). Cannot transact. | N | | CHARGED\_OFF | Charged‑off account (closed with loss). | N | | AWAITING\_FIXING | Account is awaiting remediation. | N | ### 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. * **balance\_floor** – defines a minimum balance and a linked overdraft account (if required). * **balance\_ceiling** – defines a maximum balance and an overflow account. Please see the [Balance Floor and Ceiling](https://docs.synctera.com/v2/docs/balance-floor-ceiling) guide for more details. ## 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. You can read balances via the **account GET** endpoints or via transaction queries. See the [Accounts API Reference](https://docs.synctera.com/v2/reference/getaccount). ## 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 (and, in v2 (alpha), fees via dedicated fee products). 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](/v2/docs/interest-guide). Using an account product is optional. If no account product is specified when creating the account, no interest will be calculated. It is not currently possible to change the account product on an account. To create an interest product\_type, use [POST /v0/accounts/products](/v2/reference/createaccountresourceproduct) with `product_type = "INTEREST"`. Example: ```shell Shell theme={"system"} 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.: ```json JSON theme={"system"} { "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 and referenced as `interest_product_id` on templates and accounts. ### Account Templates Account templates contain predefined values for creating an account. When creating an account, 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 /v2accounts/templates](/v2/reference/createaccounttemplate). All account creation uses an account template. As a convenience, the `account_template_id` does not need to be specified if there is 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. You can override template values in the `POST /v0/accounts` request when creating an account. However, the account type in the template and the `POST` request must agree. To create an account template, specify the type of account (`CHECKING`, `SAVING`, `LINE_OF_CREDIT` or `CHARGE_SECURED`), 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. Key Notes: * **Rails flags**: `is_ach_enabled`, `is_card_enabled`, `is_eft_ca_enabled`, `is_external_card_enabled`, `is_p2p_enabled`, `is_synctera_pay_enabled`, `is_wire_enabled` determine which payment rails are allowed and are enforced both via APIs and console operations. * `interest_product_id` is optional. If omitted, no interest is calculated for accounts using this template. * `spend_control_id` on templates/accounts should be used for spending limits; spending\_limits is deprecated. See the [Spend Controls guide](https://docs.synctera.com/v2/docs/spend-controls-guide). * `balance_floor` and `balance_ceiling` are optional attributes that can also be set on the account template level. Example Template Creation: ```shell Shell theme={"system"} 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 } }' ``` This will return a response with the created account template, e.g.: ```json JSON theme={"system"} { "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 } } ``` Note the returned `id` attribute. This is used for when creating an account. ## 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](/v2/reference/initiateaccountclosure) 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 closure is initiated - Synctera will: * Check for active disputes and pending transactions, and pause on closure until resolution * Stop further transactions, except for certain allowed scenarios (authorized payments, refunds, etc.) * Deactivate cards and tokens. * End recurring transactions. * Write off negative balances and handle other closure‑related behaviors. * Payout any interest due to the customer. * Transfer remaining funds to a specified destination account. If the destination account is an external account via ACH, the system will wait on a 2 day return window to ensure payout settles to avoid returns to a closed account before closing ### Integrating with Account Closure: The following curl example will walk you through integrating with Synctera’s account closure functionality, via the [Initiate Closure](/v2/reference/initiateaccountclosure) API. This assumes you have set up baseurl and apikey environment variables. See [Base URL](/v2/reference/need-to-know#environments) and [Authentication](/v2/reference/need-to-know#authentication) for instructions. Closing an account requires the following integrations: 1. Integrate with Synctera’s [Initiate Closure](/v2/reference/initiateaccountclosure) 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. 2. Subscribe to the [Account.UPDATED](/v2/docs/webhooks-guide) webhook: This webhook will transmit updates on the status of the account. Once all system checks pass, 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](/v2/reference/initiateaccountclosure) request: Call [POST/v2/accounts/](/v2/reference/initiateaccountclosure){account_id}[/initiate\_closure](/v2/reference/initiateaccountclosure) to close the account. ```shell Shell theme={"system"} 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](/v2/reference/initiateaccountclosure) response: ```shell Shell theme={"system"} { "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" } ``` **Updating an Account Closure** An account may require an update to the `payment_method` after the closure initiation has already been completed. Integrators can now PATCH the account closure with the new `payment_method` and `destination_id` details if necessary by using the [PATCH /v2/accounts/account\_id/initiate\_closure](https://docs.synctera.com/v2/reference/updateaccountclosure) endpoint. Please see the [webhooks guide](/v2/docs/webhooks-guide) for further details on subscribing to the ACCOUNT.UPDATED webhook. ### Account Closure FAQs 1. **Will we be able to transfer the funds in multiple payments?** \ Yes. We are able to transfer the funds in multiple payments. 2. **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. 3. **What happens if there is a return / refund after the account is closed?** \ Synctera will work with your Sponsor Bank to send a check to the last known address for any funds that come in after the account is closed or follow the bank process. 4. **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. 5. **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. 6. **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. 7. **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.