Creation

This page describes the card creation, delivery, and activation processes.

Note – Cards may be both Virtual and Physical

If your Card Program allows it, the same Card may exist in both Physical and Virtual forms. In such cases, cannot determine which form was used for a given transaction.

Process

Mandatory creation steps

• Create a Physical or Virtual Card associated with a Wallet.
• Register for 3D Secure using the dedicated endpoint.
• Activate the Card (cards are created in an inactive state; you must activate them).

Optional steps

• Define or change the Card PIN code
• Modify Card options or limits (payment limits, NFC activation, online payment, etc.)
• Update Card restrictions
• Lock or unlock the Card
• Convert a Virtual Card to a Physical one

Treezor encourages you to set all limits, options, and PIN code during the card creation to avoid additional steps.

Tip – To create cards for a company's employees:

Set the employee's (Physical User) parentUserId attribute with the userId of the company (Legal Entity). The Card can be shipped to the company's address by setting sendToParent value to true. If so, the envelope bears the child's complete name and the parent's address.

Card life cycle

Cards come with an expiryDate, indicating when the card expires and when it should be renewed. Treezor sends webhooks to better handle this situation:

• card.expiryAlert – Indicates the card expires at the end of next month.
• card.update with EXPIRED status – Indicates the card expired.

Information – Expiry alert and renewal are uncorrelated

Please note there is no correlation between the card.expiryAlert webhook and the renewal process.

Virtual Card creation

A Virtual Card is a card (with a PAN, CVC, and expiration date) that does not exist in a physical form. It is made available to the end user as an image (that looks like a Card).

It can be used for online payments.

Parameters

Here are some of the most important parameters to define when creating a Virtual Card.

Attribute	Type	Description
userId	integer	The unique identifier of the cardholder.
walletId	integer	The unique identifier of the Wallet associated with the card.
permsGroup	string	A code for a preset of permissions. It indicates whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not.
cardPrint	string	The Card Program to associate to the Card and the options provided with it. 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.
designCode	string	Customization code for the card design. If missing, falls back to the default Design Code.
cardTag	string	Custom information for you to use as you see fit. See the Object tags article.

Ensure you fill in all the limits below by setting:

• All values you don't need to 0 to deactivate them
• At least one ATM daily, weekly, or monthly limit to another value than 0
• At least one Payment daily, weekly, or monthly 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 or paymentDailyLimit	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

API – API Reference available

For a complete list of Card attributes, check the Cards section of the API Reference.

Request example

Endpoint: /v1/cards/CreateVirtual

CURL

curl -X POST '{baseUrl}/v1/cards/CreateVirtual' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

{
    "cardPrint": "{cardPrint}",
    "userId": 8290083,
    "walletId": 2464676,
    "permsGroup": "TRZ-CU-011",
    "mccRestrictionGroupId": 95447,
    "merchantRestrictionGroupId": 45599,
    "countryRestrictionGroupId": 165327,
    "limitPaymentDaily":{limitPaymentDaily},
	"limitAtmDaily":{limitAtmDaily}
}

Returns the Card object, with its cardId (present in all CardTransactions).

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": "000",	// Retrieve the CVV with cardImage or PCI DSS
            "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
        }
    ]
}

Endpoint: /cards

CURL

curl -X POST '{pciBaseUrl}/cards' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

{
    "cardPrint": "{cardPrint}",
    "userId": 8290083,
	"medium": "virtual",
    "walletId": 2464676,
    "permsGroup": "TRZ-CU-011",
    "mccRestrictionGroupId": 95447,
    "merchantRestrictionGroupId": 45599,
    "countryRestrictionGroupId": 165327,
    "limitPaymentDaily":{limitPaymentDaily},
	"limitAtmDaily":{limitAtmDaily},
	"sca": "eyJh_UxfQ.nNIH_n9kA"
}

Returns the Card object, with its cardId (present in all CardTransactions).

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": "000",	// Retrieve the CVV with cardImage or PCI DSS
            "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
        }
    ]
}

Treezor also sends a card.createvirtual webhook.

Retrieving a Virtual Card image

The created virtual cards are available as an image (base64 encoded format). You can retrieve a card and expose it to your users.

Endpoint: /v1/cardimages

CURL

curl -X GET '{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"
        }
    ]
}

Endpoint: /cards/{cardId}/cardImage

CURL

curl -X GET '{pciBaseUrl}/cards/{cardId}/cardImage' \
	--header 'Authorization: Bearer {accessToken}'

It returns the Card Image object if successful:

JSON

{
  "encryptedCardImage": "…"
}

Please refer to the Displaying sensitive data article for more information regarding the exposition of the card image.

Security – Sensitive data storage is forbidden

You are prohibited from storing card images on your servers (except if you are PCI DSS certified).

Converting to physical

Converting a card consists of turning a virtual card into a physical one. The availability of this option depends on your Card Program. When doing so, all the card information, settings, and options remain unchanged.

Information – Conversion requires a delivery address for the Physical Card

If the User doesn't already have an address defined, you have to update it beforehand.

CURL

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

Returns the Card object, with a virtualConverted attribute set to 1.

json

{
    "cards": [
        {
            "cardId": 999894952,
            "userId": 100198207,
            "walletId": 2728965,
            "walletCardtransactionId": 2905467,
            "mccRestrictionGroupId": 0,
            "merchantRestrictionGroupId": 0,
            "countryRestrictionGroupId": 0,
            "publicToken": "105608965",
            "cardTag": "Event-test-card",
            "statusCode": "UNLOCK",
            "isLive": 0,
            "pinTryExceeds": 0,
            "maskedPan": "548821******4661",
            "embossedName": "SPRINTREVIEW GRANDMA",
            "expiryDate": "2027-05-31",
            "CVV": "624",
            "startDate": "2024-05-24",
            "endDate": "0000-00-00",
            "countryCode": "FR",
            "currencyCode": "EUR",
            "lang": null,
            "deliveryTitle": "M",
            "deliveryLastname": "GRANDMA",
            "deliveryFirstname": "SPRINTREVIEW",
            "deliveryAddress1": "12 RUE DE LA LIBERTE",
            "deliveryAddress2": "",
            "deliveryAddress3": "",
            "deliveryCity": "PARIS",
            "deliveryPostcode": "7501",
            "deliveryCountry": "FR",
            "mobileSent": "+33687432367",
            "limitsGroup": "TRZ-VL-001",
            "permsGroup": "TRZ-CU-012",
            "cardDesign": "8529",
            "virtualConverted": 1,
            "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": null,
            "totalAtmMonth": null,
            "totalAtmWeek": null,
            "totalAtmDay": null,
            "totalAtmAll": null,
            "totalPaymentYear": null,
            "totalPaymentMonth": null,
            "totalPaymentWeek": null,
            "totalPaymentDay": null,
            "totalPaymentAll": null,
            "createdBy": 929252,
            "createdDate": "2024-05-14 10:28:07",
            "modifiedBy": 929252,
            "modifiedDate": "2024-05-14 10:28:20",
            "totalRows": null,
            "designCode": null,
            "cardLanguages": "",
            "eventName": "Wallet transfer",
            "eventAlias": "wallet-transfer-65eafdf301f56",
            "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
        }
    ]
}

Physical card creation

A Physical Card is a card that is shipped to the cardholder by mail and can, for example, be used in retail shops, gas stations, etc., depending on the applied restrictions.

If you want to display an image of a Physical Card to the end user, you must first create a Virtual Card and convert it to a Physical one. This allows you to show an image of the Virtual Card which bears the same PAN, CVC and expiration date.

Tip – Physical Cards are mailed to users

The following User attributes are required to send physical cards: title, firstname, lastname, address{1-3}, city, postcode and country.

Parameters

Here are some of the most important parameters to define when creating a Virtual Card.

Attribute	Type	Description
userId	integer	The unique identifier of the cardholder
walletId	integer	The unique identifier of the Wallet associated with the card.
permsGroup	string	A code for a preset of permissions. It indicates whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not.
cardPrint	string	The Card Program to associate to the Card and the options provided with it. This information is shared with you by Treezor.
anonymous	integer	Must be set to 1 if the Card is assigned to an Anonymous User.
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.
designCode	string	Customization code for the card design. If missing, falls back to the default Design Code.
cardTag	string	Custom information for you to use as you see fit. See the Object tags article.
pin	string	The Card PIN code. Treezor recommends you set this value when creating the card, but if not, a random value is set by default.
cardLanguages	string	Specifies a maximum of 4 preferred languages used to communicate with the cardholder on ATMs. Expected as ISO 639-1 (code alpha-2) concatenated by priority (e.g., nrfrenes for Dutch 1st, French 2nd, English 3rd, Spanish 4th).
batchDeliveryId	integer	Allows you to group Cards shipping together by specifying the same delivery ID to multiple Cards.
logoId	string	Allows you to add a logo on the Card by specifying the file's name.
logoBackId	string	Allows you to add a logo on the backside of the Card by specifying the file's name.
packageId	string	Allows you to customize the Card packaging.
customizedInfo	string	Allows you to add text on the Card.
freeCustomizedInfo	string	Allows you to add more text on the Card.
letterCustomizedInfo	string	Allows you to add text on letter that accompanies the Card.
embossLegalName	boolean	Allows you to emboss the User's legalName on the Card in addition to the cardholder's name, if defined to true.
sendToParent	integer	Allows you to send the Card to the parent User, if set to 1.

Ensure you fill in all the limits below by setting:

• All values you don't need to 0 to deactivate them
• At least one ATM daily, weekly, or monthly limit to another value than 0
• At least one Payment daily, weekly, or monthly 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 or paymentDailyLimit	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

Configuration – Some fields are not available by default

Contact your Treezor Account Manager to set the batchDeliveryId, customizedInfo, freeCustomizedInfo, letterCustomizedInfo, logoId, logoBackId, and packageId.

Request

Endpoint: /v1/cards/RequestPhysical

CURL

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

Here is an example of {payload}:

JSON

{
    "userId":{userId},
	"walletId":{walletId},
	"permsGroup":"TRZ-CU-016",
	"cardPrint":{cardPrint},
	"cardTag":"This field can be populated as you see fit",
	"limitPaymentDaily":{limitPaymentDaily},
	"limitAtmDaily":{limitAtmDaily}
}

Returns the Card, with its cardId (available in CardTransactions).

For security reasons, cards are created in an inactive state. Once you are sure the end user has received the card, it must be activated.

JSON

 {
	"cardId": 0,
	"userId": 0,
	"walletId": 0,
	"cardTag": "string",
	"statusCode": "UNLOCK",
	"isLive": 0,
	"pinTryExceeds": 0,
	"embossedName": "string",
	"expiryDate": "string",
	"CVV": "string",
	"limitsGroup": "string",
	"permsGroup": "string",
	"cardDesign": "string",
	"virtualConverted": 0,
	"optionAtm": 0,
	"optionForeign": 0,
	"optionOnline": 0,
	"optionNfc": 0,
	"limitAtmYear": 0,
	"limitAtmMonth": 0,
	"limitAtmWeek": 0,
	"limitAtmDay": 0,
	"limitAtmAll": 0,
	"limitPaymentYear": 0,
	"limitPaymentMonth": 0,
	"limitPaymentWeek": 0,
	"limitPaymentDay": 0,
	"limitPaymentAll": 0,
	"paymentDailyLimit": 0,
	"restrictionGroupLimits": [
	{
		"paymentDailyLimit": 0,
		"mccRestrictionGroups": 0,
		"countryRestrictionGroups": 0,
		"merchantIdRestrictionGroups": 0
	}
	],
	"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,
	// [...] some attributes are hidden
}

Endpoint: /cards

CURL

curl -X POST '{pciBaseUrl}/cards' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

{
    "userId":{userId},
	"medium": "physical",
	"walletId":{walletId},
	"permsGroup":"TRZ-CU-016",
	"cardPrint":{cardPrint},
	"cardTag":"This field can be populated as you see fit",
	"limitPaymentDaily":{limitPaymentDaily},
	"limitAtmDaily":{limitAtmDaily},
	"sca": "eyJh_UxfQ.nNIH_n9kA"
}

Returns the Card, with its cardId (available in CardTransactions).

For security reasons, cards are created in an inactive state. Once you are sure the end user has received the card, it must be activated.

JSON

 {
	"cardId": 0,
	"userId": 0,
	"walletId": 0,
	"cardTag": "string",
	"statusCode": "UNLOCK",
	"isLive": 0,
	"pinTryExceeds": 0,
	"embossedName": "string",
	"expiryDate": "string",
	"CVV": "string",
	"limitsGroup": "string",
	"permsGroup": "string",
	"cardDesign": "string",
	"virtualConverted": 0,
	"optionAtm": 0,
	"optionForeign": 0,
	"optionOnline": 0,
	"optionNfc": 0,
	"limitAtmYear": 0,
	"limitAtmMonth": 0,
	"limitAtmWeek": 0,
	"limitAtmDay": 0,
	"limitAtmAll": 0,
	"limitPaymentYear": 0,
	"limitPaymentMonth": 0,
	"limitPaymentWeek": 0,
	"limitPaymentDay": 0,
	"limitPaymentAll": 0,
	"paymentDailyLimit": 0,
	"restrictionGroupLimits": [
	{
		"paymentDailyLimit": 0,
		"mccRestrictionGroups": 0,
		"countryRestrictionGroups": 0,
		"merchantIdRestrictionGroups": 0
	}
	],
	"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,
	// [...] some attributes are hidden
}

Physical Cards can be identified by the following attributes:

• physical = 1 or
• physical = 0 along with virtualConverted = 1

Treezor also sends a card.requestphysical webhook.

Expedition tracking Production-only

Treezor sends a card.expeditionTracking webhook when the card manufacturer mails the physical card, allowing you to track the expedition and inform your end users.

Expedition tracking is only available if your manufacturer is Idemia.

Bulk Creation

Depending on your use case, it may be more suitable for you to create Cards in bulk.

Please note that Bulk Card Creation automatically complies with PCI DSS if you have migrated to the PCI DSS services.

Configuration – Bulk Creation is not enabled by default

You can request access to this feature by contacting your Treezor Account Manager.

Creation

Parameters

Attribute	Type	Description
number	integer	The number of cards to be created. There may be limitations to the maximum number of cards you can create at once.
medium	integer	Defines whether the cards are to be Physical (1) or Virtual (1), or Virtual cards that can be converted into Physical ones (3).
userIdOwner	boolean	The unique identifier of the user owning the cards. Required if createUserForEach is set to false or undefined.
createUserForEach	boolean	Whether to automatically create users for each created card. Required if userIdOwner is set to false.
distributionCountry	string	The country in which the end user is using your services. Available values may vary depending on your configuration, see Distribution Country for more information. This field is only required when you operate in multiple countries and if createUserForEach is set to true.
defaultPermsGroup	string	A code for a preset of permissions. It indicates whether the card main options (contactless, online payments, withdrawals, and international payments) are activated or not.
walletTypeId	integer	The type of Wallets the cards will be associated to.
createWalletForEach	boolean	Defines whether to create one Wallet per card.
cardDeliveryAddress1	string	The first line of the delivery address for physical cards.
cardDeliveryPostCode	string	The postal code of the delivery address.
cardDeliveryCity	string	The city of the delivery address.
cardDeliveryCountry	string	The country of the delivery address.
anonymous	integer	Defines whether the cards are to belong to Anonymous Users. If so set the value to 1, otherwise 0.
cardPrint	string	The Card Program to associate to the Card and the options provided with it. This information is shared with you by Treezor.
logoId	string	Customizes the cards with a logo.
logoBackId	string	Customizes the backside of the cards with a logo by specifying the file's name.
packageId	string	Customizes the packaging of the cards.
customizedInfo	string	Adds text on the cards.
freeCustomizedInfo	string	Adds more text on the cards.
letterCustomizedInfo	string	Adds text on the letter that comes with the cards.
defaultMccRestrictionGroupId	integer	The unique identifier of the MCC Restriction Group to associate with the cards.
defaultMerchantRestrictionGroupId	integer	The unique identifier of the MID Restriction Group to associate with the cards.
defaultCountryRestrictionGroupId	integer	The unique identifier of the Country Restriction Group to associate with the cards.

Ensure you fill in all the limits below by setting:

• All values you don't need to 0 to deactivate them
• At least one ATM daily, weekly, or monthly limit to another value than 0
• At least one Payment daily, weekly, or monthly 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 or paymentDailyLimit	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

CURL

curl -X POST '{baseUrl}/core-connect/card/bulk' \
	--header 'accept: application/json' \
	--header 'authorization: Bearer {accessToken}' \
	--header 'content-type: application/json' \
	-d '{payload}'

Here is an example of {payload}.

JSON

{
	"number":5,
	"medium":2,
	"defaultPermsGroup":"TRZ-CU-016",
	"walletTypeId":10,
	"createWalletForEach":true,
	"createUserForEach":true,
	"cardDeliveryAddress1":"33 avenue Wagram",
	"cardDeliveryPostCode":"75017",
	"cardDeliveryCity":"Paris",
	"cardDeliveryCountry":"FR",
	"anonymous":1,
	"cardPrint":"8528",
	"logoId":"",
	"packageId":""
}

Answers with a 201 HTTP Status Code and returns the following:

JSON

{
	"number":5,
	"createUserForEach":true,
	"distributionCountry":"FR",
	"createWalletForEach":true,
	"walletTypeId":10,
	"medium":2,
	"cardPrint":"8528",
	"anonymous":1,
	"defaultPermsGroup":"TRZ-CU-016",
	"packageId":"",
	"logoId":"",
	"cardDeliveryAddress1":"33 avenue Wagram",
	"cardDeliveryPostCode":"75017",
	"cardDeliveryCity":"Paris",
	"cardDeliveryCountry":"FR",
	"orderId":"d1fca687-9dbd-4530-8a80-336f2b56421a",
	"status":"PENDING"
}

Bulk creations are asynchronous, therefore, you have a second endpoint to follow their progress.

Follow Bulk Creations

To follow your Bulk Creations progress, you can use the following request:

CURL

curl -X GET '{baseUrl}/core-connect/card/bulk' \
	--header 'accept: application/json' \
	--header 'authorization: Bearer {accessToken}'

Returns the following.

JSON

[
	// this represents a Bulk Creation that completed with some errors
	// more information is contained in the "errors" attribute
	{
		"orderId":"0c6251ad-6b84-4e74-a926-8a193974248d",
		"walletIdAttach":null,
		"createWalletForEach":true,
		"walletTypeId":9,
		"userIdOwner":null,
		"createUserForEach":true,
		"number":1,
		"defaultMccRestrictionGroupId":null,
		"defaultMerchantRestrictionGroupId":null,
		"defaultCountryRestrictionGroupId":null,
		"defaultPermsGroup":"TRZ-CU-003",
		"status":"COMPLETE_WITH_ERROR",
		"createdAt":"2021-09-02T14:00:59+02:00",
		"errors":[
			"[{\"code\":\"unexpected_error\",\"docurl\":\"https:\/\/developers.treezor.co\",\"type\":\"unexpected_internal_server_error\",\"message\":\"An unexpected error was raised in our server. Please try again later, if same result please contact support\"}]"
		],
		"packageId":null,
		"logoId":null,
		"anonymous":1,
		"cardPrint":"8528",
		"paymentDailyLimit":null,
		"limitPaymentAll":null,
		"limitPaymentDay":null,
		"limitPaymentWeek":null,
		"limitPaymentMonth":null,
		"limitPaymentYear":null,
		"limitAtmAll":null,
		"limitAtmDay":null,
		"limitAtmWeek":null,
		"limitAtmMonth":null,
		"limitAtmYear":null,
		"medium":2,
		"cardDeliveryAddress1":"33 avenue Wagram",
		"cardDeliveryAddress2":null,
		"cardDeliveryAddress3":null,
		"cardDeliveryPostCode":"75017",
		"cardDeliveryCity":"Paris",
		"cardDeliveryState":null,
		"cardDeliveryCountry":"FR",
		"distributionCountry": null
	},
	// this represents a Bulk Creation that succeeded without any errors
	{
		"orderId":"11520318-6c26-4207-aebb-97280a857537",
		"walletIdAttach":922972,
		"createWalletForEach":null,
		"walletTypeId":null,
		"userIdOwner":1731771,
		"createUserForEach":null,
		"number":50,
		"defaultMccRestrictionGroupId":null,
		"defaultMerchantRestrictionGroupId":null,
		"defaultCountryRestrictionGroupId":null,
		"defaultPermsGroup":"TRZ-CU-016",
		"status":"COMPLETE",
		"createdAt":"2021-08-23T10:55:28+02:00",
		"errors":[],
		"packageId":null,
		"logoId":null,
		"anonymous":1,
		"cardPrint":"8528",
		"paymentDailyLimit":null,
		"limitPaymentAll":null,
		"limitPaymentDay":null,
		"limitPaymentWeek":null,
		"limitPaymentMonth":null,
		"limitPaymentYear":null,
		"limitAtmAll":null,
		"limitAtmDay":null,
		"limitAtmWeek":null,
		"limitAtmMonth":null,
		"limitAtmYear":null,
		"medium":1,
		"cardDeliveryAddress1":null,
		"cardDeliveryAddress2":null,
		"cardDeliveryAddress3":null,
		"cardDeliveryPostCode":null,
		"cardDeliveryCity":null,
		"cardDeliveryState":null,
		"cardDeliveryCountry":null,
		"distributionCountry": null
	},
	// this represents a Bulk Creation that is still pending
	{
		"orderId":"1775d8da-2edc-46b6-87d6-948bc184511b",
		"walletIdAttach":null,
		"createWalletForEach":true,
		"walletTypeId":10,
		"userIdOwner":null,
		"createUserForEach":true,
		"number":5,
		"defaultMccRestrictionGroupId":5053,
		"defaultMerchantRestrictionGroupId":4932,
		"defaultCountryRestrictionGroupId":2410,
		"defaultPermsGroup":"TRZ-CU-016",
		"status":"PENDING",
		"createdAt":"2021-10-26T10:54:53+02:00",
		"errors":[],
		"packageId":null,
		"logoId":null,
		"anonymous":1,
		"cardPrint":"8529",
		"paymentDailyLimit":null,
		"limitPaymentAll":null,
		"limitPaymentDay":null,
		"limitPaymentWeek":null,
		"limitPaymentMonth":null,
		"limitPaymentYear":null,
		"limitAtmAll":null,
		"limitAtmDay":null,
		"limitAtmWeek":null,
		"limitAtmMonth":null,
		"limitAtmYear":null,
		"medium":1,
		"cardDeliveryAddress1":"10 avenue Vagram",
		"cardDeliveryAddress2":null,
		"cardDeliveryAddress3":null,
		"cardDeliveryPostCode":"75000",
		"cardDeliveryCity":"Paris",
		"cardDeliveryState":null,
		"cardDeliveryCountry":"FR",
		"distributionCountry": null
	}
]

Activation

As a security measure, all Cards are issued in an inactive state to ensure that a Physical Card is not usable before the cardholder receives it.

A Card in an inactive state cannot be used to make any type of payment or withdrawal.

Typically, the end user would be required to activate the card in your application by entering the publicToken as printed on the back of the received card.

CURL

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

Returns a Card object, with its isLive attribute set to 1.

JSON

{
	"cardId": 0,
	"userId": 0,
	"walletId": 0,
	"walletCardtransactionId": 0,
	"mccRestrictionGroupId": 0,
	"merchantRestrictionGroupId": 0,
	"countryRestrictionGroupId": 0,
	"publicToken": "string",
	"cardTag": "string",
	"statusCode": "UNLOCK",
	"isLive": 1,	// <--- affected attribute
	// [...] some attributes are hidden
}

Users of may also activate a Card in one step, using its publicToken directly.

CURL

curl -X PUT '{baseUrl}/v1/cards/{cardToken}/public-token-activation' \
	--header 'Authorization: Bearer {accessToken}'

Also returns a Card object, with its isLive attribute set to 1.

Treezor also sends a card.activate webhook.

Enrolling a Card for 3D Secure

3D Secure provides an enhanced level of security for online (e-commerce) payments by adding the possibility to authenticate the cardholder. Registering the card for 3D Secure requires a mobile phone number. The cardholder will then be sent a secure code on their mobile phone when an authentication is required for an online payment. This code is unique for each payment and needs to be entered on the merchant's website or mobile application when prompted.

Prior to this step, your must ensure the User was created with a mobile phone number. Otherwise, the User must be updated with a mobile phone number.

CURL

curl -X POST '{baseUrl}/v1/cards/Register3DS' \
    --header 'Authorization: Bearer {accessToken}' \
    --header 'Content-Type: application/json' \
    -d '{
        "cardId": 123456
    }'

This returns a Card object, but doesn't specify the 3D Secure enrolling status. Treezor also sends a card.register3DS webhook.

Configuration – By default, 3DS SMS are sent under the name "Secure3DS"

You can contact Treezor and provide a new sender name that:

• Contains only alphanumeric characters (no spaces)
• Starts with a letter
• Is less than 12-character long

Customization

Cards can be customized with the following values.

Configuration – There is no API endpoint to manage these features.

If you are interested in customizing the cards, please contact your Treezor Account Manager.

Logo (logoId)

You can add a customized logo by setting its filename (as uploaded to the manufacturer) in the logoId parameter. This logo overlays to your usual Card Design.

The constraints are as follows:

• Format: .jpeg, .jpg, .pcx, or .png.
• Definition: 600 PPI.
• Maximum size: Depends on your Card Design.
• String: Can't exceed 30 characters.
• Accepted characters: a-z, A-Z, 0-9.
• Transparent background is recommended. In any case, white content is not printed.

Back Logo (logoBackId)

You can add a customized logo on the backside of the Card by setting its filename (as uploaded to the manufacturer) in the logoBackId parameter. This logo overlays to your usual Card Design.

The constraints are as follows:

• Format: .jpeg, .jpg, .pcx or .png.
• Definition: 600 PPI.
• Maximum size: Depends on your Card Design.
• String: Can't exceed 30 characters.
• Accepted characters: a-z, A-Z, 0-9.
• Transparent background is recommended. In any case, white content is not printed.

Card Delivery Method (deliveryMethod)

You can define the method the manufacturer uses to send the cards (e.g., delivery with or without tracking).

The possible options are to be defined with your Treezor Account Manager. They range from 0 to 9 and depend on your specific implementation with the manufacturer.

Pin Mailer (pinMailer)

You can request the card manufacturer to send the card PIN code by letter.

This requires a specific configuration of the card production chain with the manufacturer by your Treezor Account Manager. Then, this option can be activated by your Technical Account Manager or Implementation Manager.

Once the feature activated, you can define whether to use the card PIN code by letter by setting the pinMailer value to 1.

Batch Delivery (batchDeliveryId)

The Batch Delivery system lets you receive physical cards in batches if enabled. Cards with the same values for the parameters below are sent together.

Information	Description
Delivery ID	The cards must all have the same batchDeliveryId value (must be between 1 and 238327).
Address	The cards must all have the same delivery address. Please keep in mind that the card's delivery parameters default to either: The address defined at the user level The address of the parent of the user the card belongs to if the sendToParent parameter is set to 1.

Information – Batch orders are generated daily

Treezor usually sends the batch orders to the manufacturer in the afternoon. If cards with the same batchDeliveryId are created before and after the cut-off time, they are likely to be sent in 2 different batches.

Packaging (packageId)

The packageId allows you to use multiple Cards Packaging with the same Card Program. This feature can also be used to handle packaging in different languages.

This is set up between you and your Treezor Account Manager.

Designs (designCode)

The designCode allows you to use multiple Card Designs with the same Card Program. This design applies to Virtual Cards, Physical Cards, and digitized Cards.

To use a specific design, you will need to specify the designCode along with your usual cardPrintId.

The final design identification code will be a concatenation of the cardPrintId + z + designCode. Once created, Card objects returned by the API will not specify which designCode was used. It is therefore recommended that you store this information in your own databases.

Embossed name (embossedName)

Up to 2 names can be embossed on the card: the name of the cardholder (embossedName), and the name of the legal entity.

Note that some restrictions apply to the display of the names:

• Accepted characters: a-z, A-Z, 0-9, hyphen (-), and space ().
• Max. length: 20 characters. Treezor truncates the string if the limit is exceeded, starting by abbreviating the first name in the case of the embossedName.

Therefore, Treezor strongly advises you keep in mind these rules when populating the User object's firstname, lastname, and legalNameEmbossed (inherited from legalName) attributes.

Please note that regardless of the user type, you'll need the firstname, lastname, and phone (or mobile) User attributes in order to create a card.

Name of the cardholder

The name of the cardholder is embossed according to the following rules.

User type	Embossing rules
Anonymous user	embossedName returns an empty string, if the card anonymous attribute is set to 1.
Other	embossedName returns the concatenation of the firstname and lastname inherited from the User object.

Name of the legal entity

The name of the legal entity is embossed according to the following rules.

User type	Embossing rules
Physical user	legalNameEmbossed inherited from the parent user if available and if the card embossLegalName attribute is set to true.
Legal entity	legalNameEmbossed inherited from user if available and if the card embossLegalName attribute is set to true.

Please note the Card object doesn't return the legal embossed value. It is available in the legalNameEmbossed attribute of the User object, which is already truncated for embossing.

Caution – embossLegalName and customizedInfo incompatibility

Treezor sends an error if you attempt to emboss the legal name and display customized information at the same time.

Customized Info (customizedInfo)

The customizedInfo allows you to add specific text on each Card.

There is a maximum of 27 alphanumeric characters excluding !"#%'(),:;<>?@[]^ and the backtick symbol. The actual length limitation will depend on the chosen font and on the position of the text on the Card.

Caution – embossLegalName and customizedInfo incompatibility

Treezor sends an error if you attempt to emboss the legal name and display customized information at the same time.

Additional Customized Info (freeCustomizedInfo)

The freeCustomizedInfo allows you to add more specific text on each Card in a similar way to customizedInfo.

There is a maximum of 50 alphanumeric characters excluding !"#%'(),:;<>?@[]^ and the backtick symbol. The actual length limitation will depend on the chosen font and on the position of the text on the Card.

Letter Customized Info (letterCustomizedInfo)

The letterCustomizedInfo allows you to add specific text on the letter that accompanies a Card.

There is a maximum of 50 alphanumeric characters excluding !"#%'(),:;<>?@[]^ and the backtick symbol.