Creating a Card

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

The GPS Cards API can create two different types of cards:

  • Virtual Cards
  • Physical Cards

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

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 GPS 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 GPS Implementation process.

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 GPS Apex.

You can find examples of different Create Card payloads below:

{
  "cardType": "Physical",
  "cardProduct": "10030",
  "customerReference": "Physical Card 1",
  "cardHolder": {
    "title": "Mr",
    "firstName": "Bruce",
    "lastName": "Wayne",
    "dateOfBirth": "1988-01-01",
    "mobile": "0798765432",
    "email": "[email protected]"
  },
  "address": {
    "addressLine1": "The Bat Cave",
    "addressLine2": "1007",
    "addressLine3": "Mountain Drive",
    "city": "Gotham",
    "county": "New Jersey",
    "postCode": "GT11 8HY",
    "country": "USA"
  }
}
{
  "cardType": "Virtual",
  "cardProduct": "10030",
  "customerReference": "Virtual Card 1",
  "cardHolder": {
    "title": "Mr",
    "firstName": "Bruce",
    "lastName": "Wayne",
    "dateOfBirth": "1988-01-01",
    "mobile": "0798765432",
    "email": "[email protected]"
  },
  "address": {
    "addressLine1": "The Bat Cave",
    "addressLine2": "1007",
    "addressLine3": "Mountain Drive",
    "city": "Gotham",
    "county": "New Jersey",
    "postCode": "GT11 8HY",
    "country": "USA"
  }
}
{
  "cardType": "Physical",
  "cardProduct": "10030",
  "customerReference": "Physical Card 2",
  "cardHolder": {
    "title": "Mr",
    "firstName": "Bruce",
    "lastName": "Wayne",
    "dateOfBirth": "1988-01-01",
    "mobile": "0798765432",
    "email": "[email protected]"
  },
  "address": {
    "addressLine1": "The Bat Cave",
    "addressLine2": "1007",
    "addressLine3": "Mountain Drive",
    "city": "Gotham",
    "county": "New Jersey",
    "postCode": "GT11 8HY",
    "country": "USA"
  },
  "fulfillment": {
    "addressLine1": "Gotham Academy",
    "addressLine2": "64",
    "addressLine3": "Education Road",
    "city": "Gotham",
    "county": "New Jersey",
    "postCode": "GT41 7QW",
    "country": "USA"
  }
}

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

👍

API Explorer

See the Create a card endpoint.

Using the GPS Public Token

The GPS 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 GPS 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 GPS public token in your request to identify the card you want to view or update.

📘

Store the GPS Public Token safely

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


What’s Next
Did this page help you?