Modification

Aside from the card life cycle and options, Treezor offers a series of features to manage your cards on the day-to-day basis.

Feature	Description
Lock/Unlock	Ability to update the card status, hence unlocking and locking the card temporarily or permanently.
PIN code	Ability to change the PIN code, or unlock a card which has been blocked due to erroneous PIN code entries.
CVV unlock	Ability to unblock a card which has been blocked due to erroneous CVV entries.
Regeneration	Ability to recreate the virtual card image if your branding changes for instance.

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

Card Status

Statuses are defined in the statusCode attribute of a Card.

Code	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. The following webhooks are sent: card.expiryAlert – The card expires at the end of the next month for you to anticipate Renewal. card.update – The card expired.	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.

Request example

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.

CURL

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

Here is an example of {payload} which specifies a lockStatus of 2, declaring the Card as LOST and locking it permanently.

JSON

{
	"lockStatus":2
}

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

JSON

{
	"cardId": 999894949,
	"userId": 100198207,
	"walletId": 2728965,
	"publicToken": "105603415",
	"cardTag": "string",
	"statusCode": "LOST",
	"isLive": 1,
	"cancellationNumber": "19532590" 	// Generated for LOST & STOLEN Cards only
	// [...] some attributes are hidden
}

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

Treezor also sends a card.lockunlock webhook.

Card account selection Beta

For a given card, you may use a different Wallet for each transaction. This may prove particularly useful to centralize various services on a unique card. For instance, the same card could be used for employee benefits and food vouchers.

Configuration – Feature not enabled by default

Please contact Treezor to activate the Card account selection feature.

Assigning the card to a Wallet can be done as often as you wish to, and either:

• Manually – The user chooses the Wallet to debit prior to the transaction.
• Dynamically – The MDC or external validation feature selects the Wallet when the transaction is initiated.

This feature is only compatible with the following types of Wallet: 9, 10, 15.

Information – The behavior is transparent in the transaction life cycle

Even if the wallet assigned to the card changes, the wallet of a given card transaction remains the same during the whole transaction life cycle. The debited wallet value is available in the card.transaction webhook.

Manual selection

In this case, the cardholder manually selects the Wallet to be debited before the transaction.

Parameters

Attribute	Type	Description
cardId	query	The unique identifier of the card to assign.
walletId	integer	The unique identifier of the wallet to which the card is to be assigned. The wallet must have the same userId value as the card if the walletTypeId is 9 or 10.

Request example

CURL

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

Here is an example of {payload}:

JSON

{
	"walletId":123456
}

Returns the Card object with the updated walletId value, and sends the card.update webhook.

JSON

{
	"cardId": 999894949,
	"userId": 100198207,
	"walletId":123456,
	"publicToken": "105603415",
	"cardTag": "string",
	"statusCode": "UNLOCK",
	"isLive": 1,
	// [...] some attributes are hidden
}

Dynamic selection

You can take advantage of the Multi-Criteria Dynamic Card (MDC) or the external validation feature to automatically debit the relevant Wallet when a transaction is initiated.

The steps are the following:

1. The User initiates a payment with their card.
2. The Multi-Criteria Dynamic Card (MDC) rules engine or your external validation system determines the wallet to use.
3. The Wallet is debited by the card transaction.

Specific cases

Offline transactions

When a transaction occurs offline, there is no information regarding the assigned Wallet yet. In that case, the last assigned Wallet is debited when using manual selection.

When relying on MDC or external authorization for dynamic selection though, you can create rules for the relevant wallet to be selected for offline transactions.

Recurring transactions

For recurring transactions, the same Wallet is debited as the initial transaction.

PIN Change

If a Card is in the UNLOCK status and not PIN-locked, you can define its PIN code. There are 2 ways to proceed:

Context	Endpoint	Usage
Without the previous PIN	/v1/cards/{cardId}/setPIN	Machine-oriented
Requiring the previous PIN	/v1/cards/{cardId}/changePIN	End user-oriented

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

We recommend you let your end users choose their PIN code when ordering a new card.

End user ATM action required

When changing the PIN code via the API, there is no immediate way to relay the information to the physical card. The cardholder must make a withdrawal or balance inquiry at an ATM for the change to take effect.

This method works even if the Card program doesn't include withdrawals. Indeed, a rejected withdrawal updates the card too.

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.

Request example

CURL

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

Here is an example of {payload}:

JSON

{
	"newPIN":"1234",
	"confirmPIN":"1234"
}

Returns a Card object and sends the card.setpin webhook.

JSON

{
    "cards": [
        {
            "cardId": 999994169,
            "userId": 100642533,
            "walletId": 3151814,
            "walletCardtransactionId": 3159200,
            "mccRestrictionGroupId": 0,
            "merchantRestrictionGroupId": 0,
            "countryRestrictionGroupId": 0,
            "publicToken": "105501272",
            "cardTag": "black",
            "statusCode": "UNLOCK",
            "isLive": 0,
            "pinTryExceeds": 0,
            "maskedPan": "548821******6605",
            "embossedName": "ALEX OAK",
            "expiryDate": "2027-07-31",
            "CVV": "370",
            "startDate": "2024-07-24",
            "endDate": "0000-00-00",
            "countryCode": "FR",
            "currencyCode": "EUR",
            "lang": null,
            "deliveryTitle": "M",
            "deliveryLastname": "OAK",
            "deliveryFirstname": "ALEX",
            "deliveryAddress1": "07323 WOODLANE",
            "deliveryAddress2": "",
            "deliveryAddress3": "",
            "deliveryCity": "PARIS",
            "deliveryPostcode": "75017",
            "deliveryCountry": "FR",
            "mobileSent": "+336XXXXXXXX",
            "limitsGroup": "TRZ-VL-001",
            "permsGroup": "TRZ-CU-012",
            "cardDesign": "1234",
            "virtualConverted": 0,
            "physical": 0,
            "optionAtm": 0,
            "optionForeign": 1,
            "optionOnline": 1,
            "optionNfc": 1,
            "limitAtmYear": 0,
            "limitAtmMonth": 0,
            "limitAtmWeek": 2000,
            "limitAtmDay": 1000,
            "limitAtmAll": 0,
            "limitPaymentYear": 0,
            "limitPaymentMonth": 0,
            "limitPaymentWeek": 3000,
            "limitPaymentDay": 2000,
            "limitPaymentAll": 0,
            "paymentDailyLimit": 500.0,
            "totalAtmYear": 0,
            "totalAtmMonth": 0,
            "totalAtmWeek": null,
            "totalAtmDay": null,
            "totalAtmAll": 0,
            "totalPaymentYear": 0,
            "totalPaymentMonth": 0,
            "totalPaymentWeek": null,
            "totalPaymentDay": null,
            "totalPaymentAll": 0,
            "createdBy": 929252,
            "createdDate": "2024-07-24 11:13:15",
            "modifiedBy": 929252,
            "modifiedDate": "2024-09-13 15:13:26",
            "totalRows": null,
            "designCode": null,
            "cardLanguages": "",
            "eventName": "Name of the Wallet",
            "eventAlias": "name-of-the-wallet-669f4218dfbff",
            "restrictionGroupLimits": null,
            "cancellationNumber": "",
            "metadata": null,
            "renewalDate": null,
            "renewalType": null,
            "originalCardId": null,
            "logoId": "",
            "logoBackId": "",
            "packageId": "",
            "customizeInfo": "",
            "letterCustomizedInfo": "",
            "freeCustomizedInfo": "",
            "deliveryMethod": null,
            "pinMailer": null,
            "batchDeliveryId": null,
            "sendToParent": 0
        }
    ]
}

If the card is PIN-locked (pinTryExceeds value set to 1), the request fails with a 400 HTTP status code and the following error.

JSON

{
    "errors": [
        {
            "type": "invalid_request",
            "code": "input_validation_error",
            "message": "Card blocked.",
            "docUrl": "https://docs.treezor.com/guide/api-basics/response-codes.html#error-attributes",
            "requestId": "20ba6d1c-f903-4ab8-918b-341ee13b59b8"
        }
    ]
}

You must PIN Unlock before setting the PIN code.

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.

Request example

CURL

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

Here is an example of {payload}:

JSON

{
	"currentPIN": "4321",
	"newPIN":"1234",
	"confirmPIN":"1234"
}

Returns a Card object and sends the card.changepin webhook.

JSON

{
    "cards": [
        {
            "cardId": 999994169,
            "userId": 100642533,
            "walletId": 3151814,
            "walletCardtransactionId": 3159200,
            "mccRestrictionGroupId": 0,
            "merchantRestrictionGroupId": 0,
            "countryRestrictionGroupId": 0,
            "publicToken": "105501272",
            "cardTag": "black",
            "statusCode": "UNLOCK",
            "isLive": 0,
            "pinTryExceeds": 0,
            "maskedPan": "548821******6605",
            "embossedName": "ALEX OAK",
            "expiryDate": "2027-07-31",
            "CVV": "370",
            "startDate": "2024-07-24",
            "endDate": "0000-00-00",
            "countryCode": "FR",
            "currencyCode": "EUR",
            "lang": null,
            "deliveryTitle": "M",
            "deliveryLastname": "OAK",
            "deliveryFirstname": "ALEX",
            "deliveryAddress1": "07323 WOODLANE",
            "deliveryAddress2": "",
            "deliveryAddress3": "",
            "deliveryCity": "PARIS",
            "deliveryPostcode": "75017",
            "deliveryCountry": "FR",
            "mobileSent": "+336XXXXXXXX",
            "limitsGroup": "TRZ-VL-001",
            "permsGroup": "TRZ-CU-012",
            "cardDesign": "1234",
            "virtualConverted": 0,
            "physical": 0,
            "optionAtm": 0,
            "optionForeign": 1,
            "optionOnline": 1,
            "optionNfc": 1,
            "limitAtmYear": 0,
            "limitAtmMonth": 0,
            "limitAtmWeek": 2000,
            "limitAtmDay": 1000,
            "limitAtmAll": 0,
            "limitPaymentYear": 0,
            "limitPaymentMonth": 0,
            "limitPaymentWeek": 3000,
            "limitPaymentDay": 2000,
            "limitPaymentAll": 0,
            "paymentDailyLimit": 500.0,
            "totalAtmYear": 0,
            "totalAtmMonth": 0,
            "totalAtmWeek": null,
            "totalAtmDay": null,
            "totalAtmAll": 0,
            "totalPaymentYear": 0,
            "totalPaymentMonth": 0,
            "totalPaymentWeek": null,
            "totalPaymentDay": null,
            "totalPaymentAll": 0,
            "createdBy": 929252,
            "createdDate": "2024-07-24 11:13:15",
            "modifiedBy": 929252,
            "modifiedDate": "2024-09-13 15:13:26",
            "totalRows": null,
            "designCode": null,
            "cardLanguages": "",
            "eventName": "Name of the Wallet",
            "eventAlias": "name-of-the-wallet-669f4218dfbff",
            "restrictionGroupLimits": null,
            "cancellationNumber": "",
            "metadata": null,
            "renewalDate": null,
            "renewalType": null,
            "originalCardId": null,
            "logoId": "",
            "logoBackId": "",
            "packageId": "",
            "customizeInfo": "",
            "letterCustomizedInfo": "",
            "freeCustomizedInfo": "",
            "deliveryMethod": null,
            "pinMailer": null,
            "batchDeliveryId": null,
            "sendToParent": 0
        }
    ]
}

If the card is PIN-locked (pinTryExceeds value set to 1), the request fails with a 400 HTTP status code and the following error.

JSON

{
    "errors": [
        {
            "type": "invalid_request",
            "code": "input_validation_error",
            "message": "Card blocked.",
            "docUrl": "https://docs.treezor.com/guide/api-basics/response-codes.html#error-attributes",
            "requestId": "20ba6d1c-f903-4ab8-918b-341ee13b59b8"
        }
    ]
}

You must PIN Unlock the card before changing the PIN code.

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.

Request example

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

CURL

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

Returns a Card object and sends a card.unblockpin webhook with the pinTryExceeds parameter set to 0.

JSON

{
    "cards": [
        {
            "cardId": 999994169,
            "userId": 100642533,
            "walletId": 3151814,
            "walletCardtransactionId": 3159200,
            "mccRestrictionGroupId": 0,
            "merchantRestrictionGroupId": 0,
            "countryRestrictionGroupId": 0,
            "publicToken": "105501272",
            "cardTag": "black",
            "statusCode": "UNLOCK",
            "isLive": 0,
            "pinTryExceeds": 0,
            "maskedPan": "548821******6605",
            "embossedName": "ALEX OAK",
            "expiryDate": "2027-07-31",
            "CVV": "370",
            "startDate": "2024-07-24",
            "endDate": "0000-00-00",
            "countryCode": "FR",
            "currencyCode": "EUR",
            "lang": null,
            "deliveryTitle": "M",
            "deliveryLastname": "OAK",
            "deliveryFirstname": "ALEX",
            "deliveryAddress1": "07323 WOODLANE",
            "deliveryAddress2": "",
            "deliveryAddress3": "",
            "deliveryCity": "PARIS",
            "deliveryPostcode": "75017",
            "deliveryCountry": "FR",
            "mobileSent": "+336XXXXXXXX",
            "limitsGroup": "TRZ-VL-001",
            "permsGroup": "TRZ-CU-012",
            "cardDesign": "1234",
            "virtualConverted": 0,
            "physical": 0,
            "optionAtm": 0,
            "optionForeign": 1,
            "optionOnline": 1,
            "optionNfc": 1,
            "limitAtmYear": 0,
            "limitAtmMonth": 0,
            "limitAtmWeek": 2000,
            "limitAtmDay": 1000,
            "limitAtmAll": 0,
            "limitPaymentYear": 0,
            "limitPaymentMonth": 0,
            "limitPaymentWeek": 3000,
            "limitPaymentDay": 2000,
            "limitPaymentAll": 0,
            "paymentDailyLimit": 500.0,
            "totalAtmYear": 0,
            "totalAtmMonth": 0,
            "totalAtmWeek": null,
            "totalAtmDay": null,
            "totalAtmAll": 0,
            "totalPaymentYear": 0,
            "totalPaymentMonth": 0,
            "totalPaymentWeek": null,
            "totalPaymentDay": null,
            "totalPaymentAll": 0,
            "createdBy": 929252,
            "createdDate": "2024-07-24 11:13:15",
            "modifiedBy": 929252,
            "modifiedDate": "2024-09-13 15:13:26",
            "totalRows": null,
            "designCode": null,
            "cardLanguages": "",
            "eventName": "Name of the Wallet",
            "eventAlias": "name-of-the-wallet-669f4218dfbff",
            "restrictionGroupLimits": null,
            "cancellationNumber": "",
            "metadata": null,
            "renewalDate": null,
            "renewalType": null,
            "originalCardId": null,
            "logoId": "",
            "logoBackId": "",
            "packageId": "",
            "customizeInfo": "",
            "letterCustomizedInfo": "",
            "freeCustomizedInfo": "",
            "deliveryMethod": null,
            "pinMailer": null,
            "batchDeliveryId": null,
            "sendToParent": 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

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

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. Also sends a card.unblockcvc2 webhook.

Tip – Unlocking only available on Connect

If you haven't migrated to Connect, or if the feature is not yet available to you, you must open a ticket 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 as no API endpoint currently allow to unlock the 3DS feature.

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:

CURL

curl -X PUT {baseUrl}/v1/cards/{cardId}/Regenerate \
	--header 'Authorization: Bearer {accessToken}'

Returns the Card object and sends a card.regenerate webhook.

JSON

{
    "cards": [
        {
            "cardId": 999994169,
            "userId": 100642533,
            "walletId": 3151814,
            "walletCardtransactionId": 3159200,
            "mccRestrictionGroupId": 0,
            "merchantRestrictionGroupId": 0,
            "countryRestrictionGroupId": 0,
            "publicToken": "105501272",
            "cardTag": "black",
            "statusCode": "UNLOCK",
            "isLive": 0,
            "pinTryExceeds": 0,
            "maskedPan": "548821******6605",
            "embossedName": "ALEX OAK",
            "expiryDate": "2027-07-31",
            "CVV": "370",
            "startDate": "2024-07-24",
            "endDate": "0000-00-00",
            "countryCode": "FR",
            "currencyCode": "EUR",
            "lang": null,
            "deliveryTitle": "M",
            "deliveryLastname": "OAK",
            "deliveryFirstname": "ALEX",
            "deliveryAddress1": "07323 WOODLANE",
            "deliveryAddress2": "",
            "deliveryAddress3": "",
            "deliveryCity": "PARIS",
            "deliveryPostcode": "75017",
            "deliveryCountry": "FR",
            "mobileSent": "+336XXXXXXXX",
            "limitsGroup": "TRZ-VL-001",
            "permsGroup": "TRZ-CU-012",
            "cardDesign": "1234",
            "virtualConverted": 0,
            "physical": 0,
            "optionAtm": 0,
            "optionForeign": 1,
            "optionOnline": 1,
            "optionNfc": 1,
            "limitAtmYear": 0,
            "limitAtmMonth": 0,
            "limitAtmWeek": 2000,
            "limitAtmDay": 1000,
            "limitAtmAll": 0,
            "limitPaymentYear": 0,
            "limitPaymentMonth": 0,
            "limitPaymentWeek": 3000,
            "limitPaymentDay": 2000,
            "limitPaymentAll": 0,
            "paymentDailyLimit": 500.0,
            "totalAtmYear": 0,
            "totalAtmMonth": 0,
            "totalAtmWeek": null,
            "totalAtmDay": null,
            "totalAtmAll": 0,
            "totalPaymentYear": 0,
            "totalPaymentMonth": 0,
            "totalPaymentWeek": null,
            "totalPaymentDay": null,
            "totalPaymentAll": 0,
            "createdBy": 929252,
            "createdDate": "2024-07-24 11:13:15",
            "modifiedBy": 929252,
            "modifiedDate": "2024-09-13 15:13:26",
            "totalRows": null,
            "designCode": null,
            "cardLanguages": "",
            "eventName": "Name of the Wallet",
            "eventAlias": "name-of-the-wallet-669f4218dfbff",
            "restrictionGroupLimits": null,
            "cancellationNumber": "",
            "metadata": null,
            "renewalDate": null,
            "renewalType": null,
            "originalCardId": null,
            "logoId": "",
            "logoBackId": "",
            "packageId": "",
            "customizeInfo": "",
            "letterCustomizedInfo": "",
            "freeCustomizedInfo": "",
            "deliveryMethod": null,
            "pinMailer": null,
            "batchDeliveryId": null,
            "sendToParent": 0
        }
    ]
}