Appearance
API guide
The API guide will take you through the following steps to successfully create users and gift cards:
- Create a physical user – Define your users with the required information.
- Create a card – Create cards for your users, with their limits and restriction groups.
- Activate the card – Activate the card for the user to be able use it.
- Manage cards – Update your card information as needed.
- Handle the end of life cycle – Make sure your destroy the card and delete the user once the funds are used.
Create a physical user
Physical users are your end users, that is to say, individuals who will use the gift cards. They are identified with the userTypeId value 1.
You must create users with the declarative data Treezor Compliance indicated in your KYC Form. In this use case, it corresponds to the following parameters.
| Attribute | Type | Description |
|---|---|---|
firstname | string | The end user's first name. |
lastname | string | The end user's last name. |
birthday | string | The end user's birth date. Format YYYY-MM-DD |
placeOfBirth | string | The end user's place of birth. |
birthCountry | string | The end user's birth country (format ISO 3166-1 alpha-2) |
nationality | string | The end user's nationality (format ISO 3166-1 alpha-2) |
specifiedUSPerson | integer | Needs to be set to 1 if the user is a citizen or a resident of the United States. In such cases a US tax residence (taxResidence) must be declared as well. |
email | string | The end user's email, which must be valid and can't exceed 200 characters. |
mobile | string | The end user's mobile phone number, in international E.164 format. |
address{1-3} | string | The end user's postal address. The max value for each address line is 56 characters, although due to mail carrier limitations, only the first 36 are printed on envelopes used to deliver Cards. |
postcode | string | The end user's address postcode. |
city | string | The end user's address city. |
country | string | The end user's address country (format ISO 3166-1 alpha-2) |
Information – Declarative data to submit depends on the use case
In our use case, users are not KYC-validated, so only the fields indicated in the KYC Form provided by Treezor are to be filled in.
You need to use the following request:
bash
curl -X POST {baseUrl}/v1/users \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is a {payload} example:
json
{
"userTypeId": 1,
"specifiedUSPerson": 0,
"title": "M",
"firstname": "Alex",
"lastname": "Oak",
"birthday": "1982-05-31",
"placeOfBirth": "Edgewood",
"birthCountry": "FR",
"nationality": "FR",
"email": "alex.oak@example.com",
"address1": "33 rosewood road",
"postcode": "75017",
"city": "Paris",
"country": "FR",
"phone": "+3311111111",
}It returns a User object if successful:
json
{
"users": [
{
"userId": 8327278,
"userTypeId": 1,
"userStatus": "VALIDATED",
"userTag": "",
"parentUserId": 0,
"parentType": "",
"controllingPersonType": 0,
"employeeType": 0,
"specifiedUSPerson": 0,
"title": "",
"firstname": "Alex",
"lastname": "Oak",
"middleNames": "",
"birthday": "1982-05-31",
"email": "alex.oak@example.com",
"address1": "33 rosewood road",
"address2": "",
"postcode": "75017",
"city": "Paris",
"state": "",
"country": "FR",
"countryName": "France",
"distributionCountry": null,
"phone": "+3311111111",
"mobile": "",
"nationality": "FR",
"nationalityOther": "",
"placeOfBirth": "Edgewood",
"birthCountry": "FR",
"occupation": "",
"incomeRange": "",
"legalName": "",
"legalNameEmbossed": "",
"legalRegistrationNumber": "",
"legalTvaNumber": "",
"legalRegistrationDate": "0000-00-00",
"legalForm": "",
"legalShareCapital": 0,
"entityType": null,
"legalSector": "",
"legalAnnualTurnOver": "",
"legalNetIncomeRange": "",
"legalNumberOfEmployeeRange": "",
"effectiveBeneficiary": 0,
"kycLevel": 1,
"kycReview": 0,
"kycReviewComment": "",
"isFreezed": 0,
"isFrozen": null,
"language": "",
"optInMailing": null,
"sepaCreditorIdentifier": "",
"taxNumber": "",
"taxResidence": "",
"position": "",
"personalAssets": "",
"createdDate": "2023-10-23 12:28:00",
"modifiedDate": "0000-00-00 00:00:00",
"walletCount": 0,
"payinCount": 0,
"totalRows": "1",
"activityOutsideEu": null,
"economicSanctions": null,
"residentCountriesSanctions": null,
"involvedSanctions": null,
"entitySanctionsQuestionnaire": null,
"address3": null,
"timezone": null,
"occupationType": "",
"isOnStockExchange": 0,
"secondaryAddress1": "",
"secondaryAddress2": "",
"secondaryAddress3": "",
"secondaryPostcode": "",
"secondaryCity": "",
"secondaryState": "",
"secondaryCountry": "",
"clientId": "945198",
"sanctionsQuestionnaireDate": null,
"codeStatus": "110009",
"informationStatus": "",
"legalSectorType": "",
"sourceOfFunds": "",
"occupationCategory": null,
"personalAssetsRange": null,
"monthlyIncomeRange": null
}
]
}You’ll need the userId parameter value for the next step.
Create a card
The card is connected to both your company Master Wallet and the user it’s going to be allocated to. You need the corresponding userId and walletId in the next steps.
Creating a card in this use case is divided into the following steps:
Create your restriction groups
To select the relevant options for the cards that you’ll be creating in the next step, you may create the restriction groups that apply to your use case.
Information – Restrictions are not testable in Sandbox
When emulating card transactions to test your integration, restrictions won’t apply.
Merchant Id restrictions
Defining the Merchant ID (MID) restrictions allows you to easily define if the card should be usable in some specific shops.
Here are the attributes you need to create a MID restriction group.
| 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. |
To create MID restrictions, 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} to create a single-merchant whitelist restriction:
json
{
"name": "Single-merchant example",
"merchants": [
"128787"
],
"status": "VALIDATED"
}It returns a Merchant ID Restriction Group object if successful:
json
{
"merchantIdRestrictionGroups": [
{
"id": 95447,
"name": "Single-merchant example",
"isWhitelist": true,
"merchants": [
"128787"
],
"status": "VALIDATED",
"startDate": "2023-10-23 12:19:49",
"createdDate": "2023-10-23 12:19:49",
"modifiedDate": ""
}
]
}Later on, you'll need the id to take into account the restriction during the card creation.
Merchant category restrictions
Defining specific merchant category codes (MCC) restrictions allows you to easily define if the card should be used in only certain categories of merchants (or, to blacklist some categories of merchants).
Here are the attributes you need to create a MCC restriction group.
| 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. |
To create MCC restrictions, 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} to blacklist specific merchant categories:
json
{
"name": "MCC blacklist",
"mcc": [
5813,
5993
],
"status": "VALIDATED",
"isWhitelist": false
}It returns the MCC Restriction Group object if successful:
json
{
"mccRestrictionGroups": [
{
"id": 45599,
"name": "MCC blacklist",
"isWhitelist": false,
"mcc": [
5813,
5993
],
"status": "VALIDATED",
"startDate": "2023-10-31 08:58:50",
"createdDate": "2023-10-31 08:58:50",
"modifiedDate": ""
}
]
}Later on, you'll need the id to take into account the restriction during the card creation.
Country restrictions
Defining specific countries allows you to easily define if the card should be used in certain countries only (or, to blacklist some countries).
Here are the attributes you need to create a Country restriction group.
| 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. |
To create country restrictions, 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} to create a single-country whitelist restriction:
json
{
"name": "Spanish only cards",
"countries": [
"724"
],
"status": "VALIDATED"
}It returns the following Country Restriction Group object if successful:
json
{
"countryRestrictionGroups": [
{
"id": 165327,
"name": "Spanish only cards",
"isWhitelist": true,
"countries": [
"724"
],
"status": "VALIDATED",
"startDate": "2022-02-18 14:58:54",
"createdDate": "2023-10-23 12:17:26",
"modifiedDate": ""
}
]
}Later on, you'll need the id to take into account the restriction during the card creation.
Create a virtual card
To create a virtual card and attach to your user, you’ll need:
- The
walletIdof the Master Wallet - The
userIdof the end user who will use the card - The Id of the restriction groups you want to apply to your card
Main attributes
Here are the attributes you need to create a virtual card:
| Attribute | Type | Description |
|---|---|---|
userId | integer | The unique identifier of the cardholder. |
walletId | integer | The unique identifier of your company Master Wallet. |
permsGroup | string | A code indicating whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not. In this use case, it may be one of the following values:
|
cardPrint | string | It corresponds to your Card Program and the options provided with them. This information is shared with you by Treezor. |
merchantRestrictionGroupId | integer | The unique identifier of your MID restriction group if you’ve created one in the previous step. |
mccRestrictionGroupId | integer | The unique identifier of your MCC restriction group if you’ve created one in the previous step. |
countryRestrictionGroupId | integer | The unique identifier of your Country restriction group if you’ve created one in the previous step. |
Payment and ATM limits parameters
In addition, you need to define limits in order to credit the amount you want on the card.
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
0to 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 |
Best practice – ATM limit must be defined
Even if the ATM option has been deactivated for your cards, ATM limits must be defined for the card creation to be successful.
Request & Response example
To create a virtual card, use the following request:
bash
curl -X POST '{baseUrl}/v1/cards/CreateVirtual' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content: application/json' \
-d '{payload}'Here is an example of {payload} to create a virtual gift card of €25 using the previously created restriction groups:
json
{
"cardPrint": "{cardPrint}",
"userId": 8290083,
"walletId": 2464676,
"permsGroup": "TRZ-CU-011",
"mccRestrictionGroupId": 95447,
"merchantRestrictionGroupId": 45599,
"countryRestrictionGroupId": 165327,
"limitAtmYear": 0,
"limitAtmMonth": 0,
"limitAtmWeek": 0,
"limitAtmDay": 1,
"limitAtmAll": 1,
"limitPaymentYear": 0,
"limitPaymentMonth": 0,
"limitPaymentWeek": 0,
"limitPaymentDay": 25,
"limitPaymentAll": 25
}It returns the Card object if successful:
json
{
"cards": [
{
"cardId": 241709,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2473310,
"mccRestrictionGroupId": 95447,
"merchantRestrictionGroupId": 45599,
"countryRestrictionGroupId": 165327,
"publicToken": "107277882",
"cardTag": "",
"statusCode": "UNLOCK",
"isLive": 0,
"pinTryExceeds": 0,
"maskedPan": "519872******4839",
"embossedName": "ALEX OAK",
"expiryDate": "2026-10-31",
"CVV": "260",
"startDate": "2023-10-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-011",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 0,
"optionForeign": 0,
"optionOnline": 1,
"optionNfc": 1,
"limitAtmYear": 0,
"limitAtmMonth": 0,
"limitAtmWeek": 0,
"limitAtmDay": 1,
"limitAtmAll": 1,
"limitPaymentYear": 0,
"limitPaymentMonth": 0,
"limitPaymentWeek": 0,
"limitPaymentDay": 25,
"limitPaymentAll": 25,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-10-31 10:37:04",
"modifiedBy": 0,
"modifiedDate": "0000-00-00 00:00:00",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}Convert a virtual card into a physical one
You can convert a virtual card into a physical one (the card will become "virtual converted", which means it will exist in both forms). When doing so, a physical card is created and delivered to the end user’s address.
Tip – The ability to create physical cards directly depends on the Card Program
The default Card Program supports both virtual and physical cards. As a result, the endpoint to create directly a physical card is not available. You must create a virtual card to convert, even if you don't plan on exposing it to your end users.
To convert a card, use the following request, with the id of the card to convert as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{cardId}/ConvertVirtual
--header 'Authorization: Bearer {accessToken}' \
--header 'Content: application/json'It returns the Card object if successful, with the virtualConverted attribute set to 1.
json
{
"cards": [
{
"cardId": 239391,
"userId": 8322635,
"walletId": 2462231,
"walletCardtransactionId": 2462233,
"mccRestrictionGroupId": 0,
"merchantRestrictionGroupId": 0,
"countryRestrictionGroupId": 0,
"publicToken": "107199750",
"cardTag": "Event-test-card",
"statusCode": "UNLOCK",
"isLive": 0,
"pinTryExceeds": 0,
"maskedPan": "519872******5608",
"embossedName": "JOHN SMITH",
"expiryDate": "2026-10-31",
"CVV": "901",
"startDate": "2023-10-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "SMITH",
"deliveryFirstname": "JOHN",
"deliveryAddress1": "33 AVENUE DE WAGRAM",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "PARIS",
"deliveryPostcode": "75017",
"deliveryCountry": "FR",
"mobileSent": "+33141358530",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-016",
"cardDesign": "13664",
"virtualConverted": 1,
"physical": 0,
"optionAtm": 1,
"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": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-10-23 13:55:34",
"modifiedBy": 945198,
"modifiedDate": "2023-10-23 14:09:18",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Event_test",
"eventAlias": "event-test-65365bb9d864b",
"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
}
]
}Retrieve a virtual card
The created virtual cards are available as an image (base64 encoded format). You can retrieve a card and expose it to your users.
To retrieve a virtual card, use the following request with the cardId as a query parameter.
bash
curl -X POST '{baseUrl}/v1/cardimages?cardId={cardId}' \
--header 'Authorization: Bearer {accessToken}' \It returns the Card Image object if successful:
json
{
"cardimages": [
{
"id": "155341",
"cardId": "239391",
"file": "/xj/base64encodedfile"
}
]
}
Security – Sensitive data storage is forbidden
You are forbidden from storing card images on your servers (except if you are PCI/DSS-certified).
Activate a card
As a security measure, all Cards are issued in an inactive state to ensure that a Card is not usable before the cardholder receives it. Inactive cards can’t be used to make any type of payment or withdrawal.
There are two possible ways to activate a card:
- Machine-to-machine – To automate the activation without any action from your end users (e.g., they directly receive the virtual card through your app).
- User-oriented – To process an end user action (when you provide in your app a way for your end users to activate the card).
In addition, you have to Enroll the card for 3DS.
Machine-to-machine activation
To activate a card, use the following request, with the id of the card to activate as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{id}/Activate
--header 'Authorization: Bearer {accessToken}'It returns the Card object if successful, with the isLive attribute set to 1.
json
{
"cards": [
{
"cardId": 244989,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2487810,
"mccRestrictionGroupId": 0,
"merchantRestrictionGroupId": 0,
"countryRestrictionGroupId": 0,
"publicToken": "107290575",
"cardTag": "",
"statusCode": "UNLOCK",
"isLive": 1,
"pinTryExceeds": 0,
"maskedPan": "519872******8922",
"embossedName": "ALEX OAK",
"expiryDate": "2026-11-30",
"CVV": "843",
"startDate": "2023-11-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-011",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 0,
"optionForeign": 0,
"optionOnline": 1,
"optionNfc": 1,
"limitAtmYear": 0,
"limitAtmMonth": 0,
"limitAtmWeek": 0,
"limitAtmDay": 1,
"limitAtmAll": 1,
"limitPaymentYear": 0,
"limitPaymentMonth": 0,
"limitPaymentWeek": 0,
"limitPaymentDay": 25,
"limitPaymentAll": 25,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-11-13 12:40:35",
"modifiedBy": 945198,
"modifiedDate": "2023-11-13 13:41:27",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}User-oriented activation
To activate a card, use the following request, with the publicToken of the card to activate as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{cardToken}/public-token-activation \
--header 'Authorization: Bearer {accessToken}'It returns the Card object if successful, with the isLive attribute set to 1.
json
{
"cards": [
{
"cardId": 244989,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2487810,
"mccRestrictionGroupId": 0,
"merchantRestrictionGroupId": 0,
"countryRestrictionGroupId": 0,
"publicToken": "107290575",
"cardTag": "",
"statusCode": "UNLOCK",
"isLive": 1,
"pinTryExceeds": 0,
"maskedPan": "519872******8922",
"embossedName": "ALEX OAK",
"expiryDate": "2026-11-30",
"CVV": "843",
"startDate": "2023-11-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-011",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 0,
"optionForeign": 0,
"optionOnline": 1,
"optionNfc": 1,
"limitAtmYear": 0,
"limitAtmMonth": 0,
"limitAtmWeek": 0,
"limitAtmDay": 1,
"limitAtmAll": 1,
"limitPaymentYear": 0,
"limitPaymentMonth": 0,
"limitPaymentWeek": 0,
"limitPaymentDay": 25,
"limitPaymentAll": 25,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-11-13 12:40:35",
"modifiedBy": 945198,
"modifiedDate": "2023-11-13 13:41:27",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}Enroll the card for 3D Secure
Enrolling the card with the 3DS protocol will ensure the payment isn't declined if strong customer authentication is triggered during an online payment.
To enroll a card for 3DS, use the following request:
bash
curl -X POST {baseUrl}/v1/cards/Register3DS
--header 'Authorization: Bearer {accessToken}' \
--header 'Content: application/json' \
-d '{payload}With the {payload} containing the cardId:
json
{
"cardId": 241709
}An HTTP 200 response confirms the operation.
Manage cards
You can manage and update the cards after their creation. Here are a few actions that may prove useful to your use case:
Update card options
To update the card options, use the following request with the id of the card to update as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{id}/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
}It returns the Card object if successful:
json
{
"cards": [
{
"cardId": 241709,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2473310,
"mccRestrictionGroupId": 0,
"merchantRestrictionGroupId": 0,
"countryRestrictionGroupId": 0,
"publicToken": "107277882",
"cardTag": "",
"statusCode": "UNLOCK",
"isLive": 1,
"pinTryExceeds": 0,
"maskedPan": "519872******4839",
"embossedName": "ALEX OAK",
"expiryDate": "2026-10-31",
"CVV": "260",
"startDate": "2023-10-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-016",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 1,
"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": 2500,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-10-31 10:37:04",
"modifiedBy": 945198,
"modifiedDate": "2023-11-07 15:34:33",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}Information – Options are correlated with the permsGroup parameter
When updating your card options, the Card Permission Group is automatically updated as well.
Update card limits
To update the card limits, use the following request with the id of the card to update as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{id}/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":1,
"limitAtmDay":0
}It returns the Card object if successful:
json
{
"cards": [
{
"cardId": 241709,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2473310,
"mccRestrictionGroupId": 0,
"merchantRestrictionGroupId": 0,
"countryRestrictionGroupId": 0,
"publicToken": "107277882",
"cardTag": "",
"statusCode": "UNLOCK",
"isLive": 1,
"pinTryExceeds": 0,
"maskedPan": "519872******4839",
"embossedName": "ALEX OAK",
"expiryDate": "2026-10-31",
"CVV": "260",
"startDate": "2023-10-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-016",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 1,
"optionForeign": 1,
"optionOnline": 1,
"optionNfc": 1,
"limitAtmYear": 2000,
"limitAtmMonth": 2000,
"limitAtmWeek": 2000,
"limitAtmDay": 1000,
"limitAtmAll": 0,
"limitPaymentYear": 5000,
"limitPaymentMonth": 0,
"limitPaymentWeek": 3000,
"limitPaymentDay": 2000,
"limitPaymentAll": 2500,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-10-31 10:37:04",
"modifiedBy": 945198,
"modifiedDate": "2023-11-07 15:34:33",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}Update card restrictions
To update the card restrictions, use the following request with the id of the card to update as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{id}
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is an example of {payload}, which contains each of the possible restriction groups:
json
{
"mccRestrictionGroupId": 95447,
"merchantRestrictionGroupId": 45599,
"countryRestrictionGroupId": 165327
}It returns the Card object if successful:
json
{
"cards": [
{
"cardId": 241709,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2473310,
"mccRestrictionGroupId": 45633,
"merchantRestrictionGroupId": 95988,
"countryRestrictionGroupId": 165327,
"publicToken": "107277882",
"cardTag": "",
"statusCode": "UNLOCK",
"isLive": 1,
"pinTryExceeds": 0,
"maskedPan": "519872******4839",
"embossedName": "ALEX OAK",
"expiryDate": "2026-10-31",
"CVV": "260",
"startDate": "2023-10-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-016",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 1,
"optionForeign": 1,
"optionOnline": 1,
"optionNfc": 1,
"limitAtmYear": 2000,
"limitAtmMonth": 2000,
"limitAtmWeek": 2000,
"limitAtmDay": 1000,
"limitAtmAll": 0,
"limitPaymentYear": 5000,
"limitPaymentMonth": 0,
"limitPaymentWeek": 3000,
"limitPaymentDay": 2000,
"limitPaymentAll": 2500,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-10-31 10:37:04",
"modifiedBy": 945198,
"modifiedDate": "2023-11-07 16:29:52",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}Block a card
If you suspect fraud or misuse, the API allows you to temporarily or permanently block a card, effective immediately.
The lockStatus attribute allows you to set the desired statusCode for the card, hence choosing to block it in a way that is relevant to the encountered situation.
| 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 |
To block a card, use the following request with the id of the card to block as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{id}/LockUnlock
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is an example of {payload} setting the lockStatus to locked (temporarily):
json
{
"lockStatus":1
}It returns the Card object if successful, with the updated statusCode (displayed a plaintext value):
json
{
"cards": [
{
"cardId": 241709,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2473310,
"mccRestrictionGroupId": 45633,
"merchantRestrictionGroupId": 95988,
"countryRestrictionGroupId": 165327,
"publicToken": "107277882",
"cardTag": "",
"statusCode": "LOCK",
"isLive": 1,
"pinTryExceeds": 0,
"maskedPan": "519872******4839",
"embossedName": "ALEX OAK",
"expiryDate": "2026-10-31",
"CVV": "260",
"startDate": "2023-10-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-016",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 1,
"optionForeign": 1,
"optionOnline": 1,
"optionNfc": 1,
"limitAtmYear": 2000,
"limitAtmMonth": 2000,
"limitAtmWeek": 2000,
"limitAtmDay": 1000,
"limitAtmAll": 0,
"limitPaymentYear": 5000,
"limitPaymentMonth": 0,
"limitPaymentWeek": 3000,
"limitPaymentDay": 2000,
"limitPaymentAll": 2500,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": null,
"createdBy": 945198,
"createdDate": "2023-10-31 10:37:04",
"modifiedBy": 945198,
"modifiedDate": "2023-11-07 17:01:40",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}Handle the end of the gift card life cycle
Once the gift card is used by the end user (totalPaymentAll is reached), and if this was a one-time use card, you need to perform the following actions:
Check the card has been used
Because you’ve defined the card amount using the limitPaymentAll parameter, you can use the cardtransaction.create webhook to be notified once the card has been used.
In such cases, the totalPaymentAll value equals the limitPaymentAll.
Here is an example of cardtransaction.create webhook using fully the gift card available amount:
json
{
"webhook":"cardtransaction.create",
"webhook_id":"42xxxxxx7",
"object":"cardtransaction",
"object_id":"8xxxxxx5",
"object_payload": {
"cardtransactions":[
{
// [...] some attributes are hidden
"limitPaymentAll": "25.00",
"totalPaymentAll": "25.00",
"paymentAmount":"25.00",
"paymentStatus":"A",
"authorizationNote":"",
"authorizationResponseCode":"0",
// [...] some attributes are hidden
}
]
},
"object_payload_signature": "2rshbUX7b2xtxPOYKgHKvvDx9MA/19Aep07yzSpDm5U="
}Destroy the card
Once the card has been used, you must destroy it by updating its status accordingly (see Block a card section for more information on card statuses).
To destroy a card, use the following request with the id of the card to destroy as a path parameter:
bash
curl -X PUT {baseUrl}/v1/cards/{cardId}/LockUnlock
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'And in the {payload}, set the lockStatus to 4 for DESTROYED:
json
{
"lockStatus":4
}It returns the Card object if successful, with the updated statusCode (displayed a plaintext value):
json
{
"cards": [
{
"cardId": 241709,
"userId": 8290083,
"walletId": 2464676,
"walletCardtransactionId": 2473310,
"mccRestrictionGroupId": 45633,
"merchantRestrictionGroupId": 95988,
"countryRestrictionGroupId": 165327,
"publicToken": "107277882",
"cardTag": "",
"statusCode": "DESTROYED",
"isLive": 1,
"pinTryExceeds": 0,
"maskedPan": "519872******4839",
"embossedName": "ALEX OAK",
"expiryDate": "2026-10-31",
"CVV": "260",
"startDate": "2023-10-23",
"endDate": "0000-00-00",
"countryCode": "FR",
"currencyCode": "EUR",
"lang": null,
"deliveryTitle": "M",
"deliveryLastname": "OAK",
"deliveryFirstname": "ALEX",
"deliveryAddress1": "15 EDGEWOOD ROAD",
"deliveryAddress2": "",
"deliveryAddress3": "",
"deliveryCity": "ROSEWOOD",
"deliveryPostcode": "12365",
"deliveryCountry": "FR",
"mobileSent": "+33633333333",
"limitsGroup": "TRZ-VL-001",
"permsGroup": "TRZ-CU-016",
"cardDesign": "13664",
"virtualConverted": 0,
"physical": 0,
"optionAtm": 1,
"optionForeign": 1,
"optionOnline": 1,
"optionNfc": 1,
"limitAtmYear": 2000,
"limitAtmMonth": 2000,
"limitAtmWeek": 2000,
"limitAtmDay": 1000,
"limitAtmAll": 0,
"limitPaymentYear": 5000,
"limitPaymentMonth": 0,
"limitPaymentWeek": 3000,
"limitPaymentDay": 2000,
"limitPaymentAll": 2500,
"paymentDailyLimit": 0.0,
"totalAtmYear": null,
"totalAtmMonth": null,
"totalAtmWeek": null,
"totalAtmDay": null,
"totalAtmAll": null,
"totalPaymentYear": null,
"totalPaymentMonth": null,
"totalPaymentWeek": null,
"totalPaymentDay": null,
"totalPaymentAll": 2500,
"createdBy": 945198,
"createdDate": "2023-10-31 10:37:04",
"modifiedBy": 945198,
"modifiedDate": "2023-11-07 17:01:40",
"renewalType": "A",
"renewalDate": null,
"originalCardId": null,
"totalRows": null,
"designCode": null,
"cardLanguages": "",
"eventName": "Master Wallet",
"eventAlias": "master-wallet-6537b83040735",
"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
}
]
}Deactivate the user
For legal reasons, Users cannot be deleted. They are permanently “Canceled” instead.
To cancel a user, use the following request with the id of the user to cancel as a path parameter:
bash
curl -X DELETE {baseUrl}/v1/users/{userId} \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'In the {payload}, specify the mandatory origin parameter to OPERATOR, indicating you’re at the origin of the cancellation.
json
{
"origin": "OPERATOR"
}It returns a User object if successful, with the userStatus set to CANCELED:
json
{
"users": [
{
"userId": 8327278,
"userTypeId": 1,
"userStatus": "CANCELED",
"userTag": "",
"parentUserId": 0,
"parentType": "",
"controllingPersonType": 0,
"employeeType": 0,
"specifiedUSPerson": 0,
"title": "",
"firstname": "Alex",
"lastname": "Oak",
"middleNames": "",
"birthday": "1982-05-31",
"email": "alex.oak@example.com",
"address1": "33 rosewood road",
"address2": "",
"postcode": "75017",
"city": "Paris",
"state": "",
"country": "FR",
"countryName": "France",
"phone": "+3311111111",
"mobile": "",
"nationality": "FR",
"nationalityOther": "",
"placeOfBirth": "Edgewood",
"birthCountry": "FR",
"occupation": "",
"incomeRange": "",
"legalName": "",
"legalNameEmbossed": "",
"legalRegistrationNumber": "",
"legalTvaNumber": "",
"legalRegistrationDate": "0000-00-00",
"legalForm": "",
"legalShareCapital": 0,
"entityType": null,
"legalSector": "",
"legalAnnualTurnOver": "",
"legalNetIncomeRange": "",
"legalNumberOfEmployeeRange": "",
"effectiveBeneficiary": 0,
"kycLevel": 1,
"kycReview": 0,
"kycReviewComment": "",
"isFreezed": 0,
"isFrozen": null,
"language": "",
"optInMailing": null,
"sepaCreditorIdentifier": "",
"taxNumber": "",
"taxResidence": "",
"position": "",
"personalAssets": "",
"createdDate": "2023-10-23 12:28:00",
"modifiedDate": "0000-00-00 00:00:00",
"walletCount": 0,
"payinCount": 0,
"totalRows": "1",
"activityOutsideEu": null,
"economicSanctions": null,
"residentCountriesSanctions": null,
"involvedSanctions": null,
"address3": null,
"timezone": null,
"occupationType": "",
"isOnStockExchange": 0,
"secondaryAddress1": "",
"secondaryAddress2": "",
"secondaryAddress3": "",
"secondaryPostcode": "",
"secondaryCity": "",
"secondaryState": "",
"secondaryCountry": "",
"clientId": "945198",
"sanctionsQuestionnaireDate": null,
"codeStatus": "110009",
"informationStatus": "",
"legalSectorType": "",
"sourceOfFunds": ""
}
]
}Tip – Recreate a cancelled user with a unique email
Emails must be unique and cancellation is irreversible. So, you need to create the user again with an aliased email to allocate a gift card to cancelled users (e.g., a.oak@example.com could become a.oak+1@example.com).