# Creation
This page describe the proccesses of Card creation, delivery and activation.
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
Prerequisites
You must have an active User and an active Wallet.
The User email address must not exceed 50 characters.
# Mandatory steps
- Create a Physical or Virtual Card associated to a Wallet
- Register 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's 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 creation of the card, avoiding 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 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
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 |
# 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:
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.
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
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 |
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=1orphysical=0along withvirtualConverted=1
# Endpoints
| Endpoint | Description | Scope |
|---|---|---|
POST /v1/cards/CreateVirtual | Create a new Virtual Card | read_write |
POST /v1/cards/RequestPhysical | Request a new Physical Card | read_write |
POST /v1/cards/Register3DS | Register a Card for 3D Secure | read_write |
PUT /v1/cards/{cardId}/Activate | Activate a Card initially | read_write |
# Bulk Creation
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.
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
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 |
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.
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.
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,.pcxor.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,.pcxor.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
batchDeliveryIdof 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.
← Events Modifications →