Skip to main content

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.

​
Overview

In Synctera’s platform, spend controls are independent entities that must be associated with another entity (currently, an account) to take effect. A spend control defines:
  • What to monitor – time window, payment types (for example, CARD, ACH, WIRE, CASH), merchant category codes (MCCs), direction (DEBITS or CREDITS).
  • How much – amount_limit over that window.
  • What to do if violated – decline the transaction (where possible) and/or create a Case in Synctera’s case management system.
  • Webhooks sent to the nominated FinTech endpoint will be sent each time
Key characteristics:
  • Many-to-many – a spend control can apply to multiple accounts, and an account can have multiple spend controls.
  • Direction-specific – each spend control applies to either DEBITS or CREDITS; debits and credits do not offset each other for spend-control purposes.
  • Rail-agnostic – payment types cover card, ACH, wires, cash, and other movement rails; spend controls can be used for debit, credit, and Synctera Pay / external card flows via the appropriate payment types.
Spending Controls can apply to customers, accounts, and cards. This includes both deposit accounts (CHECKING/SAVING/PREPAID) and credit accounts (for example, LINE_OF_CREDIT, CHARGE_SECURED, CHARGE_UNSECURED, REVOLVING credit accounts).

​
Managing Spend Controls

You manage spend controls with the Spend Controls API:
  • Create – POST /v2/spend_controls
  • Get – GET /v2/spend_controls/
  • Update – PATCH /v2/spend_controls/
  • List – GET /v2/spend_controls
See the Spend Controls API reference for full request and response schemas.

​
Creating a Spend Control

To create a spend control, use POST /v2/spend_controls. For example, to create a limit of $1,000.00 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 $1,000.00 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 $25,000.00 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.00 of ACH and $15,000.00 of wire spending then the rule would take effect and a case would be created. The $25,000.00 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.00 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 $1,000.00 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.00 of spending with Merchant Category Code 6012 and subsequently $750.00 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 /v2/spend_controls/: 
{
  "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 /v2/spend_controls/. 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
  }
}

​
List Spend Controls

To list spend controls, use GET /v2/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 /v2/accounts and include the spend control ID in the spend_control_ids query parameter.

​
Create an Account with Spend Controls

To create an account with a spend control, use POST /v2/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 /v2/accounts/. For example, to have the account use two spend controls: 
{
  "spend_control_ids": [
    "ad7495c3-82d0-482d-b1e4-f0cbab6e039c",
    "41d6ab10-73b3-4b82-9e75-a4981b35edfb"
  ]
}
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.
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.