Card Issuing and Management Technical FAQs

The card's expiry date is determined by the default card validity period specified for your card product during programme setup. There are two types of expiry dates that can be set up in our system:

• The expiry date to be printed on the card.

• An internal system expiry date, which relates to how long the card record remains valid for after it is activated.

For more information, see the Physical Cards Guide: Generated Card Elements> Calculating the Expiry Date.

The gpsExpiryDate refers to the internal system expiry date managed and held by Thredd for a card, which determines how long the card record remains valid for after it is activated. This is distinct from the regular ExpiryDate, which is the physical expiry date printed or embossed on the card itself.

Whichever expiry date is reached first will result in the card being expired.

For more information, see the Physical Cards Guide: Generated Card Elements> Calculating the Expiry Date.

Yes, as with physical cards, virtual cards also have an internal system expiry date, which is determined by the default card validity period specified for your card product during programme setup. For more information, see the Virtual Cards Guide: Virtual Card Setup.

Yes, when creating or updating a card, you can override the default product-level expiry date value. Note that this only applies to the internal system expiry date and not to any expiry date already printed on a physical card.

• Using Web Services — specify the new date in the ExpDate field of the Card Create web service.

• Using Cards API (REST) — specify the new date in the expiryDate field of the Create Card API.

After card creation, you can use the Card Activate web service to update the expiry date at the time of card activation.

If using the Cards API, the equivalent API is Replace Card to update the expiry date.

Offline spending limit parameters are the limits and rules set on an EMV chip card that allow it to process transactions without requiring real-time authorisation from the issuer. These parameters enable the card to approve transactions autonomously by using the data stored on the chip and the terminal. This is particularly useful in environments where online connectivity is unavailable, such as during transit or in remote areas.

Types of Offline Parameters:

• Offline Spending Limit: The maximum amount the card can approve for a single offline transaction.

• Cumulative Offline Limit: The total amount or number of offline transactions allowed before the card requires an online authorisation to reset the limits.

• Floor Limit: A threshold set by the merchant or acquirer, below which transactions can be processed offline.

How It Works:

The EMV chip card uses its internal logic and security features to evaluate the transaction against the offline spending parameters.

• If the transaction falls within the allowed limits, it is approved offline.

• If the limits are exceeded, the card requests an online authorisation or declines the transaction.

Configuration:

Offline spending parameters are configured for your programme during card personalisation. These parameters can be updated later using EMV scripts sent during an online transaction. For more information see the Card Chip Parameters Guide.

Offline chip spend limits are embedded directly into the chip profile. The chip profile is approved by the Card Scheme after testing. Offline card limits are typically low in order to reduce the risk of fraud. Thredd cannot increase or decrease the limits stored on the chip, because they are configured at the chip level by the card manufacturer. To increase or decrease the limits, you need to update your chip profile.

For more information, see the Chip Parameters Guide.

The offline limits on the EMV chip are reset after the last strongly authenticated transaction. This could be a transaction where the cardholder has been verified using methods like PIN, biometric authentication, or other SCA-compliant methods.

For more information, see the Physical Card Configuration Guide: Card Security Features and the Chip Parameters Guide.

The EMV script is a set of commands sent by the card issuer to an EMV chip card during a transaction. This script is used to update or modify the card's data or behaviour securely. EMV scripts are part of the EMV standard, which ensures interoperability and security for chip-based payment cards.

Thredd sends the EMV script to the card via the payment terminal during an online transaction1 The EMV script can be downloaded to the card during either a Chip and PIN transaction (where the cardholder inserts their card and enters a PIN) or during a contactless transaction. However note that this works better for a Chip and PIN transaction, as the EMV script has more time to download. During a contactless transaction, the EMV script may not have sufficient time to download.. The script is encrypted and authenticated to ensure security and prevent tampering. The execution happens during the transaction process, ensuring real-time updates. Examples of usage include: Card blocking, limits adjustments and security updates.

For more information see the Card Chip Parameters Guide.

You can configure card usage and spending limits in Thredd using card configuration options and dynamic control groups. These settings are typically defined when you first implement your card programme through your Product Setup Form (PSF) The Product Setup Form is a spreadsheet that provides details of your Thredd account setup. The details are used to configure your Thredd account., but they can also be updated dynamically through the Thredd API.

Here’s how it works:

Card Usage Configuration

You can control where and how a card can be used by assigning it to Usage Groups. For example, you can restrict usage to certain merchant types (using MCC Groups) or block specific merchants using Card Acceptor and Deny Lists.

You can also control when cards can be used by linking them to an Auth Calendar Group — for instance, to prevent usage on weekends or holidays.

Spending Limits Configuration

Spending limits are managed through Velocity Groups or Limit Groups. These define thresholds such as:

• Maximum balance

• Minimum and maximum amounts per transaction

• Daily or weekly spending limits

You can view and adjust these limits dynamically using the Thredd API or through the Thredd Portal, where you can see live card spend limits and transaction history.

For example, you could set a £600 daily spending limit or restrict ATM withdrawals to a certain number per day.

For more information on card control groups and spending limits, see Card Configuration.

Configuring the Spend Limits for a Card

For information on how to use the Thredd API to dynamically link cards to usage groups set up for your programme, see the following guides:

• Cards API Website: Introduction to Card Control Groups

• Web Services Guide: Thredd Groups and Products and Web Services Guide: Acceptor Lists

Yes, for a virtual card launch, transaction types such as AFD and Point of Sale (POS) transactions are not applicable, so you can ignore these. However, if you plan to launch physical card or implement digital wallet tokenisation (MDES The MasterCard Digital Enablement Service (MDES) is a data interchange platform for generating and managing secure digital payment tokens. It enables devices such as smartphones, smart watches, as well as merchants, to create a tokenised version of a Mastercard, which is specific to that device or merchant. Then the device/merchant can use the tokenised version of the card to perform transactions. The tokenised version of the card appears as just a normal Mastercard card number to the merchant and acquirer, and Mastercard will map the transactions onto the original cardholder Mastercard., VDEP Visa Digital Enablement Programme.  Also called the Visa Tokenisation Service (VTS).), then these types of transactions need to be supported unless you explicitly want to block them.

To deactivate a single-use card after it has been used, change the card status from Active to Inactive, as follows:

• Cards API: Use the Update Card Status API to change the cardStatusCode field value to a suitable blocked status.

• Web services: Use the Card Change Status web service to change the NewStatCode field value to a suitable blocked status.

When creating a Single Use card, ensure that the isSingleUse field is set to true.

Master Virtual Cards (MVCs) are a type of Thredd card that is restricted to loading and unloading to a physical or virtual card and cannot be used for e-commerce or in-store transactions. An MVC is used to reflect the value of the ‘actual’ money in the Issuer's bank account. The MVC can be used to hold the card balance, and the individual virtual and physical cards will draw the card balance from the linked MVC.

For more information, see the Master Virtual Cards Guide.

MVCs are supported only in EHI transaction processing modes where Thredd holds the card balance.

You can configure your virtual card image directly through the Thredd system or by generating it on your own systems — depending on how you want to manage the design and display.

• If you want Thredd to generate the virtual card image, you’ll need to complete the Virtual Card Image tab on your Product Setup Form (PSF). This allows you to customise both the background image (e.g., your brand design or colour scheme) and the dynamic text elements, such as the cardholder name, PAN, expiry date, and CVV.

• Alternatively, you can generate the virtual card image yourself using the details returned in the Create Card API response. If you are PCI-DSS compliant, Thredd can return the full PAN; otherwise, the middle six digits will be masked. You can then overlay these details on your own card design within your app or web portal.

For more information, see the Virtual Cards Guide: Virtual Card Setup.

Chinese and other language characters are supported on the following fields: FirstName, MiddleName, LastName, AddressLine1, AddressLine2 and AddressLine3.

If using REST API, string cleaning is performed on special characters that are included in the following fields for the Create Card and Update Card endpoints:

• firstName

• middleName

• lastName

• nameOnCard

The following characters will be removed for each of these fields if they are included:

;:!?<>~#%@{}|[]”

If you are using SOAP web services, note the restrictions on use of special characters, as listed on this page: String Cleaning and Approved Characters.

We recommend you test language and special character support using the create card and retrieve card API or equivalent web services prior to production release.

After a request for a card file has been sent to the manufacturer, it cannot be cancelled. However, you can destroy the tokens and issue new ones.

For more information on the card file generation process, see the Card Generation Interface Specifications: About the Card Generation File.

Only cards with one of the statuses 00, 02, or G1 are included in the card file for the card manufacturer.

For more information, see the Card Generation File Specification Guide.

Applicable to cardholders who will receive a physical card.

Preparing your artwork

The front and back artwork for your card products must first be submitted to your Card Manufacturer during your programme setup phase. The Card Manufacturer will then provide you with reference identifiers to be used to indicate the correct artwork files to use when printing the card. For information on how to set up your artwork with Thredd and your Card Manufacturer, see the Physical Cards Guide: Physical Card Customisation

Linking your artwork to a card record

If no card artwork is specified in the create card request, then the Card Manufacturer will use the default card artwork configured for your product.

When creating or updating your card using the Thredd API, add the reference identifiers provided by your Card Manufacturer to the LogoFrontId and LogoBackId fields.

• If using Web Services, see the Web Services Guide: Card Create.

• If using the Cards API, see the Cards API Website: Creating a Card.

No, if a card is changed to a stolen or destroyed status, further transactions are not permitted on the card. Status codes such as 41 (Lost card), 43 (Stolen card), and 83 (Card destroyed) are irreversible and are intended to permanently block the card from being used for any transactions. Once applied, the card cannot be reactivated or used for any transactions.

If a transaction is attempted on a stolen or destroyed card, Thredd will decline the transaction and send you an EHI 0100A message with Authorised_by_GPS=Y and TxnStatCode=I.

It may still be possible to transfer shared balances between linked cards if one of the cards is destroyed. See Primary and Secondary Cards.

For more information, see the Thredd Card Status and Response Codes Guide.

Card status 02 indicates that the card is not yet activated or is inactive. It is commonly used for newly issued cards before activation and can also appear due to certain workflows. For example, for security reasons you can choose to issue all your physical cards or gift cards in an inactive state, so that the card cannot be used until securely activated.

You can use a status code that implements a temporary block on the card, such as G1, G2, G3 or G4. This will block any further transactions on the card. Note that refunds can still be received.

For permanent (irreversible) card blocks, use card status values such as '41' (Lost Card), ‘46’ (Account Closed), ‘83’ (Card Destroyed) and ‘98’ (Refund given to customer).

For more information, see the Thredd Card Status and Response Codes Guide.

No. Thredd declines any authorisation transaction and sends you a decline message via EHI for any status other than 00.

Note that certain types of transactions, such as chargebacks, credits and refunds can still be allowed for certain card status codes. For more information, see the Card Status Codes.

You may receive some types of card transaction-related fees, for example chargeback fees if a chargeback has been raised.

A card status of G1 blocks all card transactions, however Credits (i.e. deposits) and Refunds are still allowed.

Acquirer fees do not form part of the card spend limits. Acquirer fees are usually included in the Amt_Tran_Fee_DE28 field.

Example scenario:

• Your card programme's daily spend limit for ATM cash withdrawals is set to 1000 GBP.

• ATM cash withdrawal limit is set to 250 GBP per transaction.

• The cardholder makes 4 withdrawal transactions, each for 250 GBP, totalling 1000 GBP.

• The ATM applies a withdrawal fee of 2.50 GBP per transaction.
• The acquirer reports four transactions with billing amounts of 250 GBP each. The acquirer frees (totalling 10.00 GBP) are reported separately in the Amt_Tran_Fee_DE28 field.

In this scenario, cash withdrawals totalling 1000 GBP fall within the daily velocity limits. For more information, see the EHI Guide: Troubleshooting FAQs.

Acquirer fees for balance enquiries are usually reported in the Amt_Tran_Fee_DE28 field. For more information, see the EHI Guide: Troubleshooting FAQs.

The web services WSDL file enables schema validation of Web Services. The latest WSDL file is available to download from the Downloads page.

You can use the WSDL to validate your XML messages and for testing your requests. For more information, see the Web Services Guide: Using the API.

The PaymentTokenUsageGroup is used to define the rules around digital wallet tokenisation for your card product. Thredd makes provisioning decisions on the card based on the PaymentTokenUsageGroup configuration options set for your programme. You will need multiple Payment Token Usage Groups set up on your programme, to link to configuration options for each Wallet Provider (e.g., Google, Apple) that you want to make available for the card. For more information, see the Tokenisation Guide.

In the Card Enquiry (Ws_Enquiry) and Customer Enquiry (Ws_Customer_Enquiry and Ws_Customer_Enquiry_V2) APIs, <PaymentTokenUsageGroup> contains an alphanumeric response of up to 50 characters. This comprises the unique 3-digit numeric code assigned to the payment token usage group at the time of creation and a description of the payment token usage group. For example: 123-Company XYZ Full VDEP.

<ProductID> is the identifier of your card product, or the Product ID, within Thredd. For details, check with your Implementation Manager.

<CrdProduct> is the Scheme name. For example, Visa, Mastercard or Discover.

The address object contains the cardholder's address and is used for AVS (address verification service). The fulfilment object is used only for physical cards when the delivery address of the physical card is different from the cardholder's address.

When creating cards, customerReference is used to specify an account number or reference number. It is also used to query cards on Thredd Portal Thredd Portal is Thredd's new web application for managing your cards and transactions on the Thredd Platform. or Smart Client Smart Client is Thredd's legacy desktop application for managing your account on the Thredd Platform..

For physical cards, customerReference is passed to the card manufacturer in the card file.

Cardholder details are stored at a card level. If a cardholder has many cards, the details of each card need to be updated separately.

Typically only the cardholder's Mobile (for 3D Secure) and Address (for physical card delivery) need updating. Other fields such as dateOfBirth and email are not used for any processing or validation by Thredd.

Only include the fields you want to update. Do not send blanks, else the blanks will replace the existing values. The example below shows how to update the mobile field only of the CardHolder object:

{
     "cardHolder": {          
          "mobile": "07712345679",          
     },
  }

For more information, see the Cards API Website: Updating Cardholder Details.

This field indicates the date the card record is created (example: "2025-02-28"). You can store it on your systems, but it is not used for any processing logic. For more information, see the Cards API Website: Create Card Field Descriptions.

This field determines whether the card is issued in an active status upon creation. A card that is not active cannot be used to make live transactions.

• Set to true If you want the card to be activated immediately upon creation. This is typically used for scenarios where the card needs to be ready for use right away.

• Set to false if you do not want the card to be activated immediately. This is useful for cases where the card activation is delayed for security or other operational reasons.

If left blank, then the default value is false for a physical card and true for a virtual card. See the Cards API Website: Create Card Field Descriptions.

You can activate a card using the Update Card Status endpoint. See the Cards API Website: Card Status

This field is only for use on physical cards, and determines the name that appears on the card. Keep this field blank for virtual or MVC cards. For more information, see the Cards API Website: Create Card Field Descriptions.

Yes, this will retrieve the full PAN, but note that this API is only available if you are PCI Compliant The Payment Card Industry Data Security Standard (PCI DSS) is an information security standard for organisations that handle credit cards from the major card schemes (payment networks). All Program Managers who handle customer card data must be compliant with this standard. See: https://www.pcisecuritystandards.org/pci_security/. For more information, see the Cards API Website: Get Full PAN.

If you are not PCI compliant and want to display full PAN on your cardholder's device, you can use the Retrieve an encrypted card API endpoint. For more information, see the Cards API Website: Get Card Data.

Access token validity is 4 hours in UAT and Production.

OAUTH is a legacy connection solution, and is no longer applicable for clients using mTLS. For more information on the latest secure connection options, see the Connecting to Thredd Guide.