Skip to content

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.

permsGroupNFCATMOnlineForeign
TRZ-CU-001no crossno crossno crossno cross
TRZ-CU-002no crossno crossno crossyes checkmark
TRZ-CU-003no crossno crossyes checkmarkno cross
TRZ-CU-004no crossno crossyes checkmarkyes checkmark
TRZ-CU-005no crossyes checkmarkno crossno cross
TRZ-CU-006no crossyes checkmarkno crossyes checkmark
TRZ-CU-007no crossyes checkmarkyes checkmarkno cross
TRZ-CU-008no crossyes checkmarkyes checkmarkyes checkmark
TRZ-CU-009yes checkmarkno crossno crossno cross
TRZ-CU-010yes checkmarkno crossno crossyes checkmark
TRZ-CU-011yes checkmarkno crossyes checkmarkno cross
TRZ-CU-012yes checkmarkno crossyes checkmarkyes checkmark
TRZ-CU-013yes checkmarkyes checkmarkno crossno cross
TRZ-CU-014yes checkmarkyes checkmarkno crossyes checkmark
TRZ-CU-015yes checkmarkyes checkmarkyes checkmarkno cross
TRZ-CU-016yes checkmarkyes checkmarkyes checkmarkyes checkmark

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).

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

Request

Use the following request to update the card options.

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

AttributeTypeDescription
limitPaymentAllintegerLifetime payment limit
limitPaymentYearintegerYearly payment limit
limitPaymentMonthintegerMonthly payment limit
limitPaymentWeekintegerWeekly payment limit
limitPaymentDayintegerDaily payment limit

Withdrawal limits

AttributeTypeDescription
limitAtmAllintegerLifetime withdrawal limit
limitAtmYearintegerYearly withdrawal limit
limitAtmMonthintegerMonthly withdrawal limit
limitAtmWeekintegerWeekly withdrawal limit
limitAtmDayintegerDaily 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.

AttributeTypeUsage
paymentDailyLimitfloatThe 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.
limitPaymentDayintegerThe preferred option, applicable to all other use cases.

Limits are sliding limits.

For example, to evaluate a monthly limit for a transaction made February 15th, Treezor considers all transactions from January 15th (excluded) until February 15th (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
AttributeTypeDescription
limitPaymentAllintegerLifetime payment limit
limitPaymentYearintegerYearly payment limit
limitPaymentMonthintegerMonthly payment limit
limitPaymentWeekintegerWeekly payment limit
limitPaymentDayintegerDaily payment limit
limitAtmAllintegerLifetime withdrawal limit
limitAtmYearintegerYearly withdrawal limit
limitAtmMonthintegerMonthly withdrawal limit
limitAtmWeekintegerWeekly withdrawal limit
limitAtmDayintegerDaily withdrawal limit
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
{
    "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 icon

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

AttributeTypeDescription
name stringThe name of the restriction group
isWhitelistbooleanIndicates 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 arrayThe list of MCCs (each MCC is an integer).
statusarrayOne 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).
startDatestringThe 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:

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

Country restrictions

You may restrict a Card use in some countries only.

Parameters

AttributeTypeDescription
name stringThe name of the restriction group
isWhitelistbooleanIndicates the kind of restriction:
  • true (default) – Allows only a specified list of countries (whitelist)
  • false – Allows all countries except the specified list (blacklist)
countries arrayThe list of countries (each country is a string featuring a Country Code in the ISO 3166-1 numeric format 3-digit code).
statusarrayOne 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).
startDatestringThe date and time at which the restriction starts. Defaults to the date and time of creation.
Warning icon

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:

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

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

AttributeTypeDescription
name stringThe name of the restriction group
isWhitelistbooleanIndicates the kind of restriction:
  • true (default) – Allows only a specified list of merchants (whitelist)
  • false – Allows all merchants except the specified list (blacklist)
merchants arrayThe list of MIDs (each MID is a string).
statusarrayOne 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).
startDatestringThe 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:

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

Warning icon

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).

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

Manage metadata in bulk

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

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

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

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.

Info icon

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:

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.