Create Card - Field Descriptions
The following page describes the fields that can be used in the request and returned in the response for the Create Card endpoint.
Request Fields
The following table describes the 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 form factor of the card. Valid values:
| String | Yes | ||
| cardProduct | The unique ID of the card product linked to the card. | int32 | Yes | ||
| designId | The name of the card visual design. | 1 | 50 | String | No |
| url | A QR code or delivery ID for the card. | 0 | 100 | 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 |
| cardHolder | The cardHolder object contains fields that are used to capture the details of the cardholder. | Object | Yes | ||
| 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 | 30 | String | Yes |
| middleName | Middle name of the 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. | 1 | String | Yes | |
| mobile | Mobile number of the cardholder. | 0 | 16 | String | No |
| Email address of the cardholder. | 0 | 100 | String | No | |
| address | The address object contains fields that are used to capture the cardholder's address. If no fulfilment address is supplied, this address is also used as the card delivery address. | Object | Yes | ||
| addressLine1 | First line of the address. | 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 | 20 | String | No |
| postCode | Postcode or ZIP code of the address. | 0 | 10 | String | Yes |
| country | Country of residence, as a 3-letter ISO country code, for example GBR for the UK. For a full list, see the IBAN list of country codes. | 3 | 3 | String | Yes |
| fulfilment | The fulfilment object contains fields that are used to capture a separate delivery address, where the card manufacturer should deliver the card to a different address from the cardholder address. | Object | No | ||
| addressLine1 | First line of the address. | 0 | 100 | String | Yes, if fulfilment is supplied |
| 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 | 20 | String | No |
| postCode | Postcode or ZIP code of the address. | 0 | 10 | String | Yes, if fulfilment is supplied |
| country | Country of residence, as a 3-letter ISO country code, for example GBR for the UK. For a full list, see the IBAN list of country codes. | 3 | 3 | String | Yes, if fulfilment is supplied |
| nameOnCard | The name embossed on the card. | 0 | 26 | String | Yes for physical cards. No for virtual cards and MVCs. |
| expiryDate | The expiry date, which is embossed on the card. Format YYYY-MM. | date-time | No | ||
| freetext1 | A free text field to communicate details to the card manufacturer. | 0 | 50 | String | No |
| freetext2 | A free text field to communicate details to the card manufacturer. | 0 | 50 | String | No |
| virtualCardImageDetails | The virtualCardImageDetails object contains fields that are used to capture the image details for a virtual card. | Object | No | ||
| 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%, from 1 to 5. For example, 1 is 100% and 2 is 200%. | int32 | No | ||
| manufacturingDetails | The manufacturingDetails object contains fields that are used to capture the manufacturing details for a physical card. It is optional for physical cards and not required for virtual cards and MVCs. | Object | No | ||
| deliveryMethod | The delivery method for the physical card. Valid values:
| String | Yes, if manufacturingDetails is supplied | ||
| carrierType | The carrier product design reference used by the card printer. | 0 | 30 | String | Yes, if manufacturingDetails is supplied |
| language | The language used on the card. | 0 | 2 | String | No |
| thermalLine1 | A free text field for extra information to be printed on the card. | 0 | 120 | String | No |
| thermalLine2 | A free text field for extra information to be printed on the card. | 0 | 70 | String | No |
| embossLine4 | Embossed card line 4. The actual maximum length depends on the card design. | 0 | 27 | String | No |
| vanityName | An additional title for the cardholder name, for example "Company Director". | 0 | 32 | String | No |
| imageDetails | The imageDetails object, within manufacturingDetails, contains fields that are used to capture the image details for a physical card. | Object | No | ||
| imageId | Identifies the card manufacturer's image file to be printed on the front of the card. | 0 | 16 | String | No |
| logoFrontId | Identifies the card manufacturer's logo file to be printed on the front of the card. | 0 | 30 | String | No |
| logoBackId | Identifies the card manufacturer's logo file to be printed on the back of the card, if supported. | 0 | 30 | String | No |
| activateNow | If true, the card is activated when it is created. Defaults to false for a physical card and true for a virtual card. | Boolean | No | ||
| isSingleUse | If true, the card can be used for a single spend transaction only. | Boolean | No | ||
| isNonReloadable | If true, the card can be loaded once only. | Boolean | No | ||
| language3ds | The 3DS enrolment language for the card. This must be a valid BCP 47 language tag, for example en-GB, which is the default. | String | No | ||
| oobAppUrl | The URL for out-of-band (OOB) authentication for 3DS. This applies to both Apata and Cardinal customers. | 0 | 2048 | URI | No |
| dynamicInterchange | The dynamicInterchange object contains fields that are used to set dynamic interchange for the card. | Object | No | ||
| feePercentage | The fee percentage for dynamic interchange. | Number (double) | No |
Response Fields
The following table describes the fields included in the response after successfully creating a card.
| Field | Description |
|---|---|
| publicToken | The unique identifier for the card. |
| customerReference | The external customer reference provided in the request. |
| embossName | The name embossed on the card. |
| maskedPan | The masked PAN for the card. |
| startDate | The start date of the card. Format YYYY-MM-DD. |
| expiryDate | The expiry date of the card. Format YYYY-MM-DD. |
Updated 3 days ago
Did this page help you?