# Creation

This page describe the proccesses of Card creation, delivery and activation.

Note icon

Note – Cards may be both Virtual and Physical

If your Card Program allows it, the same Card may exist in two distinct forms simultaneously (Physical and Virtual).

In such cases, it isn't possible to know which one was used for a given transaction (with the exception of physical transactions that imply a physical card).

# Creation process

# Mandatory steps

# Optional steps

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

Bulb icon

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 at the company's address by setting sendToParent value to true. If so, the envelope bears the children's complete name and the parent address.

# 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 in the form 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's 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.

Default limits may come with your Card Program, so fill in all the limits while making sure that you:

  • Set all values you don't need to 0 to deactivate them
  • Set at least one limitPayment{period} and one limitAtm{period} limit to another value than 0
Attribute Type Description
limitPaymentAll integer Lifetime payment limit
limitPaymentYear integer Yearly payment limit
limitPaymentMonth integer Monthly payment limit
limitPaymentWeek integer Weekly payment limit
limitPaymentDay integer Daily payment limit
limitAtmAll integer Lifetime withdrawal limit
limitAtmYear integer Yearly withdrawal limit
limitAtmMonth integer Monthly withdrawal limit
limitAtmWeek integer Weekly withdrawal limit
limitAtmDay integer Daily withdrawal limit

# Request example

Here is an example of {payload}:

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

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

To retrieve a virtual card, use the following request with the cardId as a query parameter.

It returns the Card Image object if successful:

Lock icon

Security – Sensitive data storage is forbidden

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

# Endpoints

# 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 station, etc. Depending on 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.

Bulb icon

Tip – Physical Cards are mailed to users

The following User attributes are required to send physical cards: title, firstname, lastname, address{1-3}, state (Idemia only), 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's 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 defined 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 prefered 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 shippings 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's 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 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 defined to 1.

Default limits may come with your Card Program, so fill in all the limits while making sure that you:

  • Set all values you don't need to 0 to deactivate them
  • Set at least one limitPayment{period} and one limitAtm{period} limit to another value than 0
Attribute Type Description
limitPaymentAll integer Lifetime payment limit
limitPaymentYear integer Yearly payment limit
limitPaymentMonth integer Monthly payment limit
limitPaymentWeek integer Weekly payment limit
limitPaymentDay integer Daily payment limit
limitAtmAll integer Lifetime withdrawal limit
limitAtmYear integer Yearly withdrawal limit
limitAtmMonth integer Monthly withdrawal limit
limitAtmWeek integer Weekly withdrawal limit
limitAtmDay integer Daily withdrawal limit
Gear icon

Configuration – Some fields are not available by default

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

Here is an example of {payload}:

Returns the Card, with its cardId (present in all CardTransactions). The Card can now be activated.

Physical Cards can be identified by the following attributes:

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

# Endpoints

Endpoint Description Scope
/v1/cards/CreateVirtual Create a new Virtual Card read_write
/v1/cards/RequestPhysical Request a new Physical Card read_write
/v1/cards/Register3DS Register a Card for 3D Secure read_write
/v1/cards/{cardId}/Activate Activate a Card initially read_write

# Bulk Creation

Gear icon

Configuration – Bulk Creation is not enabled by default

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

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

Lock icon

Attention – Card Program restrictions

Bulk Card creation is only available with a Card Program (cardPrint) of type Virtual to Physical.

# 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.
virtual boolean Defines whether the cards are to be Physical or Virtual ones.
defaultPermsGroup string A code for a preset of permissions. It indicates whether the card's 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 or not 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.

Default limits may come with your Card Program, so fill in all the limits while making sure that you:

  • Set all values you don't need to 0 to deactivate them
  • Set at least one limitPayment{period} and one limitAtm{period} limit to another value than 0
Attribute Type Description
limitPaymentAll integer Lifetime payment limit
limitPaymentYear integer Yearly payment limit
limitPaymentMonth integer Monthly payment limit
limitPaymentWeek integer Weekly payment limit
limitPaymentDay integer Daily payment limit
limitAtmAll integer Lifetime withdrawal limit
limitAtmYear integer Yearly withdrawal limit
limitAtmMonth integer Monthly withdrawal limit
limitAtmWeek integer Weekly withdrawal limit
limitAtmDay integer Daily withdrawal limit

Here is an example of {payload}.

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

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

# Follow Bulk Creations

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

Returns the following.

# 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 cardToken as printed on the back of the received Card.

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

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

# 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. A mobile phone number is required to register the card for 3D Secure. 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, it is necessary to ensure that the User was created with a mobile phone number, otherwise the User has to be updated with a mobile phone number.

This returns a Card object, but doesn't specify the 3D Secure enrolling status.

Gear icon

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

You can contact your Treezor Account Manager 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.

Gear icon

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 cutomized logo by setting its filename in the logoId parameter. This logo is overlayed to your usual Card Design.

The constraints are as follows:

  • Format: .jpeg, .pcx or .png (any other format will have to be checked for compatibility)
  • Definition: 600 PPI
  • Maximum size: depends on your Card Design
  • String: Can't exceed 30 characters
  • Transparent background is recommended. In any case, white content will not be printed.

# Back Logo (logoBackId)

You can add a cutomized logo on the backside of the Card by setting its filename in the logoBackId parameter. This logo is overlayed to your usual Card Design.

The constraints are as follows:

  • Format: .jpeg, .pcx or .png (any other format will have to be checked for compatibility)
  • Definition: 600 PPI
  • Maximum size: depends on your Card Design
  • String: Can't exceed 30 characters
  • Transparent background is recommended. In any case, white content will not be printed.

# Batch Delivery (batchDeliveryId)

Depending on your project, you may need to receive your Cards in batches. This is possible using Treezor's Batch Delivery system (batchDeliveryId).

To have multiple Cards delivered together, all the Cards need to have the same

  • batchDeliveryId of your choice,
  • delivery address.

# Packaging (packageId)

The packageId allows you to use multiple Cards Packagings with the same Card Program. This feature can also be used to handle packagings 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 on Virtual Cards, Physicial 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.

# Customized Info (customizedInfo)

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

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

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

Updated on: 5/13/2024, 8:36:53 AM