Card

Regardless of the form of the payment instrument, they are all considered cards.

There can only be one card entity per card number. The card is linked to an account and a customer. The card holds data related to the card, like card specific usage limiters and card delivery type. Similar to an account product, a card product is also predefined during implementation.

Any card product specific features like allowed transaction types, fee types, usage limiter types, BIN range and expiration period are automatically applied when a card is created via API.

Here’s a list of card level data:

• Link to customer that owns the card (customerId) and account to which it is linked to (accountId)
  • It’s required to link a card to an account and a customer during card creation.
• cardID is the Enfuce database ID for the card that is used for updates and as the main identifier in API and Data Export Files.
• Information if the card is a main or supplementary card (cardRole)
  • This is for information purposes only – it does not impact the card functionality. There can be several main cards and several supplementary cards linked to one account.
  • Note that in cases where the cardholder and account holder differ, then cardRole has to be set to supplementary. For example, when a corporate customer is linked to the account and a private customer to the card, the cardRole has to be set to supplementary.
• Card number, (Primary Account Number PAN) (maskedCardNumber)
  • Enfuce generates the card number (16 digits) from a predefined number range when the card is created. The range is based on the BIN (Bank Identification Number) range that the cards scheme has assigned to the issuer. This means that the first 6-10 numbers are predefined and the rest of the card number is randomly generated by Enfuce.
  • The full card number is PCI protected data and is only available in masked format via the API.
  • For physical cards, the card number is usually printed on the front of a payment card or printed on the back of the card, and is encoded on the magnetic stripe and chip.
• Expiration date (expiration)
  • The card expiration date determines how long the card is valid. The expiration time applies only to the card, not to the account.
  • The expiration time is determined as number of months and will be calculated from card creation.
  • For example, a card expiration is set to +36 months from creation month. Thus, a card created during March 2022 will get an expiration date of 03/2025.
• PIN
  • By default, the system will generate a random PIN during the card creation process. The PIN is available through the view PIN API and the embosser can print and send it, in which case Enfuce adds it to the embossing file.
• Set PIN options (pinStatus)
  • With this solution, the issuer can request to use either a randomly generated PIN or set a customer defined PIN. See Set PIN section.
• Information needed for the embossing of a physical card (embossing)
• Segment (segment) (optional service)
  • The issuer can determine segments that can be used e.g. when determining fee levels for different customer segments.
• Address for PIN delivery (pinAddress)
  • An optional address can be set that is only used for delivery of the physical PIN. Primary address resides on the customer entity.
• Address for Card delivery (cardAddress)
  • An optional address can be set that is only used for delivery of physical card. Primary address resides on the customer entity.
• Status (status)
  • Card status, for more information please see sections of this guide below.
• Usage limiters (usageLimits, regionAndEcommBlocking)
  • See Advanced spend controls guide for more information.

​

Card product types

• A physical card is personalised by an embosser (the card manufacturer).
• A virtual card is a digital representation of a card, including only the card number, expiry date and CVV/CVC.

Regardless of whether the card is physical or virtual, it can be tokenised. Tokens allow the card to be utilised through digital wallets.

​

Creating a card

When a card is created, it’s linked to an existing customer and account. A detailed guide on how to create a card can be found here. It should be noted that the Card API has different endpoints for creating cards depending on if the card to be created is a Visa or a Mastercard branded card and whether it is physical or virtual.

The required data when creating a card is limited to:

1. Linked account and customer (**customerId**, **accountId**)
2. Main or supplementary card (**cardRole**)
3. First and Last name of the cardholder (**firstName, lastName**)

The Card API has additional fields that can be used to convey more embossing lines for the embossing house or, if several card designs are used, to inform which plastic template should be used for specific order. Potential use of the optional fields available in the Card API should be separately agreed upon and aligned on during the implementation phase.

When Enfuce receives the card creation request, the system creates a card entity and links it to the account and customer defined in the request. The card information received (firstName, lastName, cardRole) in the creation request are captured and saved as part of the card data.

Both physical and virtual cards are available for use instantly. This means that card details (PAN#, expiration date and CVV) used for e-commerce purchases can be viewed right after the card is issued. Also both physical and virtual cards can be enrolled to digital wallets (e.g. Apple Pay or Google Pay) right after the card is issued and is in use. It should be noted that if a physical card has an initial block, it needs to be removed before the physical card is in use (activate plastic via API call).

More about plastic status can be found in the below paragraph Plastic statuses.

​

Card statuses

Card statuses present the status of a card at any point of time. The card level statuses are used to determine the status of a single card contract, i.e. card number. A single card contract status does not impact other cards linked to the same account or the account itself, but only the single card. The following card statuses are in use:

Via the Account API, the issuer can define a reason for the status change. The reason can be used to differentiate between changes that are initiated by yourself and the ones initiated by your customer. The set reason is available in both View API as well as the data export card properties file.

​

Plastic statuses (physical cards only)

The plastics are fully managed by Enfuce. While the card status represents the status of the card as a whole, Enfuce also keeps track of every physical manifestation, or plastic that has been produced of the card number. Every time a new physical card with the same number is generated, a new plastic is created in the Enfuce system. The core functionality is that Enfuce keeps track of which plastic, also called “sequence”, can be used and which can’t. The issuer can fetch the plastics with the cardID by using Get a list of plastics for given card. The following chapters will provide a more detailed description of each plastic status.

​

Locked or active

Based on the card product setup, the cards can be produced either as locked or active. Both locked and active indicate that the embossing process at Enfuce has been completed for the card and a PIN has been calculated. By default cards are produced as active which means that they are ready to be used immediately as well as enrolled to digital wallets. If card´s are produced as locked, the card cannot be used (authorisations are declined) nor enrolled to digital wallets before it’s activated via API call.

Considerations:

• The PIN can be viewed only when the plastic status is active or locked so not when it is inactive
• Reissuing of the card is possible only when the card status is active, not when it is inactive

​

Inactive

Plastic status inactive indicates that the embossing process at Enfuce has not been completed.

Considerations:

After the card creation, the issuer can change the customer’s contact details e.g. address or name when the plastic status is still inactive knowing that the changes will be taken to the card manufacturing with that current order. When the plastic status has changed to active or locked it means that the card has been sent to card manufacturing. In that case, contact details can be of course changed too, but then a new card order needs to be done.

Card order can be canceled as long as the plastic status is inactive, Update plastic

​

Closed

Closed plastic status is set when there is more than one plastic and the newer plastic has been used/activated.

​

Use case example

Customer’s name has changed and a new card with a new name has been reissued (=new plastic created):

• The old plastic is active with sequence number 1
• The new plastic is inactive with sequence number 2

Next night, Enfuce runs embossing and the plastic statuses will change. After the embossing run, the new plastic has status active to indicate it is in use. The old plastic’s status has changed from active to closed indicating it is not the latest plastic in use anymore.

• The old plastic with sequence number 1 is closed
• The new plastic with sequence number 2 is active

Although the old plastic with sequence number 1 is now closed, the cardholder may continue to use the plastic until the new plastic with sequence number 2 arrives and is taken into use.

​

Example of plastic statuses in different use cases

​

Instant issuing and plastic statuses

Instant issuing means that physical card product´s virtual form can be instantly in use. After the card onboarding, customers can enroll the card in digital wallets or start using the card credentials in e-commerce transactions immediately. This will make the onboarding journey smoother and create a more convenient user experience – no need to wait to start paying with a new card.

The default for Enfuce issuers is that physical cards can be used instantly by enrolling them to digital wallets or using the card credentials for e-com purchases. In order to enable instant usage, there will be two plastic IDs created – one as inactive and one as active. The first plastic is the virtual form and the second plastic ID is the physical card that will be manufactured.

Here is an example of how the plastic statuses will look like when a card that can be instantly in use is created:

{
"cardId": "123456",
......,
"sequenceNumber": 2,
"status": "INACTIVE"
},
{
"cardId": "123456",
......,
"sequenceNumber": 1,
"status": "ACTIVE"
}

There is one plastic as inactive and one as active. The embossing process for the inactive plastic with sequence number 2 has not yet completed so there is no PIN calculated for that card. On the following night when Enfuce will run embossing, the plastic statuses will be changed as follows:

{
"cardId": "123456",
......,
"sequenceNumber": 2,
"status": "ACTIVE"
},
{
"cardId": "123456",
......,
"sequenceNumber": 1,
"status": "CLOSED"
}

​

PIN

The PIN code is personal to the card, consisting of 4 numerical digits, and is used during card present transactions, i.e. when the physical card is inserted in or swiped at a physical terminal. The lifecycle of the PIN code consists of:

​

PIN creation

Each physical card created will have a PIN code, and it will either be a random PIN or set by the cardholder using the Set PIN API.

​

PIN distribution

PIN distribution can be either by a PIN letter and distributed physically, or delivered digitally to the card holder. Alternatively, both of these options can be used in combination.

​

PIN validation

• PIN validation can be either done online or offline.
• Offline PIN validation is done by the card chip itself before the authorisation request is initiated by the terminal to Enfuce host. If the correct PIN is entered and validated by the card, the terminal will initiate the authorisation process that also contains the results of PIN validation. In case of a wrong PIN entry, the card will decline the request and increment the offline PIN try counter on the chip.
  • The number of failed offline attempts is defined in the chip parameters with the embossing partner.
• Online PIN validation happens as part of the authorisation messages; here the entered PIN is included in the authorisation message in encrypted form and validated by Enfuce during the authorization process. Similar to the offline PIN try counter on the chip, Enfuce maintains an online PIN try counter that gets incremented for every invalid PIN validation during the authorisation process
  • The number of failed attempts is configurable at the product level (default is 3). If the third attempt is incorrect, the PIN counter will be locked. Please refer to the ‘PIN Reset’ chapter for instructions on how to reset the PIN counter.

​

PIN reset

• If the offline PIN try counter gets locked, information about that is not available as it is only known by the chip on the card. The counter is reset automatically when an authorisation with a successful online PIN validation is done.
  • So in cases when the offline PIN gets locked due to too many faulty PIN tries, the cardholder needs to do a transaction where the PIN validation is done online by inserting the correct PIN. Unfortunately, it is not self-evident which terminals do online PIN validation and it also differs per market. Based on our experience, ATMs will always do online PIN validation. So using the card at an ATM, either withdrawal or balance check, will reset the offline PIN try counter.
• If the online PIN counter has exceeded the max limit and got locked, the issuer can reset that by using Enfuce API (RESET_PIN_ATTEMPT)

​

Embossing

Card embossing refers to the manufacturing process of physical cards. During the card embossing, Enfuce shares relevant data to the embosser. This data is then saved onto the magnetic stripe, EMV chip and the visible parts of the physical card, i.e plastic template/picture and the names/text embossed on the card.

The process is initiated when a card plastic is created in Enfuce system. There are multiple use cases that trigger the manufacturing of a new plastic card:

• New card creation
• Reissuing of an existing card
• Replacement of a lost card

As the plastic is created, it is simultaneously marked to be included in the embossing process. Enfuce runs the embossing process every day at approximately 03:00 UTC. We generate embossing files that are encrypted before placed on the SFTP server from where the embossing house will process it. Embossing files are created per institution and contain all cards that have been marked for production since the previous run. Enfuce has standard embossing file formats (.xml and .json) that are used with embossing partners.

​

Embossing data

The data included in the embossing file is generated by Enfuce (e.g. PAN, expiration date, PIN) and partly provided by the issuer. Enfuce supports the issuer through giving the following information through the API and forwarding it to the embosser:

manufacturer: Enfuce can support a multi-manufacturer setup where some cards are sent to one manufacturer and some to another e.g. based on the geographic location of the customer. Information on who should manufacture the card should be provided in the card creation request.

externalLayoutCode: If there are multiple card layouts at the embosser, it is possible to store the information and Enfuce will include information of the chosen one in the embossing file. If only one layout is defined, this information is not needed.

companyName: Name of the company to which the card belongs to. The length is limited to 26 characters to ensure fit on the card. If the name cannot be fit to 26 characters, the issuer should abbreviate the name. There is no standard as to how the name should be abbreviated and issuer can use own consideration.

There is a default set of characters that are supported when card is embossed (i.e. stamped) as well as an extended set of characters available for issuers that use laser overlay that allows for laser printing. Issuer should align with embosser and Enfuce on the supported character set. Enfuce supported characters are available in the API description.

firstName: First name of the cardholder. The length is limited to 26 characters to ensure fit on the card. If the name cannot be fit to 26 characters, the issuer should abbreviate the name. There is no standard as to how the name should be abbreviated and issuer can use own consideration. One option is to abbreviate first name and keep last name complete e.g. “J. CARSON”.

There is a default set of characters that are supported when card is embossed (i.e. stamped) as well as an extended set of characters available for issuers that use laser overlay that allows for laser printing. Issuer should align with embosser and Enfuce on the supported character set. Enfuce supported characters are available in the API description.

lastName: Last name of cardholder. The length is limited to 26 characters to ensure fit on the card. If the name cannot be fit to 26 characters, the issuer should abbreviate the name. There is no standard as to how the name should be abbreviated and issuer can use own consideration. One option is to abbreviate first name and keep last name complete e.g. “J. CARSON”.

There is a default set of characters that are supported when card is embossed (i.e. stamped) as well as an extended set of characters available for issuers that use laser overlay that allows for laser printing. Issuer should align with embosser and Enfuce on the supported character set. Enfuce supported characters are available in the API description.

additionalField1 / additionalField2 / additionalField3 / additionalField4 / additionalField5: These fields can be used instead of the “Name” fields or in addition to them, depending on how many lines are supported on the plastic card. The additional fields have the same logic as the “Name” fields (length, characters supported), but if an actual name is not printed on the card, these fields enable not needing to store e.g. “Vehicle 1” type of information in name fields in the system. Usage of additional fields and the number of lines embossed and possible additional layouts need to be aligned with Enfuce and the card embosser.

Note that the embossing data is only relevant for physical cards and the information is not automatically reflected in virtual card designs.

​

Printing physical cards

Card printing refers to the manufacturing process of physical cards. During the card printing, Enfuce shares relevant data to the embosser/card manufacturer. This data is then saved onto the magnetic stripe, EMV chip and the visible parts of the physical card, i.e plastic template/picture and the names/text are printed on the card. The process starts when a card plastic is created in the system. There are multiple use cases that trigger the manufacturing of a new card:

• New card creation
• Reissuing of an existing card
• Replacing a lost card

When the plastic card is created, it is simultaneously marked to be included in the printing process. Enfuce runs the embossing process every day at approximately 03:00 UTC. We generate embossing files that are encrypted before being placed on the SFTP server from where the embossing house/card printer will process it. These files are created per institution and contain all cards that have been marked for production since the previous run. Enfuce has standard embossing file formats (.xml and .json) that are used with card printers.

​

Card printing data

The data included in the embossing file is generated by Enfuce (e.g. PAN, expiration date, PIN) and partly provided by yourself. Enfuce supports you by giving the following information through the API and forwarding it to the embosser or card printer:

**manufacturer**: Enfuce can support a multi-manufacturer setup where some cards are sent to one card manufacturer and some to another e.g. based on the geographic location of the customer. Information on who should manufacture the card should be provided in the card creation request.

externalLayoutCode: If there are multiple card layouts at the manufacturer, it is possible to store the information and Enfuce will include information of the chosen one in the embossing file. If only one layout is defined, this information is not needed.

**companyName**: Name of the company to which the card belongs to. The length is limited to 26 characters to ensure it fits on the card. If the name cannot be fit to 26 characters, the name needs to be abbreviated. There is no standard as to how the name should be abbreviated so you and your customer can use your own consideration and preference.

There is a default set of characters that are supported when card is embossed (i.e. stamped) as well as an extended set of characters available for issuers that use laser overlay that allows for laser printing. You need to align with the embosser and Enfuce on the supported character set. Enfuce-supported characters are available in the API description.

**firstName**: First name of the cardholder. The length is limited to 26 characters to ensure fit on the card. If the name cannot be fit to 26 characters, the name needs to be abbreviated. There is no standard as to how the name must be abbreviated so you and your customer can use your own consideration and preference. One option is to only print the first initial of the first name, e.g. “J. CARSON”.

There is a default set of characters that are supported when card is embossed (i.e. stamped) as well as an extended set of characters available for issuers that use laser overlay that allows for laser printing. You need to align with the embosser and Enfuce on the supported character set. Enfuce-supported characters are available in the API description.

**lastName**: Last name of cardholder. The length is limited to 26 characters to ensure fit on the card. If the name cannot be fit to 26 characters, the name needs to be abbreviated. There is no standard as to how the name must be abbreviated so you and your customer can use your own consideration and preference. One option is to only print the first initial of the first name, e.g. “J. CARSON”.

There is a default set of characters that are supported when card is embossed (i.e. stamped) as well as an extended set of characters available for issuers that use laser overlay that allows for laser printing. You need to align with the embosser and Enfuce on the supported character set. Enfuce-supported characters are available in the API description. **additionalField1 / additionalField2 / additionalField3 / additionalField4 / additionalField5**

These fields can be used instead of the “Name” fields or in addition to them, depending on how many lines are supported on the plastic card. The additional fields have the same logic as the “Name” fields (length, characters supported), but if an actual name is not printed on the card, these fields enable not needing to store e.g. “Vehicle 1” type of information in name fields in the system. Using additional fields and the number of lines embossed and possible additional layouts need to be aligned with the card printer.

Note that the embossing data is only relevant for physical cards and the information is not automatically reflected in virtual card designs.

​

Card renewal, reissuing and replacement

During the card lifecycle, there are times when a card has to be renewed, reissued or replaced. First, let’s align on the definition of each of these terms:

• Renew: A card gets renewed because the card expiry date has passed. The card number (PAN) remains the same and the expiry date is updated.
• Reissue: A card gets reissued because the old card is worn-out or broken. The card number (PAN) remains the same and the expiry date is updated.
• Replace: A card gets replaced because the previous card was lost, stolen or exposed to fraud. The card number (PAN) is re-generated and the expiry date is updated.

If a card is enrolled to a digital wallet, the card lifecycle events are also linked to the token lifecycle events. For more information see the digital wallets guide.

​

Card renewal

Card renewal is automatically triggered by Enfuce a set number of days prior to a card’s expiration. The default amount of days is 45. For example, if a card expires on 06/2022, Enfuce will trigger the renewal 45 days prior to the card expiry date 2022-06-30, i.e. 2022-05-16. Only cards that have the status ‘Card OK’ will be renewed.

When renewing the card, the card number (PAN) remains the same but the expiration date will increase and the card’s CVV2/CVC2 number will be regenerated. The PIN remains the same.

​

Card reissuing

You can trigger a card (with OK status) to be reissued through the API (REISSUE_CARD). Usually, you would trigger this because the previous plastic being worn out or broken.

When reissuing the card, the card number (PAN), expiration date and CVV2/CVC2 number will remain the same (unless there is less than 2 months left of expiration). The PIN remains the same unless ‘set PIN’ is chosen during reissuing. This means that the customer will potentially need to update the card credentials for any recurring payment orders.

​

Card replacement

In cases where the card has been lost, stolen or there are other reasons to create a new card with a new number, the **REPLACE_CARD** functionality is used. When triggering the replacement, the previous card status will be changed to Card Lost and a new card number will be created automatically. As REPLACE_CARD will change the status to LOST, the issuer is expected to change the previous card status to match what it was (for example Card stolen, Closed due to fraud).

As the card is replaced, it will remain linked to the same account and customer. Enfuce will generate a new card entity, which will get a new card number (PAN), expiration date and CVV2/CVC2. The PIN will be regenerated unless ‘set PIN’ is chosen during replacement.

​

Card production events

Card production events refer to specific event during the card life cycle. Enfuce will trigger a notification when event changes. These events can be also seen via Get Card API (field: “productionType”) and in the DWH files.