Enroll a New Customer in EWA

An employee who is enrolled in an Earned Wage Access (EWA) Program is treated as a RocketKOR Customer. An Individual Customer Account is created for the employee, and a Financial Account is created for the account (such as a debit card) the employee is using for EWA disbursements.

Use this API to enroll a new Customer in an EWA Program and issue a debit or credit card to the Customer. This card will be used for EWA disbursements to the Customer.

The API will perform the following operations as part of the EWA enrollment process:

Create a new Individual Customer Account. If a Customer Account with the same externalId already exists, the API will return an error.
Issue a new debit or credit card to the Customer. A new integrated Financial Account will be created for the issued card.
Enroll the Customer in the specified EWA Program.
Create an EWA Customer Profile for the Customer.

Endpoint

POST /v1/customer-profiles

Authorization Header

Authorization: Bearer <access_token>

Request Body

externalId

string

Your organization’s Earned Wage Access (EWA) reference number for the employee. This should be a string that is used to identify the employee in your internal systems, such as your payroll software. The EWA reference number is added to the employee’s Customer Account, allowing you to easily locate the employee in RocketKOR. EWA reference numbers must be unique within the Business Account.

eligibilityStatus

string enum, values: NEW, ELIGIBLE, INELIGIBLE, ARREARS, BAD_DEBT, DISABLED

Customer’s eligibility status for Earned Wage Access (EWA) programs. The following values are supported:

NEW An EWA Customer Profile has been created for the Customer. This is the default value when a Customer is created or onboarded to an EWA Program.
ELIGIBLE The EWA Customer Profile has access to an EWA Program. Funds can be disbursed to the Customer Profile from the EWA Program.
INELIGIBLE The EWA Customer Profile is no longer able to access the EWA Program. Funds will not be disbursed to the Customer Profile but recovery will still be attempted.
ARREARS The latest recovery attempt for the EWA Customer Profile was not processed successfully. Funds will not be disbursed to the Customer Profile.
BAD_DEBT Several recovery attempts for the EWA Customer Profile have failed and funds are no longer expected to be recovered. Funds will not be disbursed to or recovered from the Customer Profile.
DISABLED The EWA Customer Profile is no longer eligible for the EWA Program.

programId

string

ID of the Earned Wage Access (EWA) program for the Customer.

customerData

object

Customer information.

type REQUIRED

string enum, value: INDIVIDUAL

Type of Customer. Value must be INDIVIDUAL.

firstName REQUIRED

string, min length: 1, max length: 40

Customer’s first name.

middleName

string, min length: 1, max length: 40

Customer’s middle name.

lastName REQUIRED

string, min length: 1, max length: 40

Customer’s last name.

prefix

string, min length: 1, max length: 40

Title before the Customer’s name (example: Dr).

suffix

string, min length: 1, max length: 40

Title following the Customer’s name (example: PhD).

sex

string enum, values: MALE, FEMALE, NONBINARY

Customer’s sex.

gender

string

Customer’s gender.

securityQuestion

string

Customer’s security question.

securityAnswer

string

Customer’s security answer.

pronoun

string

Customer’s pronouns (example: He/His).

primaryPhoneNumber REQUIRED

object

Customer’s primary phone number.

number REQUIRED

string

Customer’s phone number. The phone number can be entered in any of the following formats:

[+][country code][phone number including area code] (example: +14151234)
[country code][phone number including area code] (example: 14151234)
[phone number including area code] (example: 4151234)

RocketKOR will convert the phone number to E.164 format (example: +14151234).

type REQUIRED

string enum, values: WORK, HOME, MOBILE

Type of phone number.

provider

string, min length: 1, max length: 40

Phone provider.

extension

string, min length: 1, max length: 10

Phone extension.

verified

boolean

Whether the phone number has been verified.

primaryEmail REQUIRED

object

Customer’s primary email address.

value REQUIRED

string (email), max length: 320

Customer’s email address.

verified

boolean

Whether the email address has been verified.

dateOfBirth

string (date), format: yyyy-MM-dd

Customer’s date of birth.

placeOfBirth

object

Customer’s place of birth.

city

string, max length: 60

City.

countryCode

string, min length: 3, max length: 3

Country code. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

socialId

string, max length: 50

Customer’s unique national identifier, such as a Social Security Number (SSN). Responses include a truncated value only.

socialIdCountryCode

string, min length: 3, max length: 3

Country where the social ID was granted. Required if socialId is provided. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

citizenshipCountryCode

string, min length: 3, max length: 3

Country where the Customer holds citizenship. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

financialAccountData

object

Details for the Customer’s card, such as a debit or credit card. An external card Financial Account will be created for this card.

name REQUIRED

string, min length: 1, max length: 100

Name for the Financial Account. This is an informal name used for the account in RocketKOR.

subtype REQUIRED

string enum, values: DEBIT, CREDIT

Type of card.

defaultFlag

boolean, default: false

Whether this is the Customer’s default Financial Account for transactions.

currency

string, min length: 3, max length: 3, default value: USD

Currency of the Financial Account. Must be an ISO 4217 alpha 3-character currency code.

card REQUIRED

object

Details for the card attached to the Financial Account.

firstName REQUIRED

string, min length: 1, max length: 40

Customer’s first name as it appears on the card.

middleName

string, min length: 1, max length: 40

Customer’s middle name as it appears on the card.

lastName REQUIRED

string, min length: 1, max length: 40

Customer’s last name as it appears on the card.

cardNumber REQUIRED

string, min length: 11, max length: 19

Card number.

expiry REQUIRED

string, format: yyyy-MM

Expiry date for the card.

billingAddress REQUIRED

object

Billing address for the card.

addressLine1 REQUIRED

string, min length: 1, max length: 50

Address line 1.

addressLine2

string, min length: 1, max length: 50

Address line 2.

addressLine3

string, min length: 1, max length: 50

Address line 3.

city REQUIRED

string, min length: 1, max length: 25

City.

stateCode CONDITIONAL

string, min length: 2, max length: 3

State, province, or territory. Required if country is USA or CAN. Must be an ISO 3166-2 uppercase alpha 2-character or 3-character country subdivision code. For example, Missouri is MO and Ontario is ON.

countryCode REQUIRED

string, min length: 3, max length: 3

Country. Must be an ISO 3166-1 uppercase alpha 3-character country code. For example, the United States is USA and Canada is CAN.

postalCode REQUIRED

string, min length: 1, max length: 10

ZIP code or postal code. For US addresses, must be a valid value of 5 digits (example: 63368) or 5 digits-4 digits (example: 63368-5555). Can be alphanumeric for other countries with a maximum length of 10 characters.

Returns

Returns the Earned Wage Access (EWA) Customer Profile object. This object contains unique IDs for the Customer’s EWA Customer Profile, Customer Account, and Financial Account; your EWA reference number for the Customer; and details for the Customer’s EWA Program.

SAMPLE REQUEST

				
					{
  "externalId": "52cb212e-d6d2-4afe-b9dc-4f9fe5c12c3b",
  "eligibilityStatus": "NEW",
  "programId": "abcdefg",
  "customerData": {
    "type": "INDIVIDUAL",
    "firstName": "Sarah",
    "middleName": "Jane",
    "lastName": "Green",
    "prefix": "Ms",
    "suffix": "",
    "sex": "FEMALE",
    "gender": "",
    "securityQuestion": "Who is your favorite author?",
    "securityAnswer": "Barbara Gowdy",
    "pronoun": "She/Her",
    "primaryPhoneNumber": {
      "number": "+15556589",
      "type": "WORK",
      "provider": "ABC",
      "extension": "31",
      "verified": false
    },
    "primaryEmail": {
      "value": "sgreen@abc.com",
      "verified": false
    },
    "dateOfBirth": "1991-06-21",
    "placeOfBirth": {
      "city": "Houston",
      "countryCode": "USA"
    },
    "socialId": "123-45-6789",
    "socialIdCountryCode": "USA",
    "citizenshipCountryCode": "CAN"
  },
  "financialAccountData": {
    "name": "Customer’s External Card Account",
    "subtype": "DEBIT",
    "defaultFlag": true,
    "currency": "USD",
    "card": {
      "firstName": "Sarah",
      "middleName": "Jane",
      "lastName": "Green",
      "cardNumber": "4242424242424242",
      "expiry": "2027-12",
      "billingAddress": {
        "addressLine1": "625 Queen St",
        "addressLine2": "Suite 201",
        "addressLine3": "South Building",
        "city": "Vancouver",
        "stateCode": "BC",
        "countryCode": "CAN",
        "postalCode": "V5K 0A1"
      }
    }
  }
}

SAMPLE RESPONSE

				
					{
  "id": "28562c80-155b-4ddc-bc4b-aedb7dcdeed2",
  "externalId": "52cb212e-d6d2-4afe-b9dc-4f9fe5c12c3b",
  "customerId": "ed51e0b5-ddbb-43e0-b14d-d66044bf81ac",
  "financialAccountId": "6aadfb7a-fc4f-481a-8f25-2d84810a4b9e",
  "latestEligibilityStatus": {
    "id": "2294d74b-c0e0-4a7f-9ea0-3a2117e83a4c",
    "eligibilityUpdateReason": "New application",
    "status": "NEW",
    "createdAt": "2024-01-22T22:20:55.610Z"
  },
  "firstName": "Sarah",
  "middleName": "Jane",
  "lastName": "Green",
  "programId": "abcdefg",
  "programName": "EWA"
}