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.

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.

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.

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

Unencrypted Identity Parameters

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

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, passport, nationalIdCard or stateIdCard) 
}

📘

Note: These values must be provided if a Mexican Matricula ID is being used. Also note that nationalIdCard is the document type for Passport Cards and Permanent Resident Cards.

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