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 Name | Required | Type | Pattern | Description |
---|---|---|---|---|
program_id | Yes | String | Program to Create the Initial Account under | |
external_tag | No | String | User defined external reference field to store on Card Holder | |
first_name | Yes | String | Example: Elizabeth. See Field Validation Below. | Cardholder's first name |
middle_name | No | String | Example: Blaise. See Field Validation Below. | Cardholder's middle name |
last_name | Yes | String | Example: Harley. See Field Validation Below. | Cardholder's last name |
emboss_line2 | No | String | Example: 2nd Line Emboss. See Field Validation Below. | Second line card emboss text. |
date_of_birth | See Description | Date | Example: 13-01-1990. See Field Validation Below. | Cardholder's birth date. |
address1 | No | String | See Field Validation Below. | |
address2 | No | String | See Field Validation Below. | |
city | Yes | String | Example: Salt Lake City. See Field Validation Below. | Cardholder's city |
state | Yes | String | Valid 2 character state abbreviation. Example: UT | Cardholder's state |
postal_code | Yes | String | 12345 or 12345-1234 (US), K1A-1A1 (CA). Example: 18412 | Cardholder's postal code (zip code) |
country | Yes | Number | Three digit country code. Example: 840 | Three digit ISO numeric UN M49 country code; USA=840, Canada=124. |
phone | See Description | String | Valid phone number. See Field Validation Below. | Cardholder's primary phone number |
Yes | String | Email Address. Example: [email protected] | Cardholder's email | |
sin | See Description | String | SSN 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_method | No | String | See table below | Use shipping method to send the new card plastic. Note that this field is not required if you are issuing Virtual Cards. |
load_amount | No | Number | Monetary amount greater than 0 | Smallest 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_address | No | Address | See Below | The 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_id | No | Number | ID 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_id | No | Number | ID of the linked account. | Linked accounts share a balance but have separate cards. This feature must be enabled as part of your program. |
subprogram_code | No | String | Subprogram to create card under. | May be 'virtual' or 'physical'. This feature must be enabled as part of your program. |
package_code | No | String | Specifies card art and carrier to be used with a physical card | Each package code must be individually configured. |
locale | No | String | Cardholder language and localization preference. | Set localization and language preference with en_US , en_CA , or fr_CA . |
kyc_additional_client_info | No | KYC_ACI | See Below | Cardholder's KYC Additional Client Information (KYC_ACI) |
Shipping Address Attributes
Field Name | Required | Type | Pattern | Description |
---|---|---|---|---|
address1 | Yes | String | See Field Validation Below. | |
address2 | No | String | See Field Validation Below. | |
city | Yes | String | Example: Salt Lake City. See Field Validation Below. | Cardholder's city |
state | Yes | String | Valid 2 character state abbreviation.UT | Cardholder's state |
postal_code | Yes | String | 12345 or 12345-1234 (US), K1A-1A1 (CA)18412 | Cardholder's postal code (zip code) |
country | Yes | Number | Three digit country code.840 | Three digit ISO numeric UN M49 country code; Example USA=840, Canada=124. |
first_name | No | String | Example: Elizabeth. See Field Validation Below. | Cardholder's first name |
last_name | No | String | Example: Harley. See Field Validation Below. | Cardholder's last name |
KYC Additional Client Information (KYC_ACI)
Field Name | Required | Type | Pattern | Description |
---|---|---|---|---|
occupation | No | String | Free text, maximum length 50 characters | Cardholder's occupation |
third_party_determination | No | Boolean | true / false / null | Third-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_residency | No (*1) | Boolean | true / false / null | Tax residency outside of Canada and US |
foreign_tax_country_code | (*2) | Number | Three digit country code.840 | Country of Tax Residency. Same as city field. |
foreign_tax_id | (*2) | String | Tax 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 | |
---|---|
AlphaNum | a-z, A-Z and 0-9 |
Latin 1 Accented Characters | ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ |
Latin 1 Special Characters | ,.?@&!#'~()-;+._$%&+:;¿¡ |
Fields
Field | Canada | USA |
---|---|---|
First, Middle and Last Names | AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 50 characters | Alpha, “ '-“, maximum length 30 characters |
Date Of Birth | dd-MM-yyyy, Required | dd-MM-yyyy, Optional |
Address Line 1 | AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 30 characters | AlphaNum, Latin 1 Accented Characters, space, "',-.", maximum length 40 characters |
Address Line 2 | AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 30 characters | AlphaNum, Latin 1 Accented Characters, space, "'#,-.`()", maximum length 30 characters |
City | AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, maximum length 100 characters | AlphaNum, Latin 1 Accented Characters, space, "',-.`()", maximum length 20 characters |
Phone | Required, 16 digits max | Optional, 10 digits max |
AlphaNum, “._-+“, maximum length 50 characters | See RFC-2822 | |
Emboss Line 2 | AlphaNum, Latin 1 Accented Characters, space, Latin 1 Special Characters, length from 3 to 25 characters | AlphaNum, Latin 1 Accented Characters, space, “-“, maximum length 28 characters |
Response
Field Name | Type | Description |
---|---|---|
id | Integer | ID of the Cardholder |
external_tag | String | External reference field to stored on Card Holder |
primary_processor_reference | Integer | Unique account reference value at Processor |
username | String | Username used to login into Cardholder Portal |
created_at | String | Timestamp when Card Holder was created |
bank_details | Bank Details | Bank 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 Name | Type | Description |
---|---|---|
transit_number | String | |
institution_number | String | |
account_number | String |
Notes:
- 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"
. - 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.
Value | Description |
---|---|
1 | USPS Domestic First Class Mail |
2 | UPS Domestic Ground |
3 | USPS Priority International |
4 | BULK - Domestic Ground |
Shipping Methods - Canada
Value | Description |
---|---|
4 | USPS International (7-21 business days) |
8 | UPS Worldwide Saver |
9 | UPS Standard (day definite by date scheduled delivery by end of day) |