Create Cardholder

Creates a new Cardholder account for instant issue, personalized, and secondary cards. It also allows for loading of cards at the time of creation.

This endpoint creates a Cardholder and an Account (or card) for that cardholder.

Below are general API request and response body specifications, for detailed validation requirements please check Field Validation section below.

Note: This endpoint support CIP/KYC verifications for programs that require it. In cases where CIP/KYC is required, you may need to pass the SSN/SIN number for the cardholder being created in the system and we will run a CIP/KYC verification based on the demographic data provided here (i.e., first name, last name, DOB, etc). It is also possible to send additional KYC information as part of the request, see KYC Additional Client Information (KYC_ACI) section below for more details.

Request

Field NameRequiredTypePatternDescription
program_idYesStringProgram to Create the Initial Account under
external_tagNoStringUser defined external reference field to store on Card Holder
first_nameYesStringExample: Elizabeth. See Field Validation Below.Cardholder's first name
middle_nameNoStringExample: Blaise. See Field Validation Below.Cardholder's middle name
last_nameYesStringExample: Harley. See Field Validation Below.Cardholder's last name
emboss_line2NoStringExample: 2nd Line Emboss. See Field Validation Below.Second line card emboss text.
date_of_birthSee DescriptionDateExample: 13-01-1990. See Field Validation Below.Cardholder's birth date.
address1NoStringSee Field Validation Below.
address2NoStringSee Field Validation Below.
cityYesStringExample: Salt Lake City. See Field Validation Below.Cardholder's city
stateYesStringValid 2 character state abbreviation. Example: UTCardholder's state
postal_codeYesString12345 or 12345-1234 (US), K1A-1A1 (CA). Example: 18412Cardholder's postal code (zip code)
countryYesNumberThree digit country code. Example: 840Three digit ISO numeric UN M49 country code;
USA=840, Canada=124.
phoneSee DescriptionStringValid phone number. See Field Validation Below.Cardholder's primary phone number
emailYesStringEmail Address. Example: [email protected]Cardholder's email
sinSee DescriptionStringSSN or SIN. This is a required field for U.S. programs that require a KYC verification check. It is an optional field for programs issued in Canada.

When provided, a KYC verification will be executed based on the cardholder demographic data provided as part of this API call.
shipping_methodNoStringSee table belowUse shipping method to send the new card plastic. Note that this field is not required if you are issuing Virtual Cards.
load_amountNoNumberMonetary amount greater than 0Smallest unit of the Program's currency passed as whole amounts. For example, $10.00 CAD would be sent at 1000. Initial load amount on card must be within product load limits or designated amount for Instant Issue card.
shipping_addressNoAddressSee BelowThe address the card will be shipped to. If not specified, the cardholder address will be used. Note that this only applies to physical programs.
parent_cardholder_idNoNumberID of the parent cardholder.Parent Cardholders are allowed to transfer funds to child cardholders. This feature must be enabled as part of your program.
linked_account_idNoNumberID of the linked account.Linked accounts share a balance but have separate cards. This feature must be enabled as part of your program.
subprogram_codeNoStringSubprogram to create card under.May be 'virtual' or 'physical'. This feature must be enabled as part of your program.
package_codeNoStringSpecifies card art and carrier to be used with a physical cardEach package code must be individually configured.
localeNoStringCardholder language and localization preference.Set localization and language preference with en_US, en_CA, or fr_CA.
kyc_additional_client_infoNoKYC_ACISee BelowCardholder's KYC Additional Client Information (KYC_ACI)

Shipping Address Attributes

Field NameRequiredTypePatternDescription
address1YesStringSee Field Validation Below.
address2NoStringSee Field Validation Below.
cityYesStringExample: Salt Lake City. See Field Validation Below.Cardholder's city
stateYesStringValid 2 character state abbreviation.UTCardholder's state
postal_codeYesString12345 or 12345-1234 (US), K1A-1A1 (CA)18412Cardholder's postal code (zip code)
countryYesNumberThree digit country code.840Three digit ISO numeric UN M49 country code; Example USA=840, Canada=124.
first_nameNoStringExample: Elizabeth. See Field Validation Below.Cardholder's first name
last_nameNoStringExample: Harley. See Field Validation Below.Cardholder's last name

KYC Additional Client Information (KYC_ACI)

Field NameRequiredTypePatternDescription
occupationNoStringFree text, maximum length 50 charactersCardholder's occupation
third_party_determinationNoBooleantrue / false / nullThird-party determination (Yes/No). A third party is a person or entity who instructs another person or entity to conduct an activity or financial transaction on their behalf.
foreign_tax_residencyNo (*1)Booleantrue / false / nullTax residency outside of Canada and US
foreign_tax_country_code(*2)NumberThree digit country code.840Country of Tax Residency. Same as city field.
foreign_tax_id(*2)StringTax ID in country of residence

*1 - If foreign_tax_residency is true, then the sin field is mandatory in the card create message

*2 - Required if foreign_tax_residency is true

Field Validation

Field Types

Values
AlphaNuma-z, A-Z and 0-9
Latin 1 Accented CharactersÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ
Latin 1 Special Characters,.?@&!#'~()-;+._$%&+:;¿¡

Fields

FieldCanadaUSA
First, Middle and Last NamesAlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 50 charactersAlpha, “ '-“, maximum length 30 characters
Date Of Birthdd-MM-yyyy, Requireddd-MM-yyyy, Optional
Address Line 1AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 30 charactersAlphaNum, Latin 1 Accented Characters, space, "',-.", maximum length 40 characters
Address Line 2AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 30 charactersAlphaNum, Latin 1 Accented Characters, space, "'#,-.`()", maximum length 30 characters
CityAlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 100 charactersAlphaNum, Latin 1 Accented Characters, space, "',-.`()", maximum length 20 characters
PhoneRequired, 16 digits maxOptional, 10 digits max
EmailAlphaNum, “._-+“, maximum length 50 charactersSee RFC-2822
Emboss Line 2AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, length from 3 to 25 charactersAlphaNum, Latin 1 Accented Characters, space, “-“, maximum length 28 characters

Response

Field NameTypeDescription
idIntegerID of the Cardholder
external_tagStringExternal reference field to stored on Card Holder
primary_processor_referenceIntegerUnique account reference value at Processor
usernameStringUsername used to login into Cardholder Portal
created_atStringTimestamp when Card Holder was created
bank_detailsBank DetailsBank account details for direct deposit account. Details are for Cardholders primary account only. See below for details

Bank Details

Bank details will only be displayed if direct deposit is enabled for the cardholders primary account.

Field NameTypeDescription
transit_numberString
institution_numberString
account_numberString

Notes:

  1. A separate value_load_result field will be returned along side the cardholder data. If a cardholder was created and the cardholders account was not loaded with the given amount, it will contain a status code and message describing why the load failed. Otherwise, the code will be "success".
  2. The Create Cardholder endpoint will respond with the appropriate message if the CIP/KYC verification is required and it failed. See various examples provided.

Shipping Methods - U.S.

ValueDescription
1USPS Domestic First Class Mail
2UPS Domestic Ground
3USPS Priority International
4BULK - Domestic Ground

Shipping Methods - Canada

ValueDescription
4USPS International (7-21 business days)
8UPS Worldwide Saver
9UPS Standard (day definite by date scheduled delivery by end of day)
Language
Credentials
Bearer
JWT
URL
Click Try It! to start a request and see the response here!