Create Cardholder

post https://api.staging.pungle.co/api/v1/card_issuing/cardholders

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
email	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
Email	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)