API guide

The API guide will take you through the following steps to successfully create users and gift cards:

1. Create a physical user – Define your users with the required information.
2. Create a card – Create cards for your users, with their limits and restriction groups.
3. Activate the card – Activate the card for the user to be able use it.
4. Manage cards – Update your card information as needed.
5. Handle the end of lifecycle – 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:

Here is a {payload} example:

It returns a User object if successful:

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:

1. Create the card restriction groups
2. Create a virtual card
3. Convert a virtual card into a physicial one

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: true (default) – Allows only a specified list of merchants (whitelist) false – Allows all merchants except the specified list (blacklist)
merchants	array	The list of MIDs (each MID is a string).
status	array	One of the following values: VALIDATED – The restriction is active. PENDING (default) – The restriction is created but not yet active. CANCELED – The restriction has been deactivated (this is irreversible).
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:

Here is an example of {payload} to create a single-merchant whitelist restriction:

It returns a Merchant ID Restriction Group object if successful:

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: true (default) – Allows only a specified list of merchant caegories (whitelist) false – Allows all merchant categories except the specified list (blacklist)
mcc	array	The list of MCCs (each MCC is an integer).
status	array	One of the following values: VALIDATED – The restriction is active. PENDING (default) – The restriction is created but not yet active. CANCELED – The restriction has been deactivated (this is irreversible).
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:

Here is an example of {payload} to blacklist specific merchant categories:

It returns the MCC Restriction Group object if successful:

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: true (default) – Allows only a specified list of countries (whitelist) false – Allows all countries except the specified list (blacklist)
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 (opens new window)).
status	array	One of the following values: VALIDATED – The restriction is active. PENDING (default) – The restriction is created but not yet active. CANCELED – The restriction has been deactivated (this is irreversible).
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:

Here is an example of {payload} to create a single-country whitelist restriction:

It returns the following Country Restriction Group object if successful:

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 walletId of the Master Wallet
• The userId of 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's 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: TRZ-CU-011 (contactless and online payments, recommended) TRZ-CU-003 (online payments) TRZ-CU-009 (contactless payments) TRZ-CU-001 (no option activated)
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 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

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:

Here is an example of {payload} to create a virtual gift card of €25 using the previously created restriction groups:

It returns the Card object if successful:

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:

It returns the Card object if successful, with the virtualConverted attribute set to 1.

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.

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

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 receives 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:

It returns the Card object if successful, with the isLive attribute set to 1.

User-oriented activation

To activate a card, use the following request, with the id of the card to activate as a path parameter:

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:

With the {payload} containing the cardId:

A 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
• Update card limits
• Update card restrictions
• Block a card

Update card options

To update the card options, use the following request with the id of the card to update as a path parameter:

Here is an example of {payload}:

It returns the Card object if successful:

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:

Here is an example of {payload}:

It returns the Card object if successful:

Update card restrictions

To update the card restrictions, use the following request with the id of the card to update as a path parameter:

Here is an example of {payload}, which contains each of the possible restriction groups:

It returns the Card object if successful:

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.

statusCode	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.	Permanently

To block a card, use the following request with the id of the card to block as a path parameter:

Here is an example of {payload} setting the lockStatus to locked (temporarily):

It returns the Card object if successful, with the updated statusCode (displayed a plaintext value):

Handle the end of the gift card lifecycle

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:

1. Destroy the card
2. Deactivate the user

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:

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:

And in the {payload}, set the lockStatus to 4 for DESTROYED:

It returns the Card object if successful, with the updated statusCode (displayed a plaintext value):

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:

In the {payload}, specify the mandatory origin parameter to OPERATOR, indicating you’re at the origin of the cancellation.

It returns a User object if successful, with the userStatus set to CANCELED:

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