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.
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
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 | float | 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 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 onelimitAtm{period}
limit to another value than0
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 |
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 – Totals attributes are valued to 0
if
- A Card Transaction has a
paymentStatus
other thanI
orA
. - No limit is defined for a given period (e.g.,
limitAtmDay
), then the corresponding total (totalLimitAtmDay
) is valued to0
.
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:
|
mcc | array | The list of MCCs (each MCC is an integer). |
status | array | One of the following values:
|
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:
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
Attribute | Type | Description |
---|---|---|
name | string | The name of the restriction group |
isWhitelist | boolean | Indicates the kind of restriction:
|
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:
|
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:
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
Attribute | Type | Description |
---|---|---|
name | string | The name of the restriction group |
isWhitelist | boolean | Indicates the kind of restriction:
|
merchants | array | The list of MIDs (each MID is a string). |
status | array | One of the following values:
|
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:
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.
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.
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 limitsmccRestrictionGroups
– For MCC restrictionscountryRestrictionGroups
– For countries restrictionsmerchantIdRestrictionGroups
– 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.