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

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

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

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

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

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

{
    "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

{
	"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.

Checking if limits have been reached

With each Card Transaction with a paymentStatus I (Declined) or A (Authorized), a webhook is sent containing daily, weekly, monthly, yearly, and lifetime spendings. You can then compare them to the card limits.

There are contained in the following attributes:

• totalLimitPaymentYear – The related Card yearly spent amount.
• totalLimitPaymentMonth– The related Card monthly spent amount.
• totalLimitPaymentWeek – The related Card weekly spent amount.
• totalLimitPaymentDay – The related Card daily spent amount.
• totalLimitPaymentAll – The related Card lifetime spent amount.
• totalLimitAtmWeek – The related Card weekly ATM withdrawal amount.
• totalLimitAtmDay – The related Card daily ATM withdrawal amount.
• totalLimitAtmAll – The related Card lifetime ATM withdrawal amount.

Note – Totals attributes are valued to 0 if

• A Card Transaction has a paymentStatus other than I or A.
• No limit is defined for a given period (e.g., limitAtmDay), then the corresponding total (totalLimitAtmDay) is valued to 0.

These attributes are also present on Card objects but only valued when retrieving an individual Card (i.e., GET /v1/cards?cardId={cardId}), not when retrieving all Cards of a user (i.e., GET /v1/cards?userId={userId}).

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

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

Here is an example of {payload}:

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

{
    "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:

• /v1/cards/CreateVirtual
• /v1/cards/RequestPhysical
• /v1/cards/{cardId}

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

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

Here is an example of {payload}:

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

{
    "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:

• /v1/cards/CreateVirtual
• /v1/cards/RequestPhysical
• /v1/cards/{cardId}

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

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

Here is an example of {payload}:

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

{
    "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:

• /v1/cards/CreateVirtual
• /v1/cards/RequestPhysical
• /v1/cards/{cardId}

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

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

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

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

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

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

[
    {
        "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

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

[
    {
        "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.