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