Overview

Spend controls provide a way to monitor the flow of money. In Synctera's platform, spend controls are independent entities that must be associated with another entity (such as an account) to take effect. Spend controls define rules based on time range, payment type, merchant category code and the amount of money that may be spent as well as what to do if the rule is violated. Spend controls can have a many-to-many relationship with another entities (eg. accounts). A spend control may apply to multiple accounts and an account may have multiple spend controls that apply to it.

Currently, only accounts can use spend controls.

Spend controls track the flow of money out of the account (debits) or into the account (credits) but each spend control applies to one direction only. In other words, debits and credits do not offset each other for the purposes of spend controls.

Originally, spend controls applied to debits only. We added support for credits but retained the name "spend controls". The default option for a spend control is to track debits.

Managing Spend Controls

Creating a Spend Control

To create a spend control, use POST /v0/spend_controls.

For example, to create a limit of $1000 in card spending over the last seven days:

{
  "name": "One thousand dollars weekly card limit",
  "amount_limit": 100000,
  "time_range": {
    "time_range_type": "ROLLING_WINDOW_DAYS",
    "days": 7
  },
  "payment_types": [
    "CARD"
  ],
  "action_decline": true,
  "action_case": false,
  "is_active": true
}

The amount_limit uses the smallest currency unit (eg. cents).

The time_range field can be a rolling window defined by a number of days, as in the example above, or defined as a single transaction. For example, to create a limit of $1000 per card transaction:

{
  "name": "One thousand dollars per transaction limit",
  "amount_limit": 100000,
  "time_range": {
    "time_range_type": "SINGLE_TRANSACTION",
  },
  "payment_types": [
    "CARD"
  ],
  "action_decline": true,
  "action_case": false,
  "is_active": true
}

The action_decline and action_case fields specify what will happen for a transaction that would exceed the spend control's limit. If action_case is set then a case will be created in Synctera's case management system for any transaction that would exceed the spend control's limit. If action_decline is set then the transaction will be declined if possible. Some transactions are forced, because they represent money movement that has already occurred outside of Synctera's platform. In such cases, if the transaction were to exceed the spend control's limit the transaction will not be declined but instead a case will be created, regardless of the action_case setting. At least one of action_decline and action_case must be set. To completely disable the spend control set is_active to false.

You may omit the payment_types field. In that case, the spend control applies to all payment types.

You may specify multiple payment types. This means that all the specified payment types count toward the limit. For example, to create a rule that creates a case if there is more than $25000 in combined ACH and wire spending over the last thirty days:

{
  "name": "25 thousand ACH and wire",
  "amount_limit": 2500000,
  "time_range": {
    "time_range_type": "ROLLING_WINDOW_DAYS",
    "days": 30
  },
  "payment_types": [
    "ACH",
    "WIRE"
  ],
  "action_decline": false,
  "action_case": true,
  "is_active": true
}

In this example the spending is counted for the entire rule. So if there were $15,000 of ACH spending and $15,000 of wire spending then the rule would take effect and a case would be created. The $25,000 limit is for ACH and wire spending combined. If you want the payment types to be counted separately, create separate spend controls, one for each payment type.

You may specify the direction of money movement to which the spend control applies. The options are DEBITS or CREDITS. For example, to create a rule that triggers a case if an account receives more than $10,000 in cash deposits in the last seven days:

{
  "name": "seven day cash warning",
  "amount_limit": 1000000,
  "time_range": {
    "time_range_type": "ROLLING_WINDOW_DAYS",
    "days": 7
  },
  "payment_types": [
    "CASH"
  ],
  "action_decline": false,
  "action_case": true,
  "is_active": true,
  "direction": "CREDITS"
}

You may specify merchant_category_codes to which the spend control applies. Specifying merchant category codes only works with card transactions. The options for merchant_category_codes include individual codes or ranges of codes. For example, to create a weekly limit of $1000 with merchant category code 6012 or in the range of merchant category codes 7300–7999:

{
  "name": "One thousand dollars weekly card limit for MCCs 6012, 7300–7999",
  "amount_limit": 100000,
  "time_range": {
    "time_range_type": "ROLLING_WINDOW_DAYS",
    "days": 7
  },
  "payment_types": [
    "CARD"
  ],
  "action_decline": true,
  "action_case": false,
  "is_active": true,
  "merchant_category_codes": [
    "6012",
    "7300–7999"
  ]
}

In this example, the spending is counted for the entire rule. So if there were $750 of spending with merchant category code 6012 and subsequently $750 of spending with merchant category code 7375, the rule would take effect. If you want the merchant_category_codes to be counted separately, create separate spend controls for each merchant category code or range of merchant category codes.

Spend Control Response

The API responses from the spend control endpoints include the details of the spend control, including the UUID in the id field and the number of accounts that are using the spend control in the number_of_related_accounts field (which will be zero for newly-created spend controls). To check the status of a specific spend control by its UUID, use GET /v0/spend_controls/{id}:

{
  "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
  "name": "One thousand dollars weekly card limit",
  "amount_limit": 100000,
  "time_range": {
    "time_range_type": "ROLLING_WINDOW_DAYS",
    "days": 7
  },
  "payment_types": [
    "CARD"
  ],
  "action_decline": true,
  "action_case": false,
  "is_active": true,
  "creation_time": "2022-03-24T12:59:06.756Z",
  "last_modified_time": "2022-03-24T12:59:06.756Z",
  "number_of_related_accounts": 0,
  "direction": "DEBITS",
  "merchant_category_codes": [
    "6012",
    "7300–7999"
  ]
}

Updating a Spend Control

To update a spend control, use PATCH /v0/spend_controls/{id}.

This request will disable a spend control:

{
  "is_active": false
}

This request will set a new time range and amount limit:

{
  "amount_limit": 75000,
  "time_range": {
    "time_range_type": "ROLLING_WINDOW_DAYS",
    "days": 14
  }
}

⚠️

Caution

Updating a spend control will affect all accounts that use that spend control. You can check how many accounts will be affected by checking the number_of_related_accounts field in the spend control response. To get details about the accounts, use GET /v0/accounts and include the spend control ID in the spend_control_ids query parameter. If the spend control is used by multiple accounts and you want to change the spend control rules for just one of those accounts you must create a new spend control and then update the account to use the new spend control and not the old spend control.

List Spend Controls

To list spend controls, use GET /v0/send_controls. Using query parameters. you can filter by limit amount (range), payment type, number of related accounts (range), specific related account ID and name.

List Accounts that use a Spend Control

To list all accounts that use a spend control, use GET /v0/accounts and include the spend control ID in the spend_control_ids query parameter.

Link Spend Controls to Accounts

Create an Account with Spend Controls

To create an account with a spend control, use POST /v0/accounts with the optional field spend_controls_ids. For example:

{
  "account_template_id": "e14182d8-130c-4fa4-bcac-9b3df1537247",
  "relationships": [
    {
      "person_id": "23ec211e-7c3e-4ead-b340-c5cab70257a2",
      "relationship_type": "ACCOUNT_HOLDER"
    }
  ],
  "spend_control_ids": [
    "b9c7da4e-8220-4044-86a0-f91a592002a5"
  ]
}

You may specify as many as ten spend_control_ids. Each spend control applies to the account independent of the other spend controls on the account and independent of other accounts that may use the same spend controls.

Update an Account's Spend Controls

To change the spend controls for an account, use PATCH /v0/accounts/{id}. For example, to have the account use two spend controls:

{
  "spend_control_ids": [
    "ad7495c3-82d0-482d-b1e4-f0cbab6e039c",
    "41d6ab10-73b3-4b82-9e75-a4981b35edfb"
  ]
}

⚠️

Caution

When updating the list of spend_control_ids for an account, the entire list is replaced. The list is not appended. Old values are dropped. So if you want to add a new spend controls to an account with existing spend controls make sure your update request includes both the old spend controls and the new ones.

To remove spend controls from an account use an explicitly-empty JSON array.

{
  "spend_control_ids": []
}

Using Account Templates

Account templates may contain spend control IDs. As with other account template fields, these spend control IDs will be the default for any account created using the template but during account creation you can over-ride the template's default.

⚠️

Caution

If you create an account from a template which contains a list of spend_control_ids and specify your own list of spend_control_ids then the two lists are not combined. The list will be whatever you specify in the account creation request.

Spend Monitoring Cases

When spend controls are violated they may create a case in Synctera's case system. If the spend control has action_case set, or if the spend control has action_decline set and the transaction is forced, then there will be a case based on that specific account and spend control. Multiple accounts using the same spend control will have separate cases if multiple accounts violate the spend control. Multiple spend controls on the same account will have separate cases if multiple of the spend controls are violated.

Multiple violations of a specific spend control for a specific account will combine into the same case as long as the case remains open. Any additional violations will be reflected in violation count of the case. If the case is closed and the account violates the spend control again then a new case will be created.