📘

For full request/response schemas, see the API Reference – Enrollments.

Add Enrollment for User and Create Account/Card (Encrypted)

POST /programs/{programCode}/enrollments

Creates a new enrollment for a user and performs the following core operations:

• Creates a new user profile
• Creates an account
• Creates one or more payment instruments (virtual and/or physical)
• Supports instant issue (card‑in‑hand) enrollment
• Supports account upgrades (for example, GPR → DDA when upgradeFlag=true)

📘

Important
If a valid enrollment request is submitted and processing fails during OFAC screening, the enrollment will automatically complete once OFAC is cleared.

Request and response field definitions and examples are documented in the API Reference.

Name Validation Rules

All name fields (firstName, middleName, lastName) must follow the rules below. These rules are enforced during enrollment and KYC execution.

Allowed Characters

• Alphabetic characters: A–Z, a–z
• Space
• Apostrophe (')
• Hyphen (-)
• Period (.)
• Supported diacritics:
  • Grave: À à
  • Acute: Á á
  • Tilde: Ã ã Ñ ñ
  • Cedilla: Ç ç
  • Circumflex: Î î
  • Diaeresis / Umlaut: Ü ü

Validation Rules

• Names must start and end with a letter (diacritics allowed)
• No consecutive special characters (spaces, apostrophes, hyphens, or periods)
• Diacritics must be paired with a letter
• Disallowed characters include numbers, emojis, and all other symbols

Length Requirements

Suggested validation regex (example only):

^(?=.25$)[A-Za-zÀ-ÿ](?:[A-Za-zÀ-ÿ]|[ .'-](?![ .'-]))*[A-Za-zÀ-ÿ]$

❗ If any name field does not meet these requirements, enrollment fails with HTTP 400 – Bad Request.

Supported Identity Types

The Enrollments API supports two identity verification flows:

• SSN / ITIN (U.S. persons)
• Foreign‑issued identity documents

The identity type determines which identifying fields are required and how KYC is performed.

SSN / ITIN Enrollment Flow

This is the standard enrollment flow for U.S. customers.

Required Identifying Fields

• dateOfBirth (YYYY‑MM‑DD)
• One of the following (mutually exclusive):
  • Full ssn (9 digits)
  • ssnSuffix (last 4 digits)

Non‑U.S. SSNs will fail KYC verification.

KYC Execution

When executeKycFlag=true, the platform validates:

• Name
• Date of birth
• Address
• SSN or ITIN
• Phone number

Common SSN / ITIN errors include:

• Providing both ssn and ssnSuffix
• Invalid date‑of‑birth format
• Missing home address
• Multiple default phone numbers

Foreign ID Enrollment Flow

Foreign ID enrollment supports non‑U.S. persons using government‑issued identity documents.

Required Fields

• First and last name (middle name optional)
• Date of birth
• U.S. residential address
  • Must be a physical address
  • PO Boxes, PMBs, CMRAs, and foreign addresses are not supported
• Email
• Mobile phone number
• Foreign identity details:
  • identityType
  • identityValue
  • identityCountryCode
  • identityExpirationDate

Additional Compliance Fields

Source of funds (required):

• Salary or wages
• Business income
• Pension or retirement
• Investments or asset sales
• Inheritance or gifts
• Government benefits
• Legal settlements
• Lottery or gambling winnings

Occupation (required):

• Employed
• Self‑employed / business owner
• Student (employed or unemployed)
• Unemployed
• Retired

Foreign ID user data must be encrypted before calling the enrollment endpoint.

User Data Requirements (Unencrypted)

The following top‑level objects are required to successfully perform KYC:

• profileData
• identifyingData
• email
• phoneNumbers

These objects are encrypted and passed as encryptedUserData in the enrollment request.

Enrollment Data Validation Rules

KYC Identity Verification Rules

Enrollment Error Codes

Enrollment Limits

SSN / ITIN limits:

• 1 active account per SSN / ITIN per program
• 3 lifetime accounts per SSN / ITIN per program

Phone number limits (default phone only):

• 2 active accounts per phone number per program
• 10 lifetime accounts per phone number per program

Requests exceeding these thresholds are rejected.

Idempotent Retries and Account Cycle Day

In some scenarios, enrollment may succeed without assigning an account cycle day (BCD). When this occurs:

• The account remains in a pending state
• Payment instruments are not created

Partners must retry the same POST /enrollments request idempotently. Once completed:

• The account cycle day is populated
• The account status transitions to normal
• Payment instruments are created
• An Account Updated webhook is sent

Gets Enrollment Details (Encrypted)

GET /programs/{programCode}/enrollments/accounts/{accountIdentifier}

Returns encrypted enrollment details for an account.

Notes:

• Joint accounts return two account holders
• GPR → DDA upgrades may include upgradeKycStateData

Refer to the API Reference for full request and response examples.

Example Enrollment Details Response (Joint Account)

For joint accounts, the enrollment details response contains multiple account holders.

Each account holder includes its own:

• user
• paymentInstruments
• accountHolderIdentifier

One account holder is marked as the primary account holder (isPrimaryAccountHolder=true).

{
  "account": {
    "accountIdentifier": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "accountReferenceNumber": "EXAMPLE12345",
    "status": "normal",
    "accountStatusChangedDateTime": "2099-01-01T00:00:00.000Z",
    "statusReasons": [
      "healthy"
    ],
    "directDepositInformation": {
      "accountNumber": "000000000000000",
      "routingNumber": "000000000"
    },
    "purses": [
      {
        "purseIdentifier": "11111111-2222-3333-4444-555555555555",
        "purseType": "primary",
        "availableBalance": 0,
        "ledgerBalance": 0,
        "availableBalanceAsOfDateTime": "2099-01-01T00:00:00Z",
        "ledgerBalanceAsOfDateTime": "2099-01-01T00:00:00Z",
        "isHidden": false,
        "status": "active"
      }
    ],
    "accountHolders": [
      {
        "paymentInstruments": [
          {
            "encryptedPrivatePaymentInstrumentData": {
              "version": "EC_v1",
              "ephemeralPublicKey": "BASE64_PUBLIC_KEY_PLACEHOLDER",
              "publicKeyHash": "BASE64_HASH_PLACEHOLDER",
              "data": "ENCRYPTED_DATA_PLACEHOLDER"
            },
            "paymentIdentifier": "pi-primary-0001",
            "paymentInstrumentIdentifier": "card-primary-virtual-0001",
            "paymentInstrumentType": "virtual",
            "status": "activated",
            "isPinSet": false,
            "last4Pan": "1111",
            "activatedDateTime": "2099-01-01T00:00:00Z",
            "issuedDateTime": "2099-01-01T00:00:00Z",
            "isPrivateDataViewable": false
          }
        ],
        "user": {
          "firstName": "Primary",
          "lastName": "ExampleUser",
          "dobStatus": "matched",
          "last4Identity": "1111",
          "identityType": "ssn",
          "userIdentifier": "user-primary-0001",
          "status": "active",
          "isPrimaryAccountHolder": true,
          "kycStateData": {
            "ofacStatus": "passed",
            "kycStatus": "passed",
            "kycPendingGate": "healthy"
          }
        }
      },
      {
        "paymentInstruments": [
          {
            "encryptedPrivatePaymentInstrumentData": {
              "version": "EC_v1",
              "ephemeralPublicKey": "BASE64_PUBLIC_KEY_PLACEHOLDER",
              "publicKeyHash": "BASE64_HASH_PLACEHOLDER",
              "data": "ENCRYPTED_DATA_PLACEHOLDER"
            },
            "paymentIdentifier": "pi-secondary-0002",
            "paymentInstrumentIdentifier": "card-secondary-virtual-0002",
            "paymentInstrumentType": "virtual",
            "status": "activated",
            "isPinSet": false,
            "last4Pan": "2222",
            "activatedDateTime": "2099-01-01T00:00:00Z",
            "issuedDateTime": "2099-01-01T00:00:00Z",
            "isPrivateDataViewable": false
          }
        ],
        "user": {
          "firstName": "Secondary",
          "lastName": "SampleUser",
          "dobStatus": "matched",
          "last4Identity": "2222",
          "identityType": "ssn",
          "userIdentifier": "user-secondary-0002",
          "status": "active",
          "isPrimaryAccountHolder": false,
          "kycStateData": {
            "ofacStatus": "passed",
            "kycStatus": "passed",
            "kycPendingGate": "healthy"
          }
        }
      }
    ],
    "accountCycleDay": 1
  },
  "responseDetails": [
    {
      "code": 0,
      "subCode": 0,
      "description": "Success",
      "url": "https://example.documentation"
    }
  ]
}

Refer to the API Reference for additional response schema.