Use Case Scenarios

This section provides examples of common scenarios using the Thredd web services.

• Creating a Card

• Using Tokens

• Loading a Card

• Running Card Enquiries

• Managing Cards

• Renewing Expiring Cards

• Replacing a Lost or Stolen Card

• Registering a Cardholder for 3D Secure

• Using MFX Wallets

Creating a Card

Thredd provides web services to create a card, which can be either a physical or a virtual card. For a virtual card, Thredd may hold the card image or you can manage the image on your side; for a physical card some extra steps are involved in generating an XML file, which is sent to the Thredd Card Manufacturer Thredd instructs existing card manufacturers (that it has relationships with) to print cards. Thredd uses Secure FTP (sFTP) to send the card manufacturer a generated bulk XML file containing card details. This is sent on a daily basis, or at a frequency that can be customised for your service. The card manufacturer prints the cards and sends to the cardholder. Any white label test cards are typically sent to Thredd, the Program Manager and the Card Schemes (payment networks). for printing and sending to your customer. See the figure below.

Figure 3: Using the Card Create web service

Recommended API

The API to use to create a card depends on the requirements of your application. We recommend the following:

• To create a card, use the Card Create API: ws_CreateCard. The card can be issued in a state of active or inactive:

  • If issued as inactive, it must be activated using the Card Activate API: ws_Activate. This scenario is typical for customers who sign up for a physical card via the Internet or their mobile App.

  • If issued as active, the card can be used immediately. This scenario is typical for customers who sign up for a card via a point of sale outlet or for certain types of prepaid cards which you want your customer to be able to immediately use.

• To activate a card and load an initial balance, use the Card Activate and Load API: ws_Activate_Load.

What to look out for:

• Card status: check to confirm the card status.

• Change the status to active if required, so that a customer can start using it. You can use the Card Activate API: Ws_Activate. Alternatively, if you provide your customers with a phone activation service, you can use the Phone Activation API: Ws_Phone_Activation.

• If a card is reported as lost or stolen, or you need to temporarily block the card, you can change the status of the card using the Card Change Status API: Ws_StatusChange. If the card is temporarily frozen, for example, it has been reported as lost and is later found, you can reactivate it using the Card Change Status API: Ws_StatusChange.

• If you deactivate a card that has been reported as destroyed or stolen, for security reasons it is not possible to reactivate. You will need to issue a new card.

• Card manufacturer fields: please check with your card manufacturer for details of the fields they are expecting. For details of supported manufacturers, see Card Manufacturers.

• Address fields: make sure you populate any address fields which may be used for AWS An AVS check compares the billing address used in the transaction with the issuing bank’s address information on file for that cardholder. Depending on whether they match fully, partially, or not at all, the merchant can use that information in their decision on whether or not to accept or cancel the order. AVS is one of the most widely used fraud prevention tools in card-not-present transactions. checks.

Using Tokens

Tokens enable you to use Thredd web services without needing to store or supply the full 16-digit card primary account number (PAN). When creating a card, Thredd always returns the <publicToken> linked to the physical or virtual card. When making a web service request, instead of supplying the PAN, you can include the card's <publicToken>, together with other mandatory information.

Thredd generates two types of tokens:

• 9-digit unique random token, linked to the PAN.

• 16-digit, formed from the 3-digit identifier, plus the 9-digit token, plus the last 4 digits of the PAN.

Example:

PAN = 6752993874229367

9 digit token = 734602981

16-digit token = 712+734602981+9367 = 7127346029819367

Thredd web services can receive the 9 digit public token in the request and return it in the response. Some web services may respond with the 16-digit public token. This guide will clarify when this is the case.

Using Tokens on Mobile Devices

You can use the Mastercard Digital Enablement Service (MDES) or Visa Token Service (VTS) to manage the tokens linked to a mobile device that has been bound to a card. This is a separate Mastercard or Visa <PaymentTokenId> linked to the digital PAN (DPAN), and should not be confused with the Thredd <PublicToken> linked to the card.

You can use the following web services to manage your mobile device tokens:

• Token Device Management: WS_Token_Device_Management

• Payment Token Get: Ws_Payment_Token_Get

• Payment Token Status Change: Ws_Payment_Token_StatusChange

Loading a Card

The load card web services enable you to load funds onto a card. Your EHI mode For authorisation type of transactions, the External Host Interface (EHI) can operate in one of five modes: Gateway Processing (mode 1) the External Host maintains card balances and participates in transaction authorisation by approving or declining the transaction. Cooperative Processing (mode 2) - Thredd maintains balances and performs all types of the authorization, but the External Host can overrule in some circumstances. Full Service Processing (mode 3) - read-only data feed from the Thredd system to the Client's system. Gateway Processing with STIP (mode 4) - External Host maintains Balance (with Thredd stand-in). determines whether Thredd holds the card balance or you hold the balance on the card. See the example below for a client with Cooperative Processing (mode 2) or Full Service Processing (mode 3), where Thredd holds the balance.

Figure 4: Using the Card Load web service

When using the API, you can specify the amount to load, the load source, and other load details.

Recommended API

The API to use to load a card depends on the requirements of your application. We recommend the following:

• To load a card without activation, use Card Load: Ws_Load

• To load and activate a card at the same time, use Card Activate and Load: Ws_Activate_Load

• To unload a card (debit a specified amount or the full balance), use Card Unload: Ws_UnLoad

• To unload a card and change the card status to inactive (e.g., customer closing an account), use Card Unload and Change Status: Ws_UnLoad_StatusChange

What to look out for:

• Check card status: The load will fail if the card is flagged as invalid, lost, stolen, destroyed, expired or restricted.

• The cardholder's load limits: the load will fail if the number of load attempts or load amount exceeds the daily or period limit configured for your product.

• Load source: the load will fail if you use a load source not configured for your product (if no load sources have been set up for your product, you are able to use any load source).

Running Card Enquiries

Thredd provides web services to enable you to check the status of the card, the available balance and other card details.

Figure 5: Using the Card Enquiry web service

Recommended API

The API to use to run a card enquiry depends on your requirements. We recommend the following:

• To confirm the status of a card and the available balance, use Card Enquiry: Ws_Enquiry. This returns both live and archived cards.

• To confirm the status of all live cards linked to a customer, use Ws_Customer_Enquiry or Ws_Customer_Enquiry_V2. See Customer Enquiry.

Managing Cards

Below are examples of other common web services you can use to manage your cards:

PIN Control

• To set, retrieve, unblock and change the PIN associated with a card, use Card PIN Control: WS_PinControl.
  You can also use this to unblock the CVC2 The Card Verification Value (CVV) on a credit card or debit card is a 3 digit number on VISA, MasterCard and Discover branded credit and debit cards. Cardholder's are typically required to enter the CVV during any online or cardholder not present transactions. CVV numbers are also known as CSC numbers (Card Security Code), as well as CVV2 numbers, which are the same as CVV numbers, except that they have been generated by a 2nd generation process that makes them harder to guess. of a card or mobile device token.

Change Card Groups

You can link a card to the Thredd card groups configured for your programme (e.g. Limit Groups Velocity limit group which restricts the frequency and/or amount at which the card can be loaded or unloaded. You can view your current Limit Groups in Smart Client., MCC Group Merchant Category Code (MCC) Group. The MCC is a four-digit number used by the Card Schemes (payment networks) to define the trading category of the merchant., Fee Group Group which controls the card transaction authorisation fees. and Usage Group Group that controls where a card can be used. For example: POS or ATM.). The group determines how the card can be used and/or the types of charges that can be applied to the card.

• To change the groups linked to a card, use Card Change Groups (single): Ws_Card_Change_Groups

• To bulk change the groups for multiple cards, use Card Change Groups (Bulk): Ws_Change_Groups

What to look out for:

• If you change the velocity group for a card, this may prevent the customer using their card (e.g. POS daily limit for the existing group XXX-VL-XX is 500.00, but the new group for this card, XXX-VL-YY, has a POS daily limit of 250.00).

• You must use a group that has already been configured for you in Smart Client and in Thredd Portal (based on the information provided in your Product Setup Form The Product Setup Form is a spreadsheet that provides details of your Thredd account setup. The details are used to configure your Thredd account.). For any amendments or new groups, please contact your Account Manager.

• This change is at a card level and not a product level.

Manage Card Fees

The default fees for a card are linked to the generic Thredd product for the card, as set up for your programme. Thredd offer web service to enable you to query and apply fees to a specific card.

• To apply fees to a specific card, use the Card Apply Fees API: Ws_Generic_Fees

• To list pending fees due on a card, use the Card List Pending Fees API: Ws_List_Pending_Fees

Renewing Expiring Cards

We recommend you renew expiring cards as follows:

Figure 6: Renewing Expiring Cards

1. Use the Cards Get Expiring Soon API (Ws_Get_Card_ExpireSoon) to return a list of cards due to expire in the next month.

2. Renew any expiring soon cards using the Card Renew API: Ws_Renew_Card.

You can transfer the card balance immediately to the new card and update any linked wallet/card payment tokens at the same time.

3. Thredd returns a new Thredd public token (<PublicToken>) to use for any further actions or queries on the renewed card.

If renewal options 0, 1 or 8 are requested, then Thredd returns the existing Thredd public token and does not create a new card record.

4. If you are replacing the card with a physical card, then you need to activate the card. See Card Activate.

5. The old expiring card record will still exist in the system; any queries using the old Thredd public token will return details of the status or balance on this record.

When replacing a card, do not use the Create Card web service, with <Replacement> set to 1. This is a legacy option.

We recommend you renew any physical cards well in advance of their expiry date, so that the new cards can be sent to cardholders for them to activate and use. Once a card's expiry date has passed, the cardholder will no longer be able to use the old card for payment transactions.

When replacing a card, please be aware that when the new card is activated, Thredd will change the status of the old card to 62 restricted card.

Extending the Expiry Date

In some circumstances you may be able to extend the Thredd expiry date of a card, using the Card Extend Expiry Date API: Ws_ExtendExpiry

Replacing a Lost or Stolen Card

You can use the Card Renew API to replace a lost or stolen card.

Registering a Cardholder for 3D Secure

3D Secure (3-domain structure), also known as a payer authentication, is a security protocol that helps to prevent fraud in online credit and debit card transactions. This security feature is supported by Visa and Mastercard and is branded as ‘Verified by Visa’ and ‘Mastercard SecureCode’ respectively.

Depending on the region in which you process cards, Thredd offer a choice of Apata Apata provide an Access Control Server (ACS) that enables support for the 3D Secure cardholder authentication scheme. See: https://apata.com/ or Cardinal Commerce Cardinal Commerce provide an Access Control Server (ACS) that enables support for the 3D Secure cardholder authentication scheme. See: https://www.cardinalcommerce.com to manage 3D enrolment and authentication. We provide web services to enable you to enrol your cardholders in the 3D Secure scheme, update and delete cardholder details.

Figure 7: Using the 3D Secure cardholder enrolment web service

Recommended API

• To enrol a cardholder in 3D Secure, and add, edit or delete their credentials, use 3D Secure Enrol Credentials API: Ws_AddUpDelCredentials

• For details of additional legacy 3D Secure web services, see 3D Secure Overview.

For additional information on 3D Secure support, see our 3D Secure FAQs.

The use of 3D Secure can help prevent cardholder fraud. 3D secure authentication checks are only applicable to cardholders and merchants enrolled in this scheme. For details see the 3D Secure Guide (Apata) and 3D Secure Guide (Cardinal).

Using MFX Wallets

Thredd offers web services to enable you to create and manage eWallets. The eWallet can support multiple currencies1 Currency support is region-specific. Please check with your account manager for support in your region. and can be linked to a physical card.

• To create a wallet, use the Wallet Create API: Ws_CreateWallet

• To check the balance available on the wallet, use the Wallet Balance Enquiry API: Ws_Balance_Enquiry_Wallet

• To regenerate the wallet (e.g. for a lost or stolen card), use the Regenerate the Wallet API: ws_RegenerateWallet