The Know Your Customer (KYC) API Calls

Use the KYC API calls to gather all the information about a merchant required to complete the onboarding process and enable withdrawals to be made. All KYC API calls require WePay permission.

Tokenization

KYC Structures

KYC States

The /account/kyc object has the following states and possible state transitions:

unsubmitted No KYC information has been submitted by the user.
unverified KYC information has been submitted by the user, but no verification attempts have been made. No action is needed by the user at this time.
require_docs The user must upload documents to prove their identity.
in_review WePay is reviewing the submitted KYC information.
verified The user’s identity is verified, either synchronously or asynchronously.

kyc states

Version: v2 2017-02-01

POST Endpoint

https://wepayapi.com/v2/account/kyc

/account/kyc

This call provides information about the status of the account’s KYC information and any documents that may have been uploaded.

Arguments

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account for which you are seeking KYC information.

Example

{
   "account_id": 88113344
}

Response

Response Type Description
account_id Integer (64 bits) The unique ID of the account.
state String The state of KYC for the account.

Possible values: unsubmitted, unverified, in_review, require_docs, and verified.
supporting_documents Array Array of document structures that contains information about each individual document submitted by the user for verification. Note that not all accounts require documentation to complete KYC.
legal_name Name Structure The legal name of the account owner.

Example

{
  "account_id": 1091778617,
  "state": "verified",
  "supporting_documents": [
   {
      "file_id": 5678,
      "type": "social_security_card",
      "state": "rejected",
      "reject_reason": "illegible",
      "create_time": 1480700500000
    },
    {
      "file_id": 1234,
      "type": "social_security_card",
      "state": "verified",
      "reject_reason": null,
      "create_time": 1480700611000
    },
    {
      "file_id": 9101,
      "type": "current_utility_bill",
      "state": "verified",
      "reject_reason": null,
      "create_time": 1480700611000
    }
  ],
  "legal_name": {
    "first": "Foo",
    "last": "Bar"
  }
}

/account/kyc/create

Use this call to gather the KYC information necessary to complete the merchant onboarding process. The /account/kyc/create call must be completed before withdrawals can be setup. Additionally, the /account/kyc/create API may not be called after withdrawals have been made. Changes after any withdrawal has been made require intervention by WePay Customer Support and are generally discouraged.

After KYC information is submitted, it may not be modified through an API. Any necessary changes must be made through WePay Customer Support.

The account for which KYC information is being submitted must be active (the access token for the account must have been confirmed). See the /account API documentation for more information.

The call must be error free. Any error returned will result in the failure of the entire call.

Arguments

Parameter Required Type Description
client_id Yes String (255 chars) A unique ID for the application.
account_id Yes String (255 chars) The unique ID of the account for which KYC information is being submitted.
individual Yes* Individual Structure Required if neither business or organization are not specified.

See the Individual Structure section for more information.
business Yes* Business Structure Required if neither individual or organization are not specified.

See the Business Structure section for more information.
organization Yes* Organization Structure Required if neither individual or business are not specified.

See the Organization Structure section for more information.

Tip

Merchant Category Codes (MCC) for the UK (used in the Business, Individual, and Organization Structures) must a valid UK MCC as defined in the MCC Codes document.

Example

{
   "client_id": "9876",
   "account_id": "1234",
   "business": {
      "account_owner": {
         "name": {
            "first": "Foo",
            "last": "Bar"
         },
         "phone": {
            "country_code": "+1",
            "phone_number": "5556667777"
         },
         "date_of_birth": {
            "year": 1900,
            "month": 1,
            "day": 1
         },
         "address": {
            "address1": "456 Diagon Alley",
            "city": "London",
            "postal_code": "CM6 4HB",
            "region": "",
            "country": "GB"
         },
         "email": "example@example.com",
         "gb_owner_compliance": {
            "is_beneficial_owner": true
         }
      },
      "legal_entity_name": "Foo Bar Inc",
      "primary_url": "http://www.example.com",
      "entity_description": "Foo Bar Inc does important work.",
      "address": {
         "address1": "123 Fake Street",
         "city": "London",
         "postal_code": "CM6 4HB",
         "region": "",
         "country": "GB"
      },
      "gb_entity_compliance": {
         "company_number": "1234",
         "legal_form": "partnership",
         "additional_beneficial_owners": [
            {
               "name": {
                  "first": "Bizz",
                  "last": "Buzz"
               },
               "address": {
                  "address1": "456 Fake Street",
                  "city": "London",
                  "postal_code": "CM6 4HB",
                  "region": "",
                  "country": "GB"
               },
               "date_of_birth": {
                  "year": 1900,
                  "month": 1,
                  "day": 1
               }
            }
         ]
      }
   }
}

Response

Response Type Description
kyc_id Integer (64 bits) A unique ID for the newly created KYC object.

Example

 {
   "kyc_id":12345
 }

/account/kyc/authorize

After KYC information has been entered via the /account/kyc/create call, the data must be verified as originating from a valid application by means of a server-to-server call. The response to this call is the same as the response to /account/kyc.

Arguments

Parameter Required Type Description
kyc_id Yes Integer (64 bits) A unique KYC ID returned by the /account/kyc/create call.

Example

{
  "kyc_id": "12345"
}

Response

Response Type Description
account_id Integer (64 bits) The unique ID of the account.
state String The state of KYC for the account.

Possible values: unsubmitted, unverified, in_review, require_docs, and verified.
supporting_documents Array Array of document structures that contains information about each individual document submitted by the user for verification. Note that not all accounts require documentation to complete KYC.
legal_name Name Structure The legal name of the account owner.

Example

{
  "account_id": 1091778617,
  "state": "verified",
  "supporting_documents": [
   {
      "file_id": 5678,
      "type": "social_security_card",
      "state": "rejected",
      "reject_reason": "illegible",
      "create_time": 1480700500000
    },
    {
      "file_id": 1234,
      "type": "social_security_card",
      "state": "verified",
      "reject_reason": null,
      "create_time": 1480700611000
    },
    {
      "file_id": 9101,
      "type": "current_utility_bill",
      "state": "verified",
      "reject_reason": null,
      "create_time": 1480700611000
    }
  ],
  "legal_name": {
    "first": "Foo",
    "last": "Bar"
  }
}

/account/kyc/modify

This call allows your application to amend an account’s KYC submission with additional data, such as supporting documentation. This call returns the same response as the /account/kyc call.

Arguments

Parameter Required Type Description
account_id Yes Integer (64 bits) The unique ID of the account you want to modify.
file_ids Yes Array of integers (64 bits) The array of file IDs to be reviewed by WePay.

Example

{
   "account_id": 1234555,
   "file_ids": [ 1234, 5678, 9101 ]
}

Response

Response Type Description
account_id Integer (64 bits) The unique ID of the account.
state String The state of KYC for the account.

Possible values: unsubmitted, unverified, in_review, require_docs, and verified.
supporting_documents Array Array of document structures that contains information about each individual document submitted by the user for verification. Note that not all accounts require documentation to complete KYC.
legal_name Name Structure The legal name of the account owner.

Example

{
  "account_id": 1091778617,
  "state": "verified",
  "supporting_documents": [
   {
      "file_id": 5678,
      "type": "social_security_card",
      "state": "rejected",
      "reject_reason": "illegible",
      "create_time": 1480700500000
    },
    {
      "file_id": 1234,
      "type": "social_security_card",
      "state": "verified",
      "reject_reason": null,
      "create_time": 1480700611000
    },
    {
      "file_id": 9101,
      "type": "current_utility_bill",
      "state": "verified",
      "reject_reason": null,
      "create_time": 1480700611000
    }
  ],
  "legal_name": {
    "first": "Foo",
    "last": "Bar"
  }
}

Tokenization

WePay provides a JavaScript Library for tokenization of KYC information such that no sensitive information is transmitted through a partner’s server.

The JavaScript tokenization library handles the /account/kyc/create process. After a successful /account/kyc/create call, to ensure that the information came from a trusted source, your app must make an /account/kyc/authorize call within 30 minutes.

Loading the JavaScript Library

You must load the WePay JavaScript Library (kyc.1.latest.js). See the example at right. You must set the endpoint to production when you make your app live.

JavaScript Example

KYC Structures

The following structures are integral to the /account/kyc/create call.

Account Owner Structure

Contains details about the owner of an account.

Fields

Field Required Type Description
name Yes Name Structure The user's full name.
email No String (255 chars) The user's email address.
date_of_birth Yes Date Structure The user's date of birth.
address Yes KYC Address Structure The user's full address
phone Yes Phone Structure The user's phone number.
ca_owner_compliance Yes * CA Owner Compliance Structure Canada specific owner fields. Required for Canadian entities only.
gb_owner_compliance Yes * GB Owner Compliance Structure UK specific owner information. Required for UK entities only.
us_owner_compliance Yes * US Owner Compliance Structure U.S. specific owner information. Required for US entities only.

Example

{
   "account_owner": {
      "name": {
         "first": "Foo",
         "last": "Bar"
      },
      "phone": {
         "country_code": "+1",
         "phone_number": "5556667777"
      },
      "date_of_birth": {
         "year": 1900,
         "month": 1,
         "day": 1
      },
      "address": {
         "address1": "456 Diagon Alley",
         "city": "London",
         "postal_code": "CM6 4HB",
         "region": "",
         "country": "GB"
      },
      "email": "example@example.com",
      "gb_owner_compliance": {
         "is_beneficial_owner": true
      }
   }
}

Individual Structure

The KYC Individual Structure contains information about an account owner who is an individual (as opposed to a business or an organization).

Fields

Field Required Type Description
account_owner Yes Account Owner Structure The individual owner.
mcc Yes String (255 chars) The Merchant Category Code (MCC) that specifies the industry associated with the business. See the MCC Page for more information.
primary_url No String (255 chars) The URL of the individual's website.

Example

{
   "individual": {
      "account_owner": {
         "name": {
            "first": "Foo",
            "last": "Bar"
         },
         "address": {
            "address1": "123 Fake Street",
            "city": "Montreal",
            "postal_code": "H3Z 2Y7",
            "region": "QC",
            "country": "CA"
         },
         "phone": {
            "country_code": "+1",
            "phone_number": "5556667777"
         },
         "date_of_birth": {
            "year": 1900,
            "month": 1,
            "day": 1
         },
         "email": "example@example.com",
         "ca_owner_compliance": {
            "social_insurance_number": "046 454 286"
         }
      },
    "mcc": 7999,
    "primary_url": "https://www.foobar.com"
   }
}

Business Structure

Contains information about the business owner, the name, address, and website of the business.

Fields

Field Required Type Description
account_owner Yes Account Owner Structure Information about the account owner.
legal_entity_name Yes String (255 chars) The name of the business.
primary_url Yes String (255 chars) The URL of the business website.
entity_description Yes String (255 chars) A description of the business.
address Yes KYC Address Structure The full business address.
mcc No String (255 chars) The Merchant Category Code (MCC) that specifies the industry associated with the business. See the MCC Page for more information.
ca_entity_compliance Yes * CA Entity Compliance Structure Canada specific fields. Required for Canadian entities only.
gb_entity_compliance Yes * GB Entity Compliance Structure UK specific fields. Required for UK entities only.
us_entity_compliance Yes * US Entity Compliance Structure US specific fields. Required for US entities only.

Example

{
   "business": {
      "account_owner": {
         "name": {
            "first": "Foo",
            "last": "Bar"
         },
         "phone": {
            "country_code": "+1",
            "phone_number": "5556667777"
         },
         "date_of_birth": {
            "year": 1900,
            "month": 1,
            "day": 1
         },
         "address": {
            "address1": "456 Diagon Alley",
            "city": "London",
            "postal_code": "CM6 4HB",
            "region": "",
            "country": "GB"
         },
         "email": "example@example.com",
         "gb_owner_compliance": {
            "is_beneficial_owner": true
         }
      },
      "legal_entity_name": "Foo Bar Inc",
      "primary_url": "http://www.example.com",
      "entity_description": "Foo Bar Inc does important work.",
      "address": {
         "address1": "123 Fake Street",
         "city": "London",
         "postal_code": "CM6 4HB",
         "region": "",
         "country": "GB"
      },
      "gb_entity_compliance": {
         "company_number": "1234",
         "legal_form": "partnership",
         "additional_beneficial_owners": [{
            "name": {
               "first": "Bizz",
               "last": "Buzz"
            },
            "address": {
               "address1": "456 Fake Street",
               "city": "London",
               "postal_code": "CM6 4HB",
               "region": "",
               "country": "GB"
            },
            "date_of_birth": {
               "year": 1900,
               "month": 1,
               "day": 1
            }
         }]
      }
   }
}

Organization Structure

This structure describes an organization and its compliance information.

Fields

Field Required Type Description
account_owner Yes Account Owner Structure Information about the account owner.
legal_entity_name Yes String (255 chars) The legal name of the organization.
primary_url Yes String (255 chars) The URL of the organization's website.
entity_description Yes String (255 chars) A description of the organization.
address Yes KYC Address Structure The full business address of the organization.
mcc No String (255 chars) The Merchant Category Code (MCC) that specifies the industry associated with the business. See the MCC Page for more information.
ca_entity_compliance Yes * CA Entity Compliance Structure Canada specific fields. Required for Canadian entities only.
gb_entity_compliance Yes * GB Entity Compliance Structure UK specific fields. Required for UK entities only.
us_entity_compliance Yes * US Entity Compliance Structure US specific fields. Required for US entities only.

Example

{
   "organization": {
      "account_owner": {
         "name": {
            "first": "Foo",
            "last": "Bar"
         },
         "phone": {
            "country_code": "+1",
            "phone_number": "5556667777"
         },
         "date_of_birth": {
            "year": 1900,
            "month": 1,
            "day": 1
         },
         "address": {
            "address1": "456 Diagon Alley",
            "city": "London",
            "postal_code": "CM6 4HB",
            "region": "",
            "country": "GB"
         },
         "email": "example@example.com",
         "gb_owner_compliance": {
            "is_beneficial_owner": true
         }
      },
      "legal_entity_name": "Foo Bar Inc",
      "primary_url": "http://www.example.com",
      "entity_description": "Foo Bar Inc does important work.",
      "address": {
         "address1": "123 Fake Street",
         "city": "London",
         "postal_code": "CM6 4HB",
         "region": "",
         "country": "GB"
      },
      "mcc":"1900",
      "gb_entity_compliance": {
         "company_number": "1234",
         "legal_form": "partnership",
         "additional_beneficial_owners": [{
            "name": {
            "first": "Bizz",
            "last": "Buzz"
            },
            "address": {
               "address1": "456 Fake Street",
               "city": "London",
               "postal_code": "CM6 4HB",
               "region": "",
               "country": "GB"
            },
            "date_of_birth": {
               "year": 1900,
               "month": 1,
               "day": 1
            }
         }]
      }
   }
}

CA Entity Compliance Structure

This structure is used for Canadian entities only.

Fields

Field Required Type Description
gst_hst Yes* String (255 chars) The GST/HST number used to validate a legal business or nonprofit organization in Canada. This field is required for businesses and nonprofit organizations. This field is optional for individuals.

Example

{
  "ca_entity_compliance": {
    "gst_hst": "123456789RT0001"
  }
}

GB Entity Compliance Structure

This structure is used only for entities in Great Britain.

Fields

Field Required Type Description
company_number No String (255 chars) The company_number used to validate a legal business in the UK.
legal_form Yes String (255 chars) The type of business.

Valid options are: sole_trader, partnership, private_limited_company, public_limited_company, limited_liability_partnership, and charity

additional_beneficial_owners Yes Array of Beneficial Owner Owners the holds more than 25 percent of the company.

Example

{
   "legal_form": "partnership",
   "beneficial_owner": [{
      "name": {
         "first": "john",
         "last": "doe"
      },
      "address": {
         "address1": "123 Fake Street",
         "city": "London",
         "postal_code": "EC1Y 8SY",
         "region": null,
         "country": "GB"
      },
      "date_of_birth": {
         "year": 1926,
         "month": 3,
         "day": 1
      }
   }]
}

US Entity Compliance Structure

This structure is used for U.S. entities only.

Fields

Field Required Type Description
ein Yes* String (255 chars) The EIN used to validate a legal business or nonprofit organization in the US. This field is required for businesses and nonprofit organizations. This field is optional for individuals.

Example

{
   "ein": "12-1234567"
}

CA Owner Compliance Structure

Contains information used to identify a user in Canada.

Fields

Field Required Type Description
social_insurance_number No String (255 chars) The Social Insurance Number (SIN) number used to identify an individual in Canada.

The SIN number must be of the form nnn-nnn-nnn and consist only of digits 0 through 9.

Example

{
   "social_insurance_number": "123-456-789"
}

GB Owner Compliance Structure

Contains information about whether the owner is also a beneficial owner.

Fields

Field Required Type Description
is_beneficial_owner Yes Boolean Value of true indicates the user is also a beneficial owner of the account.

Example

{
   "is_beneficial_owner": false
}

US Owner Compliance Structure

Contains information identifying a US Owner as a valid person.

Tip

social_security_number_last_4 is accepted for all US merchants upon the first submission of KYC. The full 9 digit social_security_number must be submitted for US merchants of type individual that do not pass synchronous KYC validation upon the first submission.

Fields

Field Required Type Description
social_security_number Yes * String (255 chars) The user's government issued Social Security Number (SSN), used for identification.

The SSN must be in form nnn-nn-nnnn where only digits between 0 and 9 are valid.
social_security_number_last_4 Yes * String (255 chars) The last four digits of the user's goverment issued Social Security Number (SSN).

The number must be exactly 4 digits (values 0 through 9) in length.

Example Full Social Security Number

{
   "us_owner_compliance": {
      "social_security_number": "111-22-1234",
      "social_security_number_last_4": null
   }
}

Example Last Four Digits Only

{
   "us_owner_compliance": {
      "social_security_number": null,
      "social_security_number_last_4": "1234"
   }
}

Beneficial Owner Structure

Contains basis identity and location information about a beneficial owner.

Fields

Field Required Type Description
name Yes Name Structure The name of the beneficial owner.
address Yes KYC Address Structure The address of the beneficial owner.
date_of_birth Yes Date Structure The birthdate of the beneficial owner.

Example

{
   "beneficial_owner": {
      "name": {
         "first": "John",
         "middle": "Quincy",
         "last": "Adams"
      }
   },
   "address": {
      "address1": "123 Fake Street",
      "city": "Montreal",
      "postal_code": "H3Z 2Y7",
      "region": "QC",
      "country": "CA"
   },
   "date_of_birth": {
      "year": 1900,
      "month": 1,
      "day": 1
   }
}

Date Structure

Contains standard formatted date information about an individual’s date of birth.

Fields

Field Required Type Description
year Yes Integer (64 bits) The year of the user's birth.
month Yes Integer (64 bits) The month (values 1 through 12) of the user's birth.
day Yes Integer (64 bits) The day of the month (values 1 through 31) of the user's birth.

Example

{
   "date_of_birth": {
      "year": 1900,
      "month": 1,
      "day": 1
   }
}

Phone Structure

Contains the user’s or entity’s registered phone number.

Fields

Field Required Type Description
country_code Yes String (255 chars) The country code of the primary phone number entered by the user.
phone_number Yes String (255 chars) The primary phone number entered by the user.

Example

{
   "phone": {
      "country_code": "+1",
      "phone_number": "5556667777"
   }
}

KYC Address Structure

Contains the user’s address information, including region and postcode.

Fields

Field Required Type Description
address1 Yes String (255 chars) The street address where the user resides. In the US, this parameter must begin with a digit and not contain PO.
address2 No String (255 chars) A continuation of the users address.
city Yes String (255 chars) The city where the user resides.
region Yes String (255 chars) The region where the user resides.
postal_code Yes String (255 chars) The postcode where the user resides.
country Yes String (255 chars) The country where the user resides.

Example

{
   "address": {
      "address1": "456 Diagon Alley",
      "city": "London",
      "postal_code": "CM6 4HB",
      "region": "",
      "country": "GB"
   }
}

Name Structure

Contains the full name of the user.

Fields

Field Required Type Description
first Yes String (35 chars) The user's first name. Truncated after the first 35 characters.
middle No String (35 chars) The user's middle name. Truncated after the first 35 characters.
last Yes String (35 chars) The user's last name. Truncated after the first 35 characters.

Caution

WePay concatenates the first and middle names and then truncates the string to the first 35 characters.

Example

{
    "first":"John",
    "middle":"Quincy",
    "last":"Adams"
}