Modification
Aside from the card lifecycle 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:
| 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.
bash
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.
PIN Change
If a Card is in the UNLOCK
status and not PIN-locked, you can change 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.
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 physically 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. |
bash
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
}
]
}
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. |
bash
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
}
]
}
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.
Request example
Only the cardId
passed as a path parameter is required to use the following request.
bash
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
}
]
}
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.
bash
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
.
Tip – Unlocking for users not using 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:
bash
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
}
]
}