Creating a Card

This section provides instructions on how to create Physical and Virtual cards using the Thredd API. A card is a payment instrument that enables your customers to process transactions.

The Thredd Cards API can create three different types of cards:

• Virtual Card
• Physical Cards
• Master Virtual Cards

The type of card you want to create is governed by what value you pass for Card Type, either Physical, Virtual, or Master Virtual.

📘

Note

Only physical cards are currently supported in the Sandbox environment. Virtual Cards will be supported in the Sandbox environment in an upcoming release.

When you have created a card with a particular card type, you can convert it to another; for example, creating a Virtual Card and converting it to a Physical card. To find out more about converting cards, see Converting a Card from Virtual to Physical.

📘

Please Note

The fulfilment object only applies to cards that have a Physical CardType as these are posted out from your designated card manufacturer.

Creating a card

Prerequisites

Ensure that your Card's Product has been set up on the Thredd Apex platform as part of implementation. Your card product ID allocates default card controls to a card as well as acts as an identifier for card design. If you are unsure of your Product ID, contact your Implementation Manager / Account Manager.

Step 1: Capture cardholder details

Before creating a card, ensure you have captured all the details relating to your customer.

Step 2: Make a Card POST request

When you have captured details for your cardholder, you can make a POST /cards request. Ensure that you have the correct cardProduct defined in the request. Your cardProduct ID will be shared with you as part of the Thredd Implementation process.

{{base-url}}/cards/

You can use the customerReference field to store any ID you have for you customer from within your own system to act as a Foreign Key between your system and Thredd Apex.

You can find examples of different Create Card payloads below:

{
    "cardType":"Physical",
    "cardProduct": 10023,
    "customerReference": "CustNo12345A",
    "activateNow": true,
    "freetext1": "Comments for the card manufacturer here",
    "freetext2": "And in this field too.",
    "nameOnCard": "Mr Johnny Bloggs",
    "isSingleUse" : "true",
    "isNonReloadable" : "false",
    "cardHolder": {
        "title": "Mr.",
        "firstName": "John",
        "middleName": "Bruce",
        "lastName": "Bloggs",
        "dateOfBirth": "1982-02-19",
        "mobile": "07755123456",
        "email": "[email protected]"
    },
    "address": {
        "addressLine1": "32 Metropolis Ave",
        "addressLine2": "Mountain Drive",
        "city": "London",
        "postCode": "SW11 2LD",
        "country": "GBR"
    },
    "fulfilment": {
          "addressLine1": "32 Metropolis Ave",
          "addressLine2": "Mountain Drive",
          "city": "London",
          "postCode": "SW11 2LD",
          "country": "GBR"
     },
     "manufacturingDetails":
     {
       "cardManufacturer": "AB Note",
        "deliveryMethod": 0,
        "carrierType": "Type 1",
        "quantity": 1,
        "language": "HU",
        "thermalLine1": "asdeoivh2neriuvnqkr",
        "thermalLine2" : "asjkfnkerjnkwe",
        "embossLine4" : "jdwncwlkejr",
        "vanityName" : "Name Mane",
             "imageDetails":
             {
                  "imageId": "An image id",
                  "logoFrontId" : "A logo ID",
                  "logoBackId": "Another logo ID"
             }
          
    
    }

}

{
     "cardHolder": {
          "title": "Mr",
          "firstName": "Jon",
          "lastName": "Smith",
          "dateOfBirth": "1982-11-03"
     },
     "address": {
          "addressLine1": "32 Western Drive",
          "postCode": "S25 2BZ",
          "country": "GBR"
     },
     "virtualCardImageDetails": {
          "virtualCardImageId": "4155",
          "imageSize": 1
     },
     "cardType": "Virtual",
     "cardProduct": 10005,
     "designId": "New Card Brand",
     "customerReference": "my ref 12345"
}

{
     "cardHolder": {
          "title": "Mr",
          "firstName": "Jon",
          "lastName": "Smith",
          "dateOfBirth": "1982-11-03"
     },
     "address": {
          "addressLine1": "32 Western Drive",
          "postCode": "S25 2BZ",
          "country": "GBR"
     },
    
     "virtualCardImageDetails": {
          "virtualCardImageId": "4155",
          "imageSize": 1
     },
     "cardType": "MasterVirtual",
     "cardProduct": 10005,
     "designId": "New Card Brand",
     "customerReference": "my ref 12345"
}

A successful response will return a 200 http code. The Thredd public token linked to the card will be returned in the response.

{
    "publicToken": "103169946",
    "customerReference": "CustNo12345A",
    "embossName": "Mr Johnny Bloggs",
    "maskedPan": "999999******0134",
    "startDate": "2023-02-28",
    "expiryDate": "2026-02-27"
}

👍

API Explorer

See the Create a card endpoint.

Using the Thredd Public Token

The Thredd Public Token is a unique 9-digit number which is assigned to the card at the time of card creation. This number is for internal use on the Thredd system only, and enables you to view details of a card and manage the cards in your programme without needing to handle the full card PAN.

When you use the API to get details of a card or set details of a card, you can include the Thredd public token in your request to identify the card you want to view or update.

📘

Store the Thredd Public Token safely

The Thredd Public Token is a primary key and must be stored safely as you will use it regularly.

What is a Master Virtual Card

A Master Virtual Card (MVC) is a virtual card that is restricted to loading and unloading to a physical 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. An MVC guarantees that the load is limited to the amount prefunded (i.e. loaded onto MVC) and gives the Programme Manager the ability to distribute funds immediately rather than having to wait for notification of each individual load into the Issuer Bank account.