# Modifications

# Overview diagram

Tip – Diagram is interactive

Click on the diagram nodes to access the relevant documentation.

# Block a card

If you suspect fraud or misuse, the API allows you to block temporarily or permanently a card, effective immediately.

This feature can also be used with special cards that must expire at a specific date (such as a one year valid gift card). You will have to lock the card on the expiration day.

Best practice – Allowing your end users to block their cards

While blocking a card temporarily is no issue, you should not allow end users to block their cards permanently without thorough confirmation steps (as fees may apply to issue a replacement card).

# Status

Statuses are defined in the statusCode attribute of a Card.

`statusCode`	plaintext value	Description	Locked
`0`	`UNLOCK`	The card is unlocked and can be used (if no other options or limits prevent it)	N/A
`1`	`LOCK`	The card is locked and cannot be used	Temporarily
`2`	`LOST`	The card is lost and cannot be used	Permanently
`3`	`STOLEN`	The card is stolen and cannot be used	Permanently
`4`	`DESTROYED`	The card is terminated and cannot be used	Permanently
`5`	`LOCK_INTERNAL`	The card is locked by Treezor and cannot be used, only Treezor is able to unlock it.	Temporarily
`6`	`EXPIRED`	The card has expired because it has been renewed or its expiry date has passed.	Permanently

Caution – A lost or stolen card can't be reactivated

If the cardholder wants a replacement card, a new card will have to be ordered.

# Mandatory information

You can use the following request to change the card lock status, with the cardId as a path parameter and the lockStatus in the body. This example specifies a lockStatus of 0, which unlocks a Card.

Returns a Card object, with a statusCode attribute set to either UNLOCK, LOCK, LOST, STOLEN, DESTROYED.

Although you provide the lockStatus as an integer, it is returned as a plaintext value.

# PIN Change

If a Card is in the UNLOCK status and not PIN-locked, you can change its PIN code. There are two ways to do so:

Without knowing the previous PIN – PUT /v1/cards/{cardId}/setPIN (machine-oriented endpoint)
Requiring the previous PIN – PUT /v1/cards/{cardId}/changePIN (end user-oriented endpoint)

Once set, you cannot retrieve a PIN code using Treezor's API. Unless you are PCI/DSS compliant, you shouldn't store the PIN code on your infrastructure either.

# End user manual action required

When a PIN code is changed via the API, there is no immediate way to relay the information to the physical card. A withdrawal or balance inquiry must be made by the cardholder to an ATM for the change to take effect.

The ATM automatically updates the PIN code of the Card upon such as operation. Note that even a rejected withdrawal will update the PIN code.

If your Card program doesn't allow for withdrawals, you should not allow or change PIN codes, as end users would be unable to physicaly use their cards.

# Without the previous PIN

This is the initial situation upon Card creation.

# Parameters

In addition to the cardId passed as a path parameter, the following parameters are required.

Attribute	Type	Description
`newPIN`	string	The new PIN code of the card. Must be a string to allow for leading zeroes.
`confirmPIN`	string	Confirmation of the new PIN code of the card. Must be a string to allow for leading zeroes.

Here is an example of {payload}:

Returns a Card object.

# With the previous PIN

# Parameters

In addition to the cardId passed as a path parameter, the following parameters are required.

Attribute	Type	Description
`currentPIN`	string	The current PIN code of the card. Must be a string to allow for leading zeroes.
`newPIN`	string	The new PIN code of the card. Must be a string to allow for leading zeroes.
`confirmPIN`	string	Confirmation of the new PIN code of the card. Must be a string to allow for leading zeroes.

Here is an example of {payload}:

Returns a Card object.

It is recommended that you let your end user choose their PIN when ordering a new Card.

# PIN Unlock

Entering 3 erroneous PIN codes in a row blocks the PIN and sets the pinTryExceeds to 1.

As the card is blocked on the server side, you can unblock it instantaneously using a dedicated endpoint. When unlocking a PIN, the PIN code remains unchanged.

Note – You can't change a locked PIN

If the PIN is blocked you must unlock the PIN before being able to change it.

# Mandatory information

Only the cardId passed as a path parameter is required to use the following request.

Returns a Card object with the pinTryExceeds parameter set to 0.

# CVV Unlock

The Card CVV can get locked if the cardholder enters multiple times in a row an erroneous CVV while attempting an e-commerce payment. The number of attempts is configurable, and is usually set to 3 or 5.

When this happens, the cardtransaction.create webhook contains an authorizationNote valued to DR: CVC2 tries exceeded.

As the card is blocked on the server side, you can unblock it instantaneously using a dedicated endpoint.

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

1
2
3

Danger – Do not expose this endpoint to your end users

This endpoint is only dedicated to you, and you must ensure the cardholder's identity before unlocking the card.

It returns a 204 HTTP response with the following description: successfully unblocked.

Tip – Unlocking for users not using Connect

If haven't migrated to , or if the feature is not yet available to you, you must open a ticket (opens new window) to unlock a CVV.

# 3DS Unlock

The 3DS feature of a Card can get locked if the cardholder fails 3 times the 3DS authentication using One Time Password while attempting an e-commerce payment.

When using the Strong Customer Authentication instead of One Time Password, a failure to authenticate doesn't increment the 3DS failure count and will not lock the 3DS feature.

If the SCA feature cannot be used and the fallback to One Time Password via SMS is used, then a locking can still occur.

To unlock the 3DS feature, you must open a ticket (opens new window) as no API endpoint currently allow to unlock the 3DS feature.

# Options change

Updating the card options parameters allows you to manage individually the options initially set with the Permission Group.

When changing the card options:

You can't bypass options blocked by your Card Program
Updating the Card options automatically updates the Permission Group
When modifying a single option all 4 must be specified
Some options are not relevant for Virtual Cards but remain available should you want to convert the Card to Physical

# Parameters

In addition to the cardId passed as a path parameter, the following parameters are required (1 for enabled, 0 for disabled).

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

Here is an example of {payload}:

Returns the Card object.

# Payments & Withdrawals limits

Each card has its own payment and withdrawals limits. These limits are enforced by our servers, therefore you can modify limits at any time with immediate effect.

You may define these when creating the card, or later on using the dedicated endpoint. If you do not specify all of them during the creation, the card will adopt default values defined by your Treezor Account Manager. At least one limitPayment{period} and one limitAtm{period} must be defined upon creation.

# 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. To enforce payment limit based on the cardholder's timezone, you must populate the timezone attribute of the User.

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's 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.

You can set the daily limit in either paymentDailyLimit (float) or limitPaymentDay (integer). Only one of the two should be populated, preferably limitPaymentDay.

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

# Mandatory information

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

Returns the Card object with the updated limit attributes.

# 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's yearly spent amount.
totalLimitPaymentMonth– The related Card's monthly spent amount.
totalLimitPaymentWeek – The related Card's weekly spent amount.
totalLimitPaymentDay – The related Card's daily spent amount.
totalLimitPaymentAll – The related Card's lifetime spent amount.
totalLimitAtmWeek – The related Card's weekly ATM withdrawal amount.
totalLimitAtmDay – The related Card's daily ATM withdrawal amount.
totalLimitAtmAll – The related Card's 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 (ie GET /v1/cards/?userId={userId}).

# List-based restrictions

You may restrict the use of a Card based on:

Specific merchants – Using MID lists.
Specific merchants categories – Using MCC lists.
Specific groups of countries – Using country code lists.

# MID restrictions

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)

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

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

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

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 explicitely list all the relevant merchantId.

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

💡 Treezor exposes an endpoint to help you associated metadata to MIDs.

# MCC restrictions

You may restrict the use of a Card based on merchant categories using the corresponding Merchant Categorie Codes (MCC).

Categories can for example be: restaurants, cars rentals companies, etc.

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

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

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

# Country-based restrictions

You may restrict a Card's 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).
`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) (opens new window).

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

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

# Applying a restriction list

To apply the list on an existing Card, you simply update the Card's merchantRestrictionGroupId, mccRestrictionGroupsId, or countryRestrictionGroupsId attribute.

# Mandatory information

id ID of the card
merchantRestrictionGroupId the ID of your whitelist or blacklist

Returns the Card object with its merchantRestrictionGroupId attribute updated.

# Group Limits (or Multi-loop)

In some advanced cases, you may need more freedom in configuring restrictions. The GroupLimit feature fills this need.

GroupLimit (restrictionGroupLimits) can have their own payment limits, MID restrictions, MCC restrictions and countries restrictions, and they can be cumulated.

Allowing you for example, to have a GroupLimit covering restaurants with its own daily payment limit, and a second GroupLimit covering fresh food stores with its own daily payment limit. Your Cards could therefore be used in both restaurant and fresh food store, but with distinct payment limits for each situations.

Tip – More options are available if these these restrictions don't cover your needs

Transactions Rules Engine – Allowing you to define contextual rulesets, evaluated at each transaction.
Transactions External Validation – Requesting an authorization from your servers in real-time for each transaction.

# Regeneration

In case your brand changes its graphical identity (such as a new logo, new colors, new layout, etc.) you can ask Treezor to set up a new card design, and then re-generate Virtual Cards images without altering their actual PAN, CVC, or expiration date.

Example of a Card regeneration:

Returns the Card object.

← Creation Conversions →