Card Formats

Introduction

Card formats determine how reader output should be interpreted. There are two types of card formats:

• Standard: The standard schema contains a set of properties that determine how reader output should be interpreted. Note that this schema type is distinct from the standard property at the root of the card format object, which indicates whether a card format was provided by PDK.

• Custom: The custom js schema contains a user-defined JavaScript module, which can be used to interpret output from uncommon or proprietary readers.

The card format object

Standard

{
  "id": "d057fbaa-aa27-4905-a5af-7b610e5cc83f",
  "name": "Standard 26-bit Format",
  "schema": {
    "type": "standard",
    "num_bits": 26,
    "default_min_bits": 20,
    "default_max_bits": 32,
    "cardholder_id_bits": 16,
    "cardholder_start_address": 9,
    "num_bits_to_sum_for_even_parity": 13,
    "even_start_address": 0,
    "num_bits_to_sum_for_odd_parity": 13,
    "odd_start_address": 13,
    "facility_code": {
      "num_facility_code_bits": 8,
      "facility_start_address": 1
    }
  },
  "standard": true
}

Property	Type	Description
id	String	The card format ID.
name	String	The card format name.
schema.type	String	The card format schema type. Possible values include standard and js.
schema.num_bits	Integer	The nominal number of bits in the card number.
schema.default_min_bits	Integer	The minimum number of bits in the card number.
schema.default_max_bits	Integer	The maximum number of bits in the card number.
schema.cardholder_id_bits	Integer	The number of bits in the cardholder ID.
schema.cardholder_start_address	Integer	The starting address of the cardholder ID.
schema.num_bits_to_sum_for_even_parity	Integer	The number of bits to sum for even parity.
schema.even_start_address	Integer	The starting address for even parity.
schema.num_bits_to_sum_for_odd_parity	Integer	The number of bits to sum for odd parity.
schema.odd_start_address	Integer	The starting address for odd parity.
schema.facility_code.num_facility_code_bits	Integer	The number of bits in the facility code.
schema.facility_code.facility_start_address	Integer	The starting address of the facility code.
standard	Boolean	Whether the card format was provided by PDK. If set to true, the card format can't be deleted.

Custom

{
  "id": "8b19667b-ca5a-4029-b58d-a770f024543a",
  "name": "Test Card Format",
  "schema": {
    "type": "js",
    "default_min_bits": 9,
    "default_max_bits": 512
  },
  "cardFormat": "exports={name:'Test Card Format',parse:function(cardNumber){return cardNumber}}",
  "standard": false
}

Property	Type	Description
id	String	The card format ID.
name	String	The card format name.
schema.type	String	The card format schema type. Possible values include standard and js.
schema.default_min_bits	Integer	The minimum number of bits in the card number.
schema.default_max_bits	Integer	The maximum number of bits in the card number.
cardFormat	String	A custom JavaScript module that exports a name and parse function.
standard	Boolean	Whether the card format was provided by PDK. If set to true, the card format can't be deleted.

Basic Endpoints

Create a card format

Request

The parameters required to create a card format depend on the schema type.

Standard

POST https://systems.pdk.io/{{system_id}}/card-formats HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Card Format",
  "schema": {
    "num_bits": 26,
    "default_min_bits": 20,
    "default_max_bits": 32,
    "cardholder_id_bits": 16,
    "cardholder_start_address": 9
  }
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
system_token	Header	String	Yes	A valid system token.
name	Body	String	Yes	The card format name.
schema.num_bits	Body	Integer	Yes	The nominal number of bits in the card number.
schema.default_min_bits	Body	Integer	Yes	The minimum number of bits in the card number.
schema.default_max_bits	Body	Integer	Yes	The maximum number of bits in the card number.
schema.cardholder_id_bits	Body	Integer	Yes	The number of bits in the cardholder ID.
schema.cardholder_start_address	Body	Integer	Yes	The starting address of the cardholder ID.
schema.num_bits_to_sum_for_even_parity	Body	Integer	No	The number of bits to sum for even parity.
schema.even_start_address	Body	Integer	No	The starting address for even parity.
schema.num_bits_to_sum_for_odd_parity	Body	Integer	No	The number of bits to sum for odd parity.
schema.odd_start_address	Body	Integer	No	The starting address for odd parity.
schema.facility_code.num_facility_code_bits	Body	Integer	No	The number of bits in the facility code.
schema.facility_code.facility_start_address	Body	Integer	No	The starting address of the facility code.

Custom

POST https://systems.pdk.io/{{system_id}}/card-formats HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "cardFormat": "exports={name:'Test Card Format',parse:function(cardNumber){return cardNumber}}"
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
system_token	Header	String	Yes	A valid system token.
cardFormat	Body	String	Yes	A custom JavaScript module that exports a name function and a parse function.

Response

The response contains the ID of the newly created card format object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "8b19667b-ca5a-4029-b58d-a770f024543a"
}

Retrieve a card format

Request

GET https://systems.pdk.io/{{system_id}}/card-formats/{{card_format_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
card_format_id	Path	String	Yes	The card format ID.
system_token	Header	String	Yes	A valid system token.

Response

The response contains a card format object.

Standard

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "d057fbaa-aa27-4905-a5af-7b610e5cc83f",
  "name": "Standard 26-bit Format",
  "schema": {
    "type": "standard",
    "num_bits": 26,
    "default_min_bits": 20,
    "default_max_bits": 32,
    "cardholder_id_bits": 16,
    "cardholder_start_address": 9,
    "num_bits_to_sum_for_even_parity": 13,
    "even_start_address": 0,
    "num_bits_to_sum_for_odd_parity": 13,
    "odd_start_address": 13,
    "facility_code": {
      "num_facility_code_bits": 8,
      "facility_start_address": 1
    }
  },
  "standard": true
}

Custom

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "8b19667b-ca5a-4029-b58d-a770f024543a",
  "name": "Test Card Format",
  "schema": {
    "type": "js",
    "default_min_bits": 9,
    "default_max_bits": 512
  },
  "cardFormat": "exports={name:'Test Card Format',parse:function(cardNumber){return cardNumber}}",
  "standard": false
}

Delete a card format

Request

DELETE https://systems.pdk.io/{{system_id}}/card-formats/{{card_format_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
card_format_id	Path	String	Yes	The card format ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

List all card formats

Request

GET https://systems.pdk.io/{{system_id}}/card-formats HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
system_token	Header	String	Yes	A valid system token.

Response

The response contains an array of card format objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "d057fbaa-aa27-4905-a5af-7b610e5cc83f",
    "name": "Standard 26-bit Format",
    "schema": {
      "type": "standard",
      "num_bits": 26,
      "default_min_bits": 20,
      "default_max_bits": 32,
      "cardholder_id_bits": 16,
      "cardholder_start_address": 9,
      "num_bits_to_sum_for_even_parity": 13,
      "even_start_address": 0,
      "num_bits_to_sum_for_odd_parity": 13,
      "odd_start_address": 13,
      "facility_code": {
        "num_facility_code_bits": 8,
        "facility_start_address": 1
      }
    },
    "standard": true
  },
  {
    "id": "8b19667b-ca5a-4029-b58d-a770f024543a",
    "name": "Test Card Format",
    "schema": {
      "type": "js",
      "default_min_bits": 9,
      "default_max_bits": 512
    },
    "cardFormat": "exports={name:'Test Card Format',parse:function(cardNumber){return cardNumber}}",
    "standard": false
  }
]