Restrictions & Limits

Following your Card Program and your agreement with Treezor, you can configure the issued cards with options, restrictions, and limits to best suit your use case.

Options & Permission groups

Card options refer to how a given card can be used. They are preset at the Card Program level with the dedicated permsGroup attribute.

The following features are available to the cardholders if authorized at the Card Program level and activated in your Card object:

You can customize each option on a card-by-card basis, as long as you keep in mind that:

You can’t bypass options blocked by your Card Program.
Updating the card options automatically updates the permission group value.

Permission groups (`permsGroup`)

Below is the list of permission group values along with the options they enable.

`permsGroup`	NFC	ATM	Online	Foreign
`TRZ-CU-001`
`TRZ-CU-002`
`TRZ-CU-003`
`TRZ-CU-004`
`TRZ-CU-005`
`TRZ-CU-006`
`TRZ-CU-007`
`TRZ-CU-008`
`TRZ-CU-009`
`TRZ-CU-010`
`TRZ-CU-011`
`TRZ-CU-012`
`TRZ-CU-013`
`TRZ-CU-014`
`TRZ-CU-015`
`TRZ-CU-016`

Update card options

Regardless of the card type (virtual or physical), all options must be specified. This aims to smoothly handle the conversion of the card to physical if need be.

Parameters

The following parameters are required (1 for enabled, 0 for disabled).

Attribute	Type	Description
`atm`	integer	Defines whether the card can be used for ATM withdrawals.
`online`	integer	Defines whether the card can be used for online payments (this also applies to Mail Order, Telephone Order payments).
`nfc`	integer	Defines whether the card can be used for contactless payments (NFC).
`foreign`	integer	Defines whether the card can be used outside of the cardholder's country.

Request

Use the following request to update the card options.

CURL

bash

curl -X PUT {baseUrl}/v1/cards/{cardId}/Options \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

json

{
	"atm":1,
	"online":1,
	"nfc":1,
	"foreign":0
}

Returns the Card object, with the updated options and permsGroup:

JSON

json

{
	"cardId": integer,
	"userId": integer,
	"walletId": integer,
	"publicToken": "string",
	"statusCode": "string",	
	"isLive": integer,
	"permsGroup": "TRZ-CU-015",
    "cardDesign": "string",
    "virtualConverted": integer,
    "physical": integer,
	"optionAtm": 1,				
	"optionForeign": 0,			
	"optionOnline": 1,			
	"optionNfc": 1,			
	// [...] some attributes are hidden
}

Treezor also sends a card.options webhook.

Payment & Withdrawal limits

Card limits are configurable maximum payment and withdrawal amounts enforced by Treezor servers. They can therefore be updated at any time while abiding by your agreement with Treezor.

Limit rules and functionalities

Limits can be defined when creating the card, or later on using the dedicated endpoint.

When creating a card, you must define at least one limitPayment{period} and one limitAtm{period}. Limits that you don't specify automaticaly default to the values set by your Treezor Account Manager.

Payment limits

Attribute	Type	Description
`limitPaymentAll`	integer	Lifetime payment limit
`limitPaymentYear`	integer	Yearly payment limit
`limitPaymentMonth`	integer	Monthly payment limit
`limitPaymentWeek`	integer	Weekly payment limit
`limitPaymentDay`	integer	Daily payment limit

Withdrawal limits

Attribute	Type	Description
`limitAtmAll`	integer	Lifetime withdrawal limit
`limitAtmYear`	integer	Yearly withdrawal limit
`limitAtmMonth`	integer	Monthly withdrawal limit
`limitAtmWeek`	integer	Weekly withdrawal limit
`limitAtmDay`	integer	Daily withdrawal limit

Limits are based on Paris timezone by default.

Meaning that daily limits may not be obvious to your end users if they live under a different timezone.

You can disable entirely a specific limit.

To do so, set its value to 0, but at least one of the following values must be greater than 0: limitPaymentDay, paymentDailyLimit, limitPaymentWeek, limitPaymentMonth. The same applies for ATM limits (one of limitAtmMonth, limitAtmWeek or limitAtmDay must be greater than 0).

No consistency checks are made between each period limits.

The API allows you to define a higher daily than weekly limit, in which case, the lower of the two takes over. Consistency checks should be enforced by your application to avoid confusing end users.

Prefer the use of limitPaymentDay.

To set the daily payment limit, only one of the 2 following fields should be populated.

Attribute	Type	Usage
`paymentDailyLimit`	number	The option dedicated to food vouchers use cases. This is the only limit based on the cardholder's timezone, which can be changed using the `timezone` attribute of the User.
`limitPaymentDay`	integer	The preferred option, applicable to all other use cases.

Limits are sliding limits.

For example, to evaluate a monthly limit for a transaction made February 15^th, Treezor considers all transactions from January 15th (excluded) until February 15^th (included).

Update limits

To update the card limits, you can use the following request with the cardId as a path parameter.

Default limits may come with your Card Program, so fill in all the limits while making sure that you:

Set all values you don't need to 0 to deactivate them
Set at least one limitPayment{period} and one limitAtm{period} limit to another value than 0

Attribute	Type	Description
`limitPaymentAll`	integer	Lifetime payment limit
`limitPaymentYear`	integer	Yearly payment limit
`limitPaymentMonth`	integer	Monthly payment limit
`limitPaymentWeek`	integer	Weekly payment limit
`limitPaymentDay`	integer	Daily payment limit
`limitAtmAll`	integer	Lifetime withdrawal limit
`limitAtmYear`	integer	Yearly withdrawal limit
`limitAtmMonth`	integer	Monthly withdrawal limit
`limitAtmWeek`	integer	Weekly withdrawal limit
`limitAtmDay`	integer	Daily withdrawal limit

CURL

bash

curl -X PUT {baseUrl}/v1/cards/{cardId}/Limits \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

json

{
    "limitPaymentAll":25,
    "limitPaymentYear":0,
    "limitPaymentMonth":0,
    "limitPaymentWeek":10,
    "limitPaymentDay":0,
    "limitAtmAll":0,
    "limitAtmYear":0,
    "limitAtmMonth":0,
    "limitAtmWeek":10,
    "limitAtmDay":0
}

Returns the Card object with the updated limit attributes.

JSON

json

{
	"cardId": integer,
	"userId": integer,
	"walletId": integer,
	"publicToken": "string",
	"cardTag": "string",
	"statusCode": "UNLOCK",	
	"isLive": 1,
	"pinTryExceeds": 0, 
	"optionAtm": 1,	
	"optionForeign": 0,
	"optionOnline": 1,
	"optionNfc": 1,	
	"limitAtmYear": 0,		
	"limitAtmMonth": 0,	
	"limitAtmWeek": 10,
	"limitAtmDay": 0,
	"limitAtmAll": 0,
	"limitPaymentYear": 0,
	"limitPaymentMonth": 0,
	"limitPaymentWeek": 10,
	"limitPaymentDay": 0,
	"limitPaymentAll": 25,
	// [...] some attributes are hidden
}

Treezor also sends a card.limits webhook.

Check total spent amounts

Specific attributes indicate the total amount spent periodically for ATM and card payments.

When Treezor creates a Card Transaction object, these total amount spent values are updated if relevant. You can also find them in the cardtransaction.create webhook.

Total amount spent	Description	Corresponding limit
`totalLimitAtmYear`	The card yearly withdrawal amount.	`limitAtmYear`
`totalLimitAtmMonth`	The card monthly withdrawal amount.	`limitAtmMonth`
`totalLimitAtmWeek`	The card weekly withdrawal amount.	`limitAtmWeek`
`totalLimitAtmDay`	The card daily withdrawal amount.	`limitAtmDay`
`totalLimitAtmAll`	The card total withdrawal amount.	`limitAtmAll`
`totalLimitPaymentYear`	The card yearly spent amount.	`limitPaymentYear`
`totalLimitPaymentMonth`	The card monthly spent amount.	`limitPaymentMonth`
`totalLimitPaymentWeek`	The card weekly spent amount.	`limitPaymentWeek`
`totalLimitPaymentDay`	The card dayly spent amount.	`limitPaymentDay`
`totalLimitPaymentAll`	The card total spent amount.	`limitPaymentAll`

With this comparison, you can let your users know how much they have left to spend, anticipating any refused transactions due to reached limits.

Please note the total attributes are populated differently depending on the context (e.g., Card or Card Transaction, paymentStatus), and only when necessary for performance optimization.

Card Transactions total spent amount

In the Card Transaction object, the total attributes are null when:

The paymentStatus is other than A (Authorized) or I (Declined).
Authorizations declined by the Card Processor (see authorization notes) or due to card usage issue (e.g., permissions, status) also result in null totals.
No corresponding limit is given (e.g., if limitAtmDay is 0, then totalLimitAtmDay is null)
The limit is a higher or equal to a limit of a higher periodicity (e.g., if limitPaymentWeek ≥ limitPaymentMonth, then totalPaymentWeek is null).

Cards total spent amount

The total limits are available in the Card object but are only valued when retrieving an individual Card with the /v1/cards/{cardId} request. Contrary to card transactions, all the total limit fields are populated as long as they have a corresponding limit.

When searching for a list of cards, all the total limits are set to null.

Card object total spent amount

Please note the name of the fields differ in the Card object compared to the Card transaction object.

Total amount spent	Description	Corresponding limit
`totalAtmYear`	The card yearly withdrawal amount.	`limitAtmYear`
`totalAtmMonth`	The card monthly withdrawal amount.	`limitAtmMonth`
`totalAtmWeek`	The card weekly withdrawal amount.	`limitAtmWeek`
`totalAtmDay`	The card daily withdrawal amount.	`limitAtmDay`
`totalAtmAll`	The card total withdrawal amount.	`limitAtmAll`
`totalPaymentYear`	The card yearly spent amount.	`limitPaymentYear`
`totalPaymentMonth`	The card monthly spent amount.	`limitPaymentMonth`
`totalPaymentWeek`	The card weekly spent amount.	`limitPaymentWeek`
`totalPaymentDay`	The card dayly spent amount.	`limitPaymentDay`
`totalPaymentAll`	The card total spent amount.	`limitPaymentAll`

MCC restrictions

Merchant Category Codes (MCC) restrictions are list-based restrictions allowing you to limit the usage of the card to specific categories of merchants.

Parameters

Attribute	Type	Description
`name`	string	The name of the restriction group
`isWhitelist`	boolean	Indicates the kind of restriction: `true` (default) – Allows only a specified list of merchant caegories (whitelist) `false` – Allows all merchant categories except the specified list (blacklist)
`mcc`	array	The list of MCCs (each MCC is an integer).
`status`	array	One of the following values: `VALIDATED` – The restriction is active. `PENDING` (default) – The restriction is created but not yet active. `CANCELED` – The restriction has been deactivated (this is irreversible).
`startDate`	string	The date and time at which the restriction starts. Defaults to the date and time of creation.

Request

To create MCC restrictions, you can use the following request:

CURL

bash

curl -X POST {baseUrl}/v1/mccRestrictionGroups \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

json

{
    "name": "Restriction Restaurant, Bar, Fast-Food",
    "isWhitelist": true,
    "mcc": [
        5812,
        5813,
        5814
    ],
    "startDate": "2024-05-01 00:00:00"
}

Returns the Merchant ID Restriction Group object with its id (that you should keep on your side to apply these restrictions to Cards).

JSON

json

{
    "mccRestrictionGroups": [
        {
            "id": 47597,
            "name": "Restriction Restaurant, Bar, Fast-Food",
            "isWhitelist": true,
            "mcc": [
                5812,
                5813,
                5814
            ],
            "status": "PENDING",
            "startDate": "2024-05-01 00:00:00",
            "createdDate": "2024-04-24 09:04:38",
            "modifiedDate": null
        }
    ]
}

Treezor also sends a mccGroup.create webhook.

Apply the restriction

To apply the restriction to a card, set the mccRestrictionGroupId value to the previously obtained id when creating or updating the card:

Country restrictions

You may restrict a Card use in some countries only.

Parameters

Attribute	Type	Description
`name`	string	The name of the restriction group
`isWhitelist`	boolean	Indicates the kind of restriction: `true` (default) – Allows only a specified list of countries (whitelist) `false` – Allows all countries except the specified list (blacklist)
`countries`	array	The list of countries (each country is a string featuring a Country Code in the ISO 3166-1 numeric format 3-digit code).
`status`	array	One of the following values: `VALIDATED` – The restriction is active. `PENDING` (default) – The restriction is created but not yet active. `CANCELED` – The restriction has been deactivated (this is irreversible).
`startDate`	string	The date and time at which the restriction starts. Defaults to the date and time of creation.

Caution – Use the ISO 3166-1 numeric format

Contrary to other endpoints, here countries are expected in ISO 3166-1 numeric format (a 3-digit code).

Request

To create country restrictions, you can use the following request:

CURL

bash

curl -X POST {baseUrl}/v1/countryRestrictionGroups \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

json

{
    "name": "Restriction Belgium, Germany, France",
    "isWhitelist": true,
    "countries": [
        "250",
        "276", 
        "056"
    ],
    "startDate": "2024-05-01 00:00:00"
}

Returns the Country Restriction Group object with its id (that you should keep on your side to apply these restrictions to Cards).

JSON

json

{
    "countryRestrictionGroups": [
        {
            "id": 179655,
            "name": "Restriction Belgium, Germany, France",
            "isWhitelist": true,
            "countries": [
                "250",
                "276",
                "056"
            ],
            "status": "PENDING",
            "startDate": "2024-05-01 00:00:00",
            "createdDate": "2024-04-24 08:55:26",
            "modifiedDate": null
        }
    ]
}

Treezor also sends a countryGroup.create webhook.

Apply the restriction

To apply the restriction to a card, set the countryRestrictionGroupId value to the previously obtained id when creating or updating the card:

MID restrictions

Merchant Id (MID) restrictions are list-based restrictions allowing you to limit the usage of the card to specific merchants.

You can restrict MID in one of two ways:

Allowing only a specified list of merchants (whitelist)
Allowing all merchants except a specified list (blacklist)

If you plan on creating more than 20 MID restriction lists, please contact Treezor.

Parameters

Attribute	Type	Description
`name`	string	The name of the restriction group
`isWhitelist`	boolean	Indicates the kind of restriction: `true` (default) – Allows only a specified list of merchants (whitelist) `false` – Allows all merchants except the specified list (blacklist)
`merchants`	array	The list of MIDs (each MID is a string).
`status`	array	One of the following values: `VALIDATED` – The restriction is active. `PENDING` (default) – The restriction is created but not yet active. `CANCELED` – The restriction has been deactivated (this is irreversible).
`startDate`	string	The date and time at which the restriction starts. Defaults to the date and time of creation.

Request

To create MID restrictions, you can use the following request:

CURL

bash

curl -X POST {baseUrl}/v1/merchantIdRestrictionGroups \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

json

{
    "name": "Restriction merchantId 2024",
    "isWhitelist": true,
    "merchants": [
        "44355534500019",
        "ZWORT8KLOW9",
        "8935467"
    ],
    "startDate": "2024-05-01 00:00:00"
}

Returns the merchantIdRestrictionGroups object with its id (that you should keep on your side to apply these restrictions to Cards).

JSON

json

{
    "merchantIdRestrictionGroups": [
        {
            "id": 104734,
            "name": "Restriction merchantId 2024",
            "isWhitelist": true,
            "status": "PENDING",
            "startDate": "2024-05-01 00:00:00",
            "createdDate": "2024-04-24 09:09:59",
            "modifiedDate": null
        }
    ]
}

Treezor also sends a merchantIdGroup.create webhook.

Alert – Chain stores don't have a unique MID

Note that each shop of a chain store has its own merchantId, in such a situation you may want to use MCC instead (which could block more than expected) or explicitly list all the relevant merchantId.

Treezor offers the MID Metadata endpoint to help you associate metadata to MIDs.

Apply the restriction

To apply the restriction to a card, set the merchantRestrictionGroupId value to the previously obtained id when creating or updating the card:

MID Metadata

In some cases, the Merchant Id (MID) may not be up-to-date or the given information not enough for you to act on it. Treezor offers endpoints to add metadata to MIDs, hence allowing you to add human-readable information as you see fit.

Add metadata to a MID

To add metadata to a MID, you may use the following request by populating the metadata freely in the body (except for the mid attribute which is reserved).

CURL

bash

curl -X PUT {baseUrl}/core-connect/mid/{mid}/metadata \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}.

JSON

json

{
    "contact": "100@example.com",
    "address": "1208, Willow lane, 75000 Paris"
}

Returns the object you've created with a 201 Created HTTP Status code.

JSON

json

{
    "contact": "100@example.com",
    "address": "1208, Willow lane, 75000 Paris"
}

You can then retrieve this information by using the following request:

/core-connect/mid/{mid}/metadata

Manage metadata in bulk

You can use the following request to either add or update metadata in bulk.

CURL

bash

curl -X PUT {baseUrl}/core-connect/mid/metadata \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}.

JSON

json

[
    {
        "mid": "100",
        "contact": "100@example.com",
        "address": "1208, Willow lane, 75000 Paris",
        "siret": "348674XXXX067"
    },
    {
        "mid": "200",
        "contact": "200@example.com",
        "address": "1208, Ashwood street, Madrid"
    },
    {
        "mid": "300",
        "contact": "300@example.com",
        "address": "1208, Rosewood road, London"
    }
]

Returns a 204 HTTP Status Code without any content.

Retrieve all MID metadata

You may use the following request to retrieve all the MID metadata you populated.

CURL

bash

curl -X GET {baseUrl}/core-connect/mid/metadata/ \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Returns all the MID metadata object you've created.

JSON

json

[
    {
        "mid": "100",
        "contact": "100@example.com",
        "address": "1208, Willow lane, 75000 Paris",
        "siret": "348674XXXX067"
    },
    {
        "mid": "200",
        "contact": "200@example.com",
        "address": "1208, Ashwood street, Madrid"
    },
    {
        "mid": "300",
        "contact": "300@example.com",
        "address": "1208, Rosewood road, London"
    }
]

You can also retrieve the metadata for all MIDs belonging to a previously created MID Restriction Group using the following request:

/core-connect/merchantIdRestrictionGroups/{groupId}/mid/metadata

This request returns the list of MIDs along with their metadata. The list a paginated using a cursor.

Group limits

Group limits (or multi-loop) offers more freedom configuring limits and restrictions in some advanced cases.

Information – Treezor offers its own Transaction Rules Engine

Historically, group limits were designed for food vouchers use cases. Treezor Transactions Rules Engine offers an even better way to handle such cases, allowing you to define contextual rulesets, evaluated at each transaction.

Contact Treezor to find out which option works best for you.

You can create groups of limits and restrictions upon creating of updating a Card using the restrictionGroupLimits attribute. This array allows you to create an object for each group of limits, and each object can contain:

paymentDailyLimit – For payment limits
mccRestrictionGroups – For MCC restrictions
countryRestrictionGroups – For countries restrictions
merchantIdRestrictionGroups – For MID restrictions

In doing so, you may have a GroupLimit covering restaurants with its own daily payment limit, and a second GroupLimit covering fresh food stores with a different daily payment limit.

Your Cards could therefore be used in both restaurant and fresh food store, but with distinct payment limits for each situation.

Restrictions & Limits ​

Options & Permission groups ​

Permission groups (permsGroup) ​

Update card options ​

Parameters ​

Request ​

Payment & Withdrawal limits ​

Limit rules and functionalities ​

Payment limits ​

Withdrawal limits ​

Update limits ​

Check total spent amounts ​

Card Transactions total spent amount ​

Cards total spent amount ​

MCC restrictions ​

Parameters ​

Request ​

Apply the restriction ​

Country restrictions ​

Parameters ​

Request ​

Apply the restriction ​

MID restrictions ​

Parameters ​

Request ​

Apply the restriction ​

MID Metadata ​

Add metadata to a MID ​

Manage metadata in bulk ​

Retrieve all MID metadata ​

Group limits ​

Restrictions & Limits

Options & Permission groups

Permission groups (`permsGroup`)

Update card options

Parameters

Request

Payment & Withdrawal limits

Limit rules and functionalities

Payment limits

Withdrawal limits

Update limits

Check total spent amounts

Card Transactions total spent amount

Cards total spent amount

MCC restrictions

Parameters

Request

Apply the restriction

Country restrictions

Parameters

Request

Apply the restriction

MID restrictions

Parameters

Request

Apply the restriction

MID Metadata

Add metadata to a MID

Manage metadata in bulk

Retrieve all MID metadata

Group limits