KYC

Know Your Customer (KYC) APIs can be used for identity verification purposes.

Overview

Know Your Customer (KYC)

Some Green Dot programs/products require users to pass an identity verification process before they can have an account. Regulatory mandates require identification to prevent activities, such as money laundering and fraud. The identity verification process is known as Know Your Customer (KYC).

KYC States

Possible KYC verification outcomes:

  • None: KYC failed with a hard decline and there is no cure
  • KYC2: Full 9-digit SSN required for KYC verification
  • IDV: Escalated for document verification
  • Manual: Referred for OFAC review
  • Healthy: Passed KYC successfully

KYC Social Security Number Validation (SSN)

In non-production environments, development teams may send in certain SSN values that trigger particular paths in the KYC validation flow. The table below lists those prefixes and the behaviors they generate.

SSN PREFIXKYCOFACAccount StatusAccount ReasonNext Gate/CureResponse CodeSub-Code
451xxxxxxFailed (no cure)PassedLockedRegistration FailedNone2 – Terminal11 – KYC Fail
554xxxxxxFailed (under age)PassedLockedRegistration FailedNone2 – Terminal40 – Under Age
452xxxxxxFailed (no cure)FailedLockedRegistration FailedManual2 – Terminal33 – KYC and OFAC Failed (No Cure)
401xxxxxxPassedFailedLockedRegistration FailedManual2 – Terminal31 – OFAC Failed
992xxxxxxFailed (cure)FailedLockedRegistration Not CompleteIDV1 – Action34 - KYC and OFAC Failed (KYC is curable)
991xxxxxxFailed (cure)PassedPendingRegistration Not CompleteIDV1 – Action10 – KYC Curable Fail
10xxxxxxxPassedPassedNormalHealthyHealthy0 – Success

Social security numbers will be evaluated in production prior to validating identity during enrollment. POST /enrollments requests containing invalid social security numbers will be automatically declined with an Invalid SSN response. This enhancement can lead to higher enrollment success rates for Partners due to the ability to avoid enrollment attempts that will be declined.

Enforcement of these rules is NOT in place in non-production environments, in order to allow partners to use test pseudo-SSN’s.

Invalid Social Security Numbers

📘

This list is dynamic, so social security numbers may be added or removed in the future.

SSN TypeExample
Generic000000000
Generic111111111
Generic222222222
Generic333333333
Generic444444444
Generic555555555
Generic666666666
Generic777777777
Generic888888888
Generic999999999
Generic123456789
Generic987654321
Invalid per Social Security AdministrationArea, Group, or Serial digits cannot contain all zeros.

• Area: First three digits of SSN.
- Example: 000-xx-xxxx
• Group: Next two digits of SSN.
- Example: Xxx-00-xxxx
• Serial: Last four digits of SSN.
- Example: xxx-xx-0000
Invalid per Social Security AdministrationArea digits (first three digits) cannot be 666. Example: 666-xx-xxxx
Invalid per Social Security AdministrationGroup digits (next two digits) are not assigned sequentially. Therefore, they must follow the ordering sequence below:

• 01 – 09 are odd.
- Example: xxx-01-xxxx, xxx-03-xxxx, xxx-05-xxxx, ….. xxx-09-xxxx
• 02 – 08 are even.
- Example: xxx-02-xxxx, xxx-04-xxxx, xxx-06-xxxx, ….. xxx-08-xxxx
• 11 – 99 are odd.
- Example: xxx-11-xxxx, xxx-13-xxxx, xxx-15-xxxx, ….. xxx-99-xxxx
• 10 – 98 are even.
- Example: xxx-10-xxxx, xxx-12-xxxx, xxx-14-xxxx, ….. xxx-98-xxxx
Invalid002-28-1852
Invalid042-10-3580
Invalid062-36-0749
Invalid078-05-1120
Invalid095-07-3645
Invalid128-03-6045
Invalid135-01-6629
Invalid141-18-6941
Invalid165-16-7999
Invalid165-18-7999
Invalid165-20-7999
Invalid165-22-7999
Invalid165-24-7999
Invalid189-09-2294
Invalid212-09-7694
Invalid212-09-9999
Invalid306-30-2348
Invalid308-12-5070
Invalid468-28-8779
Invalid549-24-1889

KYC and IDV Best Practices

KYC

Required data fields:

  • Full 9 SSN
  • First and Last Name
  • DOB
  • Residential Address – required fields:
    • Address1, City, State
    • or Address1, Zip Code
    • or Address1, City, State, Zip Code
  • Examples of KYC Hard Fail reasons:
    • Invalid SSN
    • SSN Mismatch
    • COPPA Alert
    • Address is P.O. Box
    • High Risk or Blacklisted Attribute, such as Email Address, Phone Number, and IP Address (if available)
  • Examples of KYC Soft Fail reasons (eligible for step-up verification via IDV):
    • Name Mismatch
    • DOB/YOB Mismatch
    • Address Mismatch

Potential CIP, OFAC, and IDV Responses

  • CIP Hard Fail
    • Response Code: 2, SubCode: 11 – CIP failed, no cure
    • SubCode: 33 – Same as above row except OFAC also partially matched and account requires manual review
  • CIP Soft Fail > IDV Eligible
    • Response Code: 1, SubCode: 10 – CIP failed, curable via IDV
    • SubCode: 34 – Same as above row except OFAC also partially matched and account requires manual review
  • CIP Soft Fail > IDV Eligible > IDV Pass
    • Response Code: 0 – IDV Pass
  • CIP Soft Fail > IDV Eligible > IDV Needs Resubmission
    • Response Code: 1, SubCode: 23 – ID Not Readable
    • Response Code: 1, SubCode: 21 – ID Invalid
    • Response Code: 1, SubCode: 24 – ID Name Mismatch
  • CIP Soft Fail à IDV Eligible à IDV Fail
    • Response Code: 2, SubCode: 22 – IDV Fail

IDV

  • Acceptable types of ID: Driver’s License and State-Issued ID
    • No need to have user select which ID type they will be submitting in the UI – Green Dot’s 3rd party vendor is able to validate.
  • Acceptable file format: Must be base 64 encoded JPEG.
  • User must submit ID in real-time and should not have the ability to upload photos from their library.
  • User must submit via mobile app for more enhanced security. If you (partner) want to allow via desktop, we ask that you provide fraudData within the Enrollment request (such as the below) for Green Dot to implement additional risk controls:
    • Device ID
    • IP Address
    • isPhoneVerified
    • isEmailVerified
    • Account Tenure
    • Any other data the partner finds helpful for fraud learning and decisioning
  • Definitions:
    • “ID Pass”: ID passed verification.
    • “ID Not Readable”: ID submitted cannot be detected due to blurriness and/or bad image quality; needs to be resubmitted.
    • “ID Invalid: Scenario”: ID submitted has been detected but triggered one or more of the following and needs to be resubmitted.
      • Document missing four corners
      • Document too small
      • Document border too small
      • Face image not detected
      • Barcode not detected
    • “ID Name Mismatch”: Name on ID submitted does not match name on the account and needs to be resubmitted.
    • “ID Fail”: ID failed verification.
  • Limits:
    • 10 IDV submission attempts allowed per account and only “ID Invalid” and “ID Name Mismatch” count toward this threshold, cumulatively. Once threshold is maxed out, the cure is set to ‘none’, and the account will fail registration (if onboarding) or remain blocked (if already passed onboarding).
    • “ID Not Readable” has its own threshold of 3 submission attempts per account. All subsequent attempts that are “ID Not Readable” would result in “ID Invalid” and count toward the above threshold that makes the account eligible for a hard fail.
  • Image Quality:
    • Most optimal image quality is 2048 x 1536 and 90% to allow for the best verification and response times; however, 90-94% image quality is also acceptable as some devices default to a higher percentage.
    • The image quality speaks to the accuracy that the original image is transmitted to Green Dot and our third-party verification vendor. Quality is comprised of attributes like coloration, tone, and sharpness. The larger and more accurate that a photo is, the longer the time it takes to transmit it from the device to Green Dot and our vendor. At the same time, if a photo is on the smaller side, we don’t recommend a higher quality like 96-98% because it will be too sharp.
  • Best Practices for Users:
    • Must submit front and back image of ID.
    • Leave a visible, dark, and solid border around the ID.
    • Take a flat photo. Do not angle or skew.
    • Take a clear picture. Avoid glares and shadows.
    • Disable flash.
    • Center the ID and confirm that all four corners of the document are clearly visible in the image.
      Note: Recommend partner to input borders into camera view to help user frame the image.

Office of Foreign Assets Control

The Office of Foreign Assets Control (OFAC) is a department of the US Treasury. Their regulations are in place in part to ensure that companies do not unwittingly do business with terrorist organizations or other unsanctioned entities. Compliance with OFAC is critical for US businesses working with overseas partners.

Note: If kycPendingGate is manual, then this will often mean that an OFAC review is required. Once this feature is implemented, accounts with a manual cure can be cleared. This doesn’t affect the API, but it would trigger an accountUpdate alert.

📘

When an account is cleared for OFAC and the account has also passed KYC, then the Account Status will be pending and the kycPendingGate will be healthy.

Top Level Response Codes

📘

The UTC format is the date/time standard that is used across all BaaS APIs.

CodeHTTP Status CodeReference NameDescription
02xxSUCCESSThe operation was successful.
12xxACTION_RQDFollow action or additional information provided. See the Business Rule Response Codes for further details.
22xxENROLLMENT_FAILEDThe operation was successful, but the account is in terminal state.
32xxTRANSFER_DISALLOWEDThe transfer failed. See the Business Rule Response Codes for further details.
42xxBUSINESS_OPERATION_FAILED (CARD MANAGEMENT)The operation failed. See the Business Rule Response Codes for further details.
52xxAccount ManagementThe operation failed. See the Business Rule Response Codes for further details.
62xxGuest Check Out
10404NOT_FOUNDResource not found.
11200NO_DATAEmpty list returned.
50406DECRYPTION ERRORAn encrypted data block on the payload was not decrypted successfully.
100400MALFORMED SCHEMAThe payload could not be loaded.
101400INVALID REQUESTThe request was invalid. See the description for details.
200400REQUIRED PROPERTY MISSING OR MISSING A VALUEA required property (object or scalar) is missing. The property must be provided and contain a value for the type.
300400INVALID DATA TYPEThe data type is invalid. Example: An integer was expected, but an alphanumeric string was provided.
350400INVALID FORMATThe format of the string or number was invalid.
380200N/AAn identity can only be added to a Matricula based enrollment.
400400INVALID FIELD LENA value was provided that is shorter than the minimum supported length or longer than the maximum supported length.
409409CONFLICTSee the Business Rule Response Codes for the specific conflict reason.
500500DOWNSTREAM SYSTEM OFFLINE - DO NOT AUTO RETRYA downstream system is unavailable. It may be offline for an extended or unknown period, so the client should not retry automatically.
503503DOWNSTREAM SYSTEM OFFLINE - RETRYA downstream system is unavailable. It may be transient, so the client may retry automatically.
505500DOWNSTREAM SYSTEM HARD FAILURE - DO NOT AUTO RETRYThe transfer failed and the funds were credited back to the source.
506500The transfer failed and the funds have not yet been credited back to the source. Manual inspection required.The transfer failed and the funds have not yet been credited back to the source. Manual inspection required.
600400INVALID ENUM VALUEA value was provided that is not in the set of allowable values.
602400A virtual card only account is not allowed for this product
603400Invalid combination of values in the request
610400INVALID AMOUNTAn amount was provided that is not valid.
620400INVALID DATE RANGEA date was provided that is not in the allowable date range.
630400INVALID_PROPERTYA property was provided that was not valid given the context of the request.
640400INVALID STRING CHARACTERAn invalid character was provided for a string field.
650400Invalid Currency Code
700400INVALID DATE FORMATInvalid date-format. Must be (ISO_8601): YYYY-MM-DD
720400INVALID UTC DATE TIME FORMATInvalid date-format. Must be (ISO_8601): YYYY-MMDDTHH:MM:SS.SSSZ
722400INVALID GUIDIdentifiers must be in GUID format. Must be (RFC-4122): XXXXXXXX-XXXXXXXX-XXXX-XXXXXXXXXXXX where X is a hex digit.
725400INVALID DATE TIME FORMAT (non-UTC, timezone unknown)Invalid date-format. Must be (ISO_8601): YYYY-MMDDTHH:MM:SS.SSS
730400INVALID DATE TIME FORMAT (non-UTC, timezone offset known)Invalid date-format. Must be ISO_8601: YYYY-MMDDTHH:MM:SS.SSS>±hh:mm Timezone offset precision can be from HH to MM.
740400INVALID HTTP URL FORMATInvalid HTTP URL format. Must follow Internet standard.
750400INVALID EMAIL FORMATInvalid Email format. Must follow Internet standard.
760400INVALID SSNInvalid SSN
761400INVALID ITINInvalid ITIN. Must be a 9-digit number that starts with 9.
800400Not SupportedCurrently used by TestEventWebHook, if a live account is used.
901 to 920201MRDC Response CodesSee MRDC Response Codes for further details.
950 to 959eCash Response Codes / Reference NameSee eCash for more information.
960 to 979Legacy Disbursement Response Codes / Reference Name
9602xxLoad Not AllowedSee subcodes below
9612xxLoad Failed
9622xxValidation Failed
9632xxOperation Not Allowed
1000200
201
202
400
VALUE_DOES_NOT_EXISTValue does not exist in the system. This is usually because an invalid object identifier was provided.
1020TBDDUPLICATE TYPEThis type already exists. Example: A second home address was provided.
1040400MORE THAN ONE DEFAULT PROVIDEDMore than one item in an array was identified as the default.
1041400INVALID DEFAULT PROVIDED
1042400HOME ADDRESS MISSING
1050400NO DEFAULT PROVIDEDisDefault was set to false for all items in an array but there must be at least one default.
10602xxDUPLICATE RESOURCEThe resource already exists based on unique identifiers.
21004xxFAILED TO ENCRYPTThe system failed to successfully encrypt the response payload.
3000- 4050Bill Pay Response CodesSee Bill Payment Codes for more information.

KYC API Endpoints

KYC API

The KYC API allows you to verify users through KYC as well as submit user Identification verification (IDV) information to Green Dot for verification.

Request Body

{
   "idvRequestType":"prerequisite",
   "encryptedIdentityDocumentation":{
      "version":"string",
      "ephemeralPublicKey":"string",
      "publicKeyHash":"string",
      "data":"string"
   }

Request Parameters

FieldDescription
idvRequestTypeType of identity verification request. The default type is “default".
encryptedIdentityDocumentationContains an encrypted string of the User’s identityDocumentation (image of legal identification). See Unencrypted Identity Documentation, below, for details.
versionVersion of encryption algorithm used.
ephemeralPublicKeyBase64 encoded ephemeral public key. Needed for key agreement.
publicKeyHashBase64 encoded SHA-256 hash of the X509 encoded public key bytes used during encryption.
dataBase64 encrypted data of an object or property.

Unencrypted Identity Parameters

FieldDescription
documentFrontImageFront image of User’s legal identification.
documentBackImageBack image of User’s legal identification.
documentCountryCodeOptional. ID’s country of origin Default: USA
documentTypeOptional. Default is driversLicense. Type of legal identification submitted (i.e. driversLicense, stateIdCard)

Response Message

If the POST request is successful, the following response message is returned along with a 200 HTTP status code.

Created

Sample Response Body

{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"operation is successful",
         "url":"http://tbd"
      }
   ],
   "kycGate":{
      "kycStateData":{
         "ofacStatus":"pending",
         "kycStatus":"pending",
         "kycPendingGate":"none"
      }
   }
}

Sample Response Parameters

FieldDescription
responseDetails,code, subCode,description,urlSee Response Details
kycGateContains the KYC and OFAC status of the User along with further action needed if KYC was not passed.
kycStateDataThe current OFAC and KYC status of the User.
ofacStatusThe last result of running an OFAC check against a User. Results can be pending, passed, or failed. See Office of Foreign Assets Control (OFAC) for details.
kycStatusThe last result of running a User through KYC gate. Results can be pending, passed, or failed. See Know Your Customer (KYC) for details.
kycPendingGatekycGate that the User must pass through to successfully complete the KYC process. Results can be none, kyc2, idv, manual, or healthy.

Business Rule Response Codes

Refer to Business Rule Response Codes for details.

Create IDV for a User

This endpoint is used to submit a user’s Identification verification information.

Note: When idvRequestType = AccountUpgrade, the KYC API performs some pre-DDA upgrade logic. After the KYC API passes the IDV upload verification, it sends a PN to the partner. After receiving the PN, the partner calls the createPaymentInstrument API, which performs the actual DDA upgrade logic.

API Call Structure

POST /programs/{programCode}/accounts/{accountIdentifier}/users/{userIdentifier}/kycGates/idv

KYC Scan Capture

This feature allows Partners to submit a Matricula Consular ID image (front and back) for Green Dot to scrape (extract information) and verify. Once the Matricula ID is verified, an onboardingID will be returned.

API Call Structure

POST /programs/{programCode}/kycGates/scanCapture

How it works:

  • Call POST programs/{programCode}/kycGates/scanCapture.
  • Include a front and back image of the Matricula ID.
  • Once received, Green Dot will extract information from the ID image, to verify.
  • Upon validation, an onboardingID will be included in the returned response.
  • Include this onboardingID in your POST Enrollments API call, to complete enrollment.
Sample Request Body:-
{
   "channel":"mobile",-- (Enums:mobile,web,or api)
   “productCode”":”100000”,-- (Optional,if a programCode has only one productCode. Required,
   if a programCode has multiple productCodes.)
   "encryptedIdentityDocumentation":{-- (See unencrypted Identity Documentation below)"
       "version":"string",
       "ephemeralPublicKey":"string",
       "publicKeyHash":"string",
       "data":"string"
   }
}

Unencrypted Identity Documentation
{
   "documentFrontImage":"base64 string",
   "documentBackImage":"base 64 string",
   "documentCountryCode":"MEX",-- (Optional.The default is USA.)
   “documentType"": ""matriculaIdCard" -- (Enums: driversLicense, matriculaIdCard or stateIdCard) 
}

Note: These values must be provided if a Mexican Matricula ID is being used.

Sample Response:-
{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ],
   "documentData":{
   	"encryptedIdentityData":{-- (See Unencrypted Identity Data)
               “version": "string",
               "ephemeralPublicKey": "string",
               "publicKeyHash": "string", 
               "data": "string"
         }
        "onboardingID": "2489488423",
        "documentType": "string",
        "templateType": "string",
    }
}

Unencrypted Identity Data
{
   "dateOfBirth":"YYYY-MM-DD",
   "(Requires reformatting and is mapped from the dob included in the Fraud API response)""firstName":"Jack",
   "lastName":"Smith",
   "address1":"string",
   "address2":"string",
   "city":"string",
   "state":"string",
   "zipCode":"string",
   "country":"string",
   "issuanceState":"string",
   "issuanceDate":"YYYY-MM-DD",
   "expirationDate":"YYYY-MM-DD"
}

Response Codes

HTTP Status CodeCodeSubCodeDescription
4002000channel is missing
4002000documentFrontImage is missing
4002000documentBackImage is missing
4006000invalid documentType
2001530invalid front image
2001531invalid back image
2001532invalid country code
2001533bad image detected – retry
2001535onboarding document declined