Create Card - Field Descriptions

The following page details each of the fields that can be used in the request, and received in the response when using the Create Card endpoint.

Request Fields

The following table describes fields that can be included in the body of the request when creating a card.

Field

Description

Minimum Length

Maximum Length

Type

Mandatory

cardType

The type of card. Select from:

  • physical
  • virtual
  • masterVirtual

7

13

String

Yes

cardProduct

The unique ID of the card product linked to the card.

1

2147483647

int32

Yes

designId

The name of the card visual design.

1

50

String

No

customerReference

An external customer reference provided in the request.

0

25

String

No

parentCard

Where the card is a secondary card, the public token of the primary card.

9

10

String

No

expiryDate

Expiry Date. It will be embossed on the card. Format YYYY-MM.

7

7

date-time

No

freeText1

A free text field to communicate details to the card manufacturer.

1

50

String

No

freeText2

A free text field to communicate details to the card manufacturer.

1

50

String

No

nameOnCard

The name that appears on the card. Note this is mandatory for physical card types.

0

26

String

  • *Yes for physical cards,No** for MVC and virtual cards.

activateNow

If true, will set the card status as active on creation of the card. Defaults to false for a physical card. Defaults to true for a virtual card.

0

5

Boolean

No

IsSingleUse

If true, the created card is only allowed for a single spend transaction only.

0

5

Boolean

No

IsNonReloadable

If true, the card is only allowed to have a single load.

0

5

Boolean

No

language3ds

Sets the 3DS Apata Enrolment language for the card. Language must be a valid BSP-47 code. The default value is en-GB.

0

5

String

No

oobAppUrl

Enables you to set the correct URL for out-of-band (OOB) authentication processes for 3DS. This is applicable for both Apata and Cardinal customers.

0

2048

URI

No

networkSharingOptOut

Enables you specify whether the card should be opted out of the Visa Account Updater (VAU) or Automated Billing Updater (ABU), which provide merchants with account advice information.

No

Url

This value is included in the Thredd Card Generation file, in the QRCode field. For example: https://www.example.com/QRBalance/123456789
For details, see the Card Generation Interface Specifications.

0

100

String

No

cardHolder

The cardHolder object contains fields that are used to capture the details of the cardholder.

title

Title of the cardholder.

0

5

String

No

firstName

First name of the cardholder.

  • *Note:** Any unpermitted characters are removed using string cleaning when submitting this field.

0

20

String

Yes

middleName

Middle name of cardholder.

  • *Note:** Any unpermitted characters are removed using string cleaning when submitting this field.

0

30

String

No

lastName

Last name of the cardholder.

  • *Note:** Any unpermitted characters are removed using string cleaning when submitting this field.

0

30

String

Yes

dateOfBirth

Date of Birth of the cardholder. Format YYYY-MM-DD.

10

10

String

Yes

mobile

Mobile number of the cardholder.

0

16

String

No

email

Email address of the cardholder.

0

100

String

No

address

The address object contains fields that are used to capture the cardholder's address. Also used for the card purchaser's address details if no 'fulfilment' address field details are supplied.

addressLine1

First line of the address. Mandatory if ‘Address’ fields are specified.

0

100

String

Yes

addressLine2

Second line of the address.

0

100

String

No

addressLine3

Third line of the address.

0

50

String

No

city

City name.

0

50

String

No

state

State.

0

50

String

No

county

County, region or province.

0

100

String

No

postCode

Postcode / Zip code of the address.

0

10

String

Yes

country

Country of residence. This is represented as a 3-letter alphanumeric ISO country code (e.g. GBR for UK). See the IBAN list of country codes for a full list.

3

3

String

Yes

fulfilment

The fulfilment object contains fields that are used to capture the card purchaser's fulfilment address — where a separate delivery address is specified for the card manufacturer to deliver the card.

No

addressLine1

First line of the address. Mandatory if a fulfilment address is specified.

0

100

String

Yes

addressLine2

Second line of the address.

0

100

String

No

addressLine3

Third line of the address.

0

50

String

No

city

City name.

0

100

String

No

state

State.

0

100

String

No

county

County, region or province.

0

100

String

No

postCode

Postcode / Zip code of the address. Mandatory if a fulfilment address is specified.

0

16

String

Yes

country

Country of residence. This is represented as a 3-letter alphanumeric ISO country code (e.g. GBR for UK). See the IBAN list of country codes for a full list.
Mandatory if a fulfilment address is specified.

3

3

String

Yes

virtualCardImageDetails

The virtualCardImageDetails object contains fields that are used to capture the Image details required for a virtual card.

virtualCardImageId

The image ID for the virtual card.

0

16

String

No

imageSize

The image size of the virtual card as a multiple of 100%. For example, 1 is 100%, 2 is 200%.

1

5

int32

No

manufacturingDetails

The manufacturingDetails object contains fields that are used to capture the manufacturing details required for the physical card.

deliveryMethod

The delivery method for the physical card.

15

21

String

No

carrierType

Carrier Product Design reference as used by the card printer.

1

30

String

No

language

The language used on the card.

0

2

String

No

thermalLine1

Free text field which can be used for transferring extra information to be printed on the card.

0

120

String

No

thermalLine2

Free text field which can be used for transferring extra information to be printed on the card.

0

120

String

No

embossLine4

Embossed card line 4. Actual maximum length will depend on the card design.

0

27

String

No

vanityName

Additional title to the card holder name (for example "Company Director").

0

32

String

No

imageDetails

The imageDetails object contains fields that are used to capture the image details for a physical card.

imageId

Identifies the card manufacturer's image file that will be printed on the face of the card.

1

16

String

No

logoFrontId

Identifies the card manufacturer's logo file that will be printed on the face of the card.

1

30

String

No

logoBackId

Identifies the card manufacturer's logo file that will be printed on the back of the card, if supported.

1

30

String

No

Response Fields

The following table describes fields that included in the response after successfully creating a card.

FieldDescription
publicTokenThe unique identifier for the card.
customerReferenceThe external customer reference provided in the request.
embossNameThe name embossed on the card.
maskedPanThe masked PAN for the card created.
startDateThe start date of the card.
expiryDateThe expiry date of the card.