<<Back

The Enrollments API allows Partners to enroll a new user into a product, create an account, and create a payment instrument (card) with one single call. The Enrollments API stores encrypted data. Note: Partners who are not configured for encryption will have encrypted data omitted from the data objects in their responses.

Encrypted User Data:

• name

• address

• social security number

• date of birth

• email address

• phone number

Encrypted Account Information:

• direct deposit

• account or purse

• account holder

By default, every user automatically has one primary purse that is designated for a primary spending balance. A purse can be thought of as a balance container. Example: When money is added to a user’s account through direct deposit, the amount is automatically credited to their primary purse. A new user's initial status depends on the Know Your Customer (KYC) requirements and the Office of Foreign Assets Control (OFAC) requirements of the program

Example: When money is added to a user’s account through direct deposit, the amount is automatically credited to their primary purse.

A new user's initial status depends on the Know Your Customer (KYC) requirements and the Office of Foreign Assets Control (OFAC) requirements of the program.

KYC Verification

KYC Verification Response Codes

Currency Response Codes

User Data Response Codes

Terms Acceptance Response Codes

Endpoint: POST /enrollments

Structure of API Call: POST /programs/{programCode}/enrollments

• Create New User

• Create Account

• Create Payment Instrument

Note: If POST /enrollments is called with a valid request and enrollment fails during processing, the request will be automatically completed if the customer clears OFAC.

Bill Cycle Date (BCD)

Note: Active accounts will return a bill cycle date when POST /enrollments is called.

• The bill cycle date will be returned as an accountCycleDay, which represents the first day of the statement cycle for an account.

• The accountCycleDay can be 1-28.

Idempotent Retry and Billing Cycle Dates

Note: Accounts must have a billing cycle date to have a normal account status.

• Typically, the Billing Cycle Date (BCD) returned as an accountcycleday is automatically created at the time of enrollment, but in conditions where it cannot be created, the account will be left in a pending state.

• Partners should make an idempotent call in these situations. The idempotent call for POST /enrollments will populate the BCD when the idempotent retry process is completed. The account status will also be set to normal.

Example: Using a POST /enrollments idempotent call to populate the BCD.

1st POST /enrollments call fails, and the BCD is null. The paymentIdentifier and the payment instruments are not created. The account is in a pending/registration not complete state.

Active Consumer Account Limits

An account is considered active when it has been activated and either has an account status of normal or a kycPendingGate (aka: Cure) with a value other than none. There is a limit to the number of active accounts allowed per social security number for Consumer Accounts.

When the Active Account Limit rule is encountered during a POST /enrollments call and the date of births match, the most recent active enrollment details will be returned. If the date of births do not match, only the response details will be returned.

Social Security Number (SSN) Limits

• Up to 1 active accounts with the same SSN per program is allowed

• Up to 3 lifetime accounts with the same SSN per program are allowed

Phone Limits - Default or Primary Phone Number on Account

The following phone limits will be implemented (during enrollment) only for the phone number that is listed as the default for the account:

• Up to 2 active accounts with the same phone number per program are allowed

• Up to 10 lifetime accounts with the same phone number per program are allowed

Note: Updates requested for phone numbers that exceed the current phone limits will be declined.

ITIN Limits

• Up to 1 active accounts with the same ITIN per program are allowed

• Up to 3 lifetime accounts with the same ITIN per program are allowed

Response Codes

Know Your Business (KYB) Flow during Enrollment

Partners who are configured for KYB flow, can enroll customers who own small businesses. An optional node, businessData, will be available under the encryptedUserData payload.

Successful Business Enrollment (Happy Path):

• The accountType, businessData (required fields), and business phone number is provided by the customer during enrollment.

• POST /enrollments is submitted and processed.

• The customer’s account is created and activated, including paymentInstruments.

Response Codes

Active Small Business Account Limits

Social Security Number (SSN) Limits

• Up to 10 active accounts with the same SSN per program is allowed

• Up to 20 lifetime accounts with the same SSN per program are allowed

Phone Limits

The following phone limits will be implemented (during enrollment) only for the phone number that is listed as the default for the account:

• Up to 10 active accounts with the same phone number per program are allowed

• Up to 20 lifetime accounts with the same phone number per program are allowed

ITIN Limits

• Up to 10 active accounts with the same ITIN per program are allowed

• Up to 20 lifetime accounts with the same ITIN per program are allowed

Refer to Active Consumer Account Limits for details about consumer account limit thresholds.

Response Codes

Response Codes - Length Validation

Endpoint: PUT /businessProfile

Structure of API Call: PUT program/programcode/accounts/accountIdentifier/businessProfile

This endpoint allows Partners to update the business data associated with a business account. This endpoint can be used with the following businessTypes:

• ConsumerProfileType

• Individual

• soleProp

• llc

• corp

• partnership

• nonprofit

• SingleLLC

• ProCorp

Note: If the businessName on the account is updated, then the next card replacement request will use the updated businessName.

Response Codes

Endpoint: GET /businessProfile

Structure of API Call: GET programs/{programCode}/accounts/{accountIdentifier}/businessProfile

• Retrieve business data

This endpoint allows the retrieval of business data associated with a business account.

Response Codes

Accepting Matricula Consular Identification

This feature allows Partners to use Matricula Consular IDs to enroll Mexican Citizens, living in the US, who may not have a Social Security Number (SSN) or an Individual Taxpayer Identification Number (ITIN).

Note: The Matricula Consular ID cannot be used along with an SSN or ssnSuffix (last4ssn). They are mutually exclusive, so if used together, the following error will be returned :

• HTTP Status Code: 400

• Code: 630

• subCode: 0

• Description: Cannot pass both matriculaId and ssn or last4ssn

To enroll a customer using their Matricula Consular ID:

• Call POST /programs/{programCode}/enrollments and include the onboardingID received from the POST /kycGates/scanCapture call you completed.

• Note: You must call POST /kycGates/scanCapture before calling POST /enrollments.

Endpoint: POST /identity

Structure of API Call: POST /accounts/{accountIdentifier}/users/{userIdentifier}/identity

This endpoint allows an Individual Taxpayer Identification Number (ITIN) to be added to a customer’s account that originally enrolled using a Mexican Matricula ID only. This is primarily for U.S. tax purposes.

How it works:

• If a customer successfully enrolls using a Mexican Matricula ID only and they would like to add an ITIN to their account, submit a request containing the ITIN to POST /accounts/{accountIdentifier}/users/{userIdentifier}/identity.

ITIN Limits:

• Up to 1 active account with the same ITIN per consumer program is allowed

• Up to 3 lifetime accounts with the same ITIN per consumer program are allowed

Response Codes

Diacritic Character Substitution

Customers can use Spanish characters to properly spell their name during enrollment and replace card requests.

How it Works:

• Partner will allow identified Spanish characters to be used in the first and last names of their customers.

• During enrollment, when the customer enters the allowed Spanish characters for their first and last name, the name embossed onto the card will be substituted with identified replacement characters, by the system.

• Refer to the Valid Characters for Names, Cities, and Addresses table for details.

Endpoint: GET /enrollments/accounts/{accountIdentifier}

Structure of API Call: GET /programs/{programCode}/enrollments/accounts/{accountIdentifier}

• Retrieve Account

• Retrieve Payment Instrument Information

Bill Cycle Date (BCD)

Active accounts will return a bill cycle date when GET /enrollments is called.

• The bill cycle date will be returned as an “accountCycleDay”, which represents the first day of the statement cycle for an account.

• The accountCycleDay can be 1-28.

Unblock Card Retry Process

If a fraud block is removed from an account and the payment instrument remains blocked, the request to unblock the payment instrument will be retried up to 3 times. Note: All three retries will be completed in 15 minutes.

Retry Process

1. A BaaS account is locked due to suspicion of fraud.

2. A request to update the account and payment instrument to a healthy and normal state is submitted.

3. The account is updated to healthy and normal, but the payment instrument remains blocked.

4. The request to unblock the payment instrument is automatically retried up to 3 times.

5. The retry process is successful and the card is unblocked OR the retry process is unsuccessful and the kycPendingGate is set to manual with the statusReason underReview.

6. If the retry process is unsuccessful, the payment instrument will need to be unblocked by the Green Dot Care team.