DOCS

New!

/

15 minute read

August 3, 2019

KYC Verification

Some Marqeta card programs require account holders to pass an identity verification process before being allowed to transact. For example, if a card is reloadable, then identity verification is required because of regulatory mandates intended to prevent activities such as money laundering. This identity verification process is known as KYC (know your customer) and can be performed on both user and business resources.

As part of KYC, the Marqeta Platform lets you optionally present users (but not businesses) with challenge questions if they initially fail verification. Challenge questions allow a higher percentage of users to pass KYC.

KYC can be performed multiple times on a single account holder.

Perform KYC

Action: POST
Endpoint: /kyc

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to verify the identity of an account holder (a user or business).

Required fields

In order to perform a KYC check, the user/business resource on which you perform the check must have the following fields configured with valid values:

User Fields Required for KYC Business Fields Required for KYC
  • first_name

  • last_name

  • address1 (cannot be PO Box)

  • city

  • state

  • postal_code

  • country

  • birth_date

  • ssn (full or last four)

  • business_name_legal

  • business_name_dba

  • office_location (cannot be PO Box)

  • taxpayer_id

  • incorporation.incorporation_type

  • incorporation.state_of_incorporation

  • phone (the top-level phone field)

  • date_established

Note
The Social Security number (SSN) requirement depends on your program’s configuration. To determine if you should provide a full or abbreviated number, contact your Marqeta representative.

Body field details (request)

Fields Description

token

string, optional

The unique identifier of the identity check.

If you do not include a token, the system automatically generates one. This token is necessary for use in other API calls. It is recommended that, rather than let the system, you create a simple, easy-to-remember string. This value cannot be updated.

Allowable Values:

36 char max

notes

string, optional

Notes pertaining to a manual override. This field is returned in the response only when the manual_override field is set to true.

Allowable Values:

manual_override

boolean, optional

Set to true to designate an account holder as having passed a verification check without Marqeta performing the check.

Use this override when you perform verification through another mechanism, such as with an alternative KYC provider or directly with the account holder.

Allowable Values:

true, false

Default value: false

reference_id

string, optional

Can be specified only if manual_override=true. If you verified the account holder’s identity by performing a KYC verification outside of the Marqeta platform, you can use the reference_id field to store the reference number returned by your KYC provider.

Note
When you submit a KYC verification request with manual_override=false, the Marqeta platform performs the verification through one of its KYC providers. If the KYC provider responds with a reference ID, that ID is passed to you by way of this field in the response.

Allowable Values:

32 char max

user_token

OR

business_token

string, required

Specifies the account holder on which to perform the identity check.

Pass either user_token or business_token, not both.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.

Body field details (response)

Fields Description

created_time

datetime, required

Time the KYC check was performed.

Allowable Values:

last_modified_time

datetime, required

Time the KYC was last updated.

Allowable Values:

token

string, optional

The unique identifier of the identity check.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

36 char max

user_token

OR

business_token

string, optional

The account holder on which the identity check is performed.

Either user_token or business_token, not both.

Allowable Values:

Existing user or business token.

result

object, optional

Contains information about the KYC result.

Allowable Values:

manual_override

boolean, optional

If true, the account holder is designated as having passed a verification check without Marqeta performing the check.

This override is used when verification is performed through another mechanism, such as with an alternative KYC provider or directly with the account holder.

Allowable Values:

true, false

Default: false

notes

string, optional

Notes pertaining to a manual override. This field is included in the response only when the manual_override field is set to true.

Allowable Values:

questions

object, optional

Contains information about the questions presented during the check.

Allowable Values:

reference_id

string, optional

This field is included in the response only when the manual_override field is set to true. If you verified the account holder’s identity by performing a KYC verification outside of the Marqeta platform, you can use the reference_id field to store the reference number returned by your KYC provider.

Note
When you submit a KYC verification request with manual_override=false, the Marqeta platform performs the verification through one of its KYC providers. If the KYC provider responds with a reference ID, that ID is passed to you by way of this field in the response.

Allowable Values:

32 char max

The result object (response)

Fields Description

status

string, optional

Status of the KYC check.

Allowable Values:

codes

object, optional

Contains information about the KYC result codes.

Allowable Values:

failed_questions_count

integer, optional

Keeps the count of incorrect answers to questions.

Allowable Values:

0–5

The questions object (response)

Fields Description

key

string, optional

Acceptable answers to the question.

Allowable Values:

question

string, optional

The challenge question presented.

Allowable Values:

answers

array, optional

Answers given in response to the question.

Allowable Values:

The result.codes object (response)

Fields Description

created_time

datetime, required

Time the KYC check was performed.

Allowable Values:

last_modified_time

datetime, required

Time the KYC was last updated.

Allowable Values:

token

string, optional

The unique identifier of the identity check.

If you did not include a token in your request, the system automatically generated one. This token is necessary for use in other API calls. This value cannot be updated.

Allowable Values:

36 char max

user_token

OR

business_token

string, optional

The account holder on which the identity check is performed.

Either user_token or business_token, not both.

Allowable Values:

Existing user or business token.

result

object, optional

Contains information about the KYC result.

Allowable Values:

manual_override

boolean, optional

If true, the account holder is designated as having passed a verification check without Marqeta performing the check.

This override is used when verification is performed through another mechanism, such as with an alternative KYC provider or directly with the account holder.

Allowable Values:

true, false

Default: false

notes

string, optional

Notes pertaining to a manual override. This field is included in the response only when the manual_override field is set to true.

Allowable Values:

questions

object, optional

Contains information about the questions presented during the check.

Allowable Values:

reference_id

string, optional

This field is included in the response only when the manual_override field is set to true. If you verified the account holder’s identity by performing a KYC verification outside of the Marqeta platform, you can use the reference_id field to store the reference number returned by your KYC provider.

Note
When you submit a KYC verification request with manual_override=false, the Marqeta platform performs the verification through one of its KYC providers. If the KYC provider responds with a reference ID, that ID is passed to you by way of this field in the response.

Allowable Values:

32 char max

The result object (response)

Fields Description

status

string, optional

Status of the KYC check.

Allowable Values:

codes

object, optional

Contains information about the KYC result codes.

Allowable Values:

failed_questions_count

integer, optional

Keeps the count of incorrect answers to questions.

Allowable Values:

0–5

The questions object (response)

Fields Description

key

string, optional

Acceptable answers to the question.

Allowable Values:

question

string, optional

The challenge question presented.

Allowable Values:

answers

array, optional

Answers given in response to the question.

Allowable Values:

The result.codes object (response)

Fields Description

code

string, optional

Result code.

Allowable Values:

message

string, optional

Result code description.

Allowable Values:

User KYC failure codes (response)

The following table lists KYC failure codes potentially returned in the response when a user fails verification.

Failure Code Failure Description

AddressIssue

Missing, invalid, mismatched, or P.O. box address.

DateofBirthIssue

Invalid or mismatched date of birth.

DriversLicenseIssue

Invalid or unknown driver’s license number.

EmailIssue

Unknown email address or high-risk characteristics.

IPAddressIssue

Unknown location or high-risk characteristics.

NameIssue

Invalid or mismatched name.

OFAC

Appears on an Office of Foreign Assets Control (OFAC) list.

PhoneIssue

Unknown, mismatched, or invalid phone number.

RiskIssue

Appears on a non-OFAC screening list, bankruptcy, or alert list, or has a thin record.

SSNIssue

Missing, invalid, or mismatched Social Security Number (SSN), or SSN is of a deceased person.

Business KYC failure codes (response)

The following table lists KYC failure codes potentially returned in the response when a business fails verification.

Failure Code Failure Description

AddressIssue

Missing, invalid, mismatched, or P.O. box address.

NameIssue

Invalid or mismatched name.

OFAC

Appears on an OFAC list.

PhoneIssue

Unknown, mismatched, or invalid phone number.

RegistrationIssue

Inactive, not registered, or not in good standing with the Secretary of State, or recently reported or not recently updated.

RiskIssue

Appears on a non-OFAC screening list, bankruptcy, alert list, or has a thin record.

TINIssue

Missing, invalid, or mismatched Tax Identification Number (TIN).

Sample request body

{
  "token": "my_kyc01",
  "user_token": "my_user01",
  "manual_override": false
}

Is this helpful?

Sample response bodies

KYC verifications on users (but not businesses) can potentially return a questions field in the response. Whether or not a questions field is returned depends on the identity-check provider and whether challenge questions are available for the user. The following sample response body shows this questions field.

{
  "token": "my_kyc01",
  "questions": [
    {
      "key": "alternate.names.phone",
      "question": "With which name are you associated?",
      "answers": [
        "WINQUIST",
        "WALKER",
        "WALEED",
        "WINCHEZ",
        "None of the above"
      ]
    },
    {
      "key": "prior.residence.state.multiyear",
      "question": "Between 1979 and 1980, in which State did you live?",
      "answers": [
        "KENTUCKY",
        "MISSOURI",
        "KANSAS",
        "NEW YORK",
        "None of the above"
      ]
    }
  ],
  "user_token": "my_user01",
  "result": {
    "status": "pending",
    "codes": [
      {
        "code": "low risk score"
      }
    ]
  },
  "manual_override": false,
  "created_time": "2016-02-08T19:52:58Z",
  "last_modified_time": "2016-02-08T19:52:58Z"
}

Is this helpful?

A failed KYC check on a business returns failure codes such as those shown in the following response:

{
  "created_time": "2017-03-04T00:28:09Z",
  "last_modified_time": "2017-03-04T00:28:09Z",
  "token": "my_business_01_kyc_01",
  "business_token": "my_business_01",
  "result": {
    "status": "failure",
    "codes": [
      {
        "code": "failed check: TINIssue"
      },
      {
        "code": "failed check: AddressIssue"
      }
    ]
  },
  "manual_override": false
}

Is this helpful?

Retrieve KYC result

Action: GET
Endpoint: /kyc/{token}

Use this endpoint to retrieve a specific KYC result.

URL path parameters

Fields Description

token

string, required

Identifies the KYC result to retrieve.

Allowable Values:

Existing KYC token.

Send a GET request to /kyc/user/{user_token} to retrieve KYC tokens for a particular user or to /kyc/business/{business_token} to retrieve KYC tokens for a particular business.

Get started now!

Sign up today and get access to Marqeta's API Explorer

Sample response body

{
  "created_time": "2017-03-07T22:52:39Z",
  "last_modified_time": "2017-03-07T22:52:39Z",
  "token": "my_user_01_kyc_01",
  "user_token": "my_user_01",
  "result": {
    "status": "failure",
    "codes": [
      {
        "code": "full_ssn_required"
      }
    ]
  },
  "manual_override": false
}

Is this helpful?

Update KYC with answers

Action: PUT
Endpoint: /kyc/{token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

If a user fails KYC and the original KYC returns a questions field, use this endpoint to update the KYC with answers. (You obtain the answers by way of a separate request to the user.)

Note
A program-level setting determines the amount of time provided to answer the questions. The default value is 240 seconds. Marqeta can adjust this setting if necessary.

URL path parameters

Fields Description

token

string, required

Identifies the KYC to update.

Allowable Values:

Existing KYC token.

Send a GET request to /kyc/user/{user_token} to retrieve KYC tokens for a particular user or to /kyc/business/{business_token} to retrieve KYC tokens for a particular business.

Body field details (request)

Fields Description

answers

object, required

Contains information about acceptable answers to a KYC challenge question.

Allowable Values:

Send a GET request to /kyc/user/{user_token} to retrieve KYC tokens for a particular user or to /kyc/business/{business_token} to retrieve KYC tokens for a particular business.

The answers object (request)

Fields Description

answer

string, optional

Answer given in response to a challenge question.

Allowable Values:

key

string, optional

Acceptable answer to the challenge question.

Allowable Values:

Sample request body

{
  "answers": [
    { "key": "alternate.names.phone", "answer": "None of the above" },
    { "key": "prior.residence.state.multiyear", "answer": "NEW YORK" }
  ]
}

Is this helpful?

Sample response body

{
  "token": "my_kyc01",
  "user_token": "my_user01",
  "result": {
    "status": "failure",
    "codes": [
      {
        "code": "low risk score"
      }
    ]
  },
  "manual_override": false,
  "created_time": "2016-02-08T19:52:58Z",
  "last_modified_time":  "2016-02-08T19:52:58Z"
}

Is this helpful?

List KYC results for user

Action: GET
Endpoint: /kyc/user/{user_token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve all KYC results for a user.

This endpoint supports field filtering and pagination.

URL path parameters

Fields Description

user_token

string, required

Identifies the user whose KYC results you want to list.

Allowable Values:

Existing user token

Send a GET request to /users to retrieve user tokens.

count

integer, optional

Number of items to retrieve.

Allowable Values:

Default: 5

start_index

integer, optional

Start index.

Allowable Values:

Default: 0

fields

string, optional

Comma-delimited list of fields to return (e.g. question,answers,key,..). Leave blank to return all fields.

Allowable Values:

sort_by

string, optional

Sort order.

Allowable Values:

Default: -createdTime

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "created_time": "2017-03-07T23:17:36Z",
      "last_modified_time": "2017-03-07T23:17:36Z",
      "token": "my_user_01_kyc_02",
      "user_token": "my_user_01",
      "result": {
        "status": "failure",
        "codes": [
          {
            "code": "unknown"
          }
        ]
      },
      "manual_override": false
    },
    {
      "created_time": "2017-03-07T22:52:39Z",
      "last_modified_time": "2017-03-07T22:52:39Z",
      "token": "my_user_01_kyc_01",
      "user_token": "my_user_01",
      "result": {
        "status": "failure",
        "codes": [
          {
            "code": "full_ssn_required"
          }
        ]
      },
      "manual_override": false
    }
  ]
}

Is this helpful?

List KYC results for business

Action: GET
Endpoint: /kyc/business/{business_token}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Use this endpoint to retrieve all KYC results for a business.

This endpoint supports field filtering and pagination.

URL path parameters

Fields Description

business_token

string, required

Identifies the business whose KYC results you want to list.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve business tokens.

count

integer, optional

Number of items to retrieve.

Allowable Values:

Default: 5

start_index

integer, optional

Start index.

Allowable Values:

Default: 0

fields

string, optional

Comma-delimited list of fields to return (e.g. question,answers,key,..). Leave blank to return all fields.

Allowable Values:

sort_by

string, optional

Sort order.

Allowable Values:

Default: -createdTime

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "created_time": "2017-03-06T19:06:32Z",
      "last_modified_time": "2017-03-06T19:06:32Z",
      "token": "89807a33-f46f-4562-b068-52a5de769542",
      "business_token": "my_business_01",
      "result": {
        "status": "success"
      },
      "manual_override": true
    },
    {
      "created_time": "2017-03-04T00:28:09Z",
      "last_modified_time": "2017-03-04T00:28:09Z",
      "token": "my_business_01_kyc_01",
      "business_token": "my_business_01",
      "result": {
        "status": "failure",
        "codes": [
          {
            "code": "failed check: BizTaxIDFailure"
          },
          {
            "code": "failed check: OtherFailure"
          }
        ]
      },
      "manual_override": false
    }
  ]
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.