The Know Your Customer (KYC) API Calls
Warning
The /account/kyc endpoint is deprecated. This page is available for Partners using the legacy endpoint as a reference.
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
- Account Owner Structure
- Individual Structure
- Business Structure
- Organization Structure
- CA Entity Compliance Structure
- US Entity Compliance Structure
- CA Owner Compliance Structure
- US Owner Compliance Structure
- Additional Beneficial Owners
- Date Structure
- Phone Structure
- KYC Address Structure
- Name Structure
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. |
Version: v2 2019-04-03
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. |
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": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"ca_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": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"ca_entity_compliance": {
"gst_hst": "123456789RT0001",
"legal_form": "partnership",
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"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.
Note
The /account/kyc/authorize call must be made within 30 minutes of making the /account/kyc/create.
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/get_details
Use this call in order to eliminate redundancies in KYC collection for your users. In response to this call, WePay will identify the information that has already been provided so that your platform does not need to ask for it.
Arguments
| Parameter | Required | Type | Description |
| account_id | Yes | Integer (64 bits) | The account ID for which KYC details are being retrieved. |
Example
{
"account_id": 123456789
}
Response
| Response | Type | Description |
| individual | Individual Response | Returned if neither business or organization are present.
See the Individual Response section for more information. |
| business | Business Response | Returned if neither individual or organization are present.
See the Business Response section for more information. |
| organization | Organization Response | Returned if neither individual or business are present.
See the Organization Response section for more information. |
Example
{
"business": {
"account_owner": {
"name": {
"first": "Foo",
"last": "Bar"
},
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"date_of_birth_is_present": true,
"address": {
"address1": "456 Diagon Alley",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"job_title": "cfo",
"ca_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": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"us_entity_compliance": {
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Redwood City",
"postal_code": "94063",
"region": "CA",
"country": "US"
},
"date_of_birth_is_present": true,
"us_owner_compliance": {
"social_security_number_is_present": true
},
"phone": {
"country_code": "+1",
"phone_number": "6666667777"
}
}
]
},
"ein": "12-1234567",
"legal_form": "limited_liability_company"
}
}
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. |
| 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. |
| job_title | Yes * | String (255 chars) | The controller's job title. We recommend displaying the following common controller job titles in your user interface:
|
| ca_owner_compliance | Yes * | CA Owner Compliance Structure | Canada specific owner fields. Required for Canadian entities and individuals. |
| us_owner_compliance | Yes * | US Owner Compliance Structure | U.S. specific owner information. Required for US entities and individuals. |
Note
For business and nonprofit organization merchants, account_owner represents the controller. Your platform must use the term “controller” in your KYC user interface.
legal entity customer, including an executive officer or senior manager (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer); or any other individual who regularly performs similar functions (i.e., the control prong). This list of positions is illustrative, not exclusive, as there is significant diversity in how legal entities are structured.
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": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"job_title": "cfo",
"ca_owner_compliance": {
"is_beneficial_owner": true
}
}
}
Account Owner Response
Contains details about the owner of an account.
Fields
| Field | Type | Description |
| name | Name Response | The user's full name. |
| String (255 chars) | The user's email address. | |
| date_of_birth_is_present | Boolean | Shows whether the date of birth was provided. |
| address | KYC Address Response | The user's full address |
| phone | Phone Response | The user's phone number. |
| job_title | String (255 chars) | The controller's job title submitted. |
| ca_owner_compliance | CA Owner Compliance Response | Canada specific owner fields. Returned for Canadian entities and individuals. |
| us_owner_compliance | US Owner Compliance Response | U.S. specific owner information. Required for US entities and individuals. |
Example
{
"account_owner": {
"name": {
"first": "Foo",
"last": "Bar"
},
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"date_of_birth_is_present": true,
"address": {
"address1": "456 Diagon Alley",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"job_title": "cfo",
"ca_owner_compliance": {
"is_beneficial_owner": true
}
}
}
Individual Structure
The KYC Individual Structure contains information about an account owner who is an individual sole proprietor (as opposed to a business or an organization with multiple people involved).
Fields
| Field | Required | Type | Description |
| account_owner | Yes | Account Owner Structure | The individual owner. |
| year_of_formation | Yes | Integer | For individuals with the legal form sole_proprietor, provide the year in which the sole proprietorship was founded. This should be the year which paperwork was filed with the IRS. |
| country_of_formation | Yes | String (255 chars) | As opposed to country of operation, this parameter describes a sole proprietor's country of origin. This parameter is required even if the two countries are one and the same, but is only applicable to individuals with the legal form sole_proprietor. |
| sanctioned_countries_operation | Yes* | Array | This parameter is required for individuals with the legal form sole_proprietor on platforms designated as Small and Medium Business.If the merchant has operations in any of the following countries, send the applicable ISO codes in this parameter:
null. The list of countries, in order, are Cuba, Iran, Syria, North Korea, and Crimea Region. |
| significant_beneficiaries | Yes* | Significant Beneficiaries Structure | This is required for individuals with the legal form sole_proprietor if your platform is designated as crowdfunding.Provide an array of information for each beneficiary. Note: While the API parameter references significant beneficiaries, this information must be collected for all beneficiaries of the funds being collected. |
| entity_description | Yes* | String (10000 chars) | A description of the sole proprietor's business. This parameter is required when legal_form is sole_proprietor. |
| 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. |
| ca_entity_compliance | Yes* | CA Entity Compliance Structure | Canada specific fields. Required for Canadian entities and individuals only. |
| us_entity_compliance | Yes* | US Entity Compliance Structure | US specific fields. Required for US entities and individuals only. |
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"
}
},
"year_of_formation": 2009,
"entity_description": "Seller of fine anvils.",
"country_of_formation": "CA",
"sanctioned_countries_operation": [
],
"mcc": 7999,
"primary_url": "https://www.foobar.com",
"ca_entity_compliance": {
"additional_beneficial_owners": [
],
"legal_form": "sole_proprietor"
}
}
}
Individual Structure Response
The KYC Individual Structure contains information about an account owner who is an individual (as opposed to a business or an organization).
Fields
| Field | Type | Description |
| account_owner | Account Owner Resonse | The individual owner. |
| mcc | 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 | String (255 chars) | The URL of the individual's website. |
| ca_entity_compliance | CA Entity Compliance Response | Canada specific fields. Returned for Canadian entities and individuals only. |
| us_entity_compliance | US Entity Compliance Response | US specific fields. Returned for US entities and individuals only. |
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_is_present": true,
"email": "example@example.com",
"ca_owner_compliance": {
"social_insurance_number_is_present": true
}
},
"mcc": 7999,
"primary_url": "https://www.foobar.com",
"ca_entity_compliance": {
"additional_beneficial_owners": [
],
"legal_form": "sole_proprietor"
}
}
}
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. |
| year_of_formation | Yes | Integer | The year in which the business was founded. This should be the year which paperwork was filed with the IRS. |
| country_of_formation | Yes | String (255 chars) | As opposed to country of operation, this parameter describes a business's country of origin. This parameter is required even if the two countries are one and the same. |
| sanctioned_countries_operation | Yes* | Array | This parameter is required for platforms designated as Small and Medium Business. If the merchant has operations in any of the following countries, send the applicable ISO codes in this parameter:
null. The list of countries, in order, are Cuba, Iran, Syria, North Korea, and Crimea Region. |
| significant_beneficiaries | Yes* | Significant Beneficiaries Structure | This is required if your platform is designated as crowdfunding. Provide an array of information for each beneficiary. Note: While the API parameter references significant beneficiaries, this information must be collected for all beneficiaries of the funds being collected. |
| primary_url | No | String (255 chars) | The URL of the business website. |
| phone | Yes | Phone Structure | The phone number for the business. |
| 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. |
| 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": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"job_title": "cfo",
"ca_owner_compliance": {
"is_beneficial_owner": true
}
},
"legal_entity_name": "Foo Bar Inc",
"year_of_formation": 2009,
"country_of_formation": "CA",
"sanctioned_countries_operation": [
"SY",
"CU"
],
"primary_url": "http://www.example.com",
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"entity_description": "Foo Bar Inc does important work.",
"address": {
"address1": "123 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"ca_entity_compliance": {
"gst_hst": "123456789RT0001",
"legal_form": "partnership",
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"date_of_birth": {
"year": 1900,
"month": 1,
"day": 1
}
}
]
}
}
}
Business Response
Contains information about the business owner, the name, address, and website of the business.
Fields
| Field | Type | Description |
| account_owner | Account Owner Response | Information about the account owner. |
| legal_entity_name | String (255 chars) | The name of the business. |
| primary_url | String (255 chars) | The URL of the business website. |
| phone | Phone Structure | The phone number for the business. |
| entity_description | String (255 chars) | A description of the business. |
| address | KYC Address Response | The full business address. |
| mcc | 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 | CA Entity Compliance Response | Canada specific fields. Returned for Canadian entities only. |
| us_entity_compliance | US Entity Compliance Response | US specific fields. Returned for US entities only. |
Example
{
"business": {
"account_owner": {
"name": {
"first": "Foo",
"last": "Bar"
},
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"date_of_birth_is_true": true,
"address": {
"address1": "456 Diagon Alley",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"job_title": "cfo",
"ca_owner_compliance": {
"is_beneficial_owner": true
}
},
"legal_entity_name": "Foo Bar Inc",
"primary_url": "http://www.example.com",
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"entity_description": "Foo Bar Inc does important work.",
"address": {
"address1": "123 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"ca_entity_compliance": {
"gst_hst": "123456789RT0001",
"legal_form": "partnership",
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"date_of_birth_is_present": true
}
]
}
}
}
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. |
| year_of_formation | Yes | Integer | The year in which the organization was founded. This should be the year which paperwork was filed with the IRS or other regulatory bodies. |
| country_of_formation | Yes | String (255 chars) | As opposed to country of operation, this parameter describes a organization's country of origin. This parameter is required even if the two countries are one and the same. |
| significant_beneficiaries | Yes* | Significant Beneficiaries Structure | This is required if your platform is designated as crowdfunding. Provide an array of information for each beneficiary. Note: While the API parameter references significant beneficiaries, this information must be collected for all beneficiaries of the funds being collected. |
| sanctioned_countries_operation | Yes* | Array | This parameter is required for platforms designated as Small and Medium Business. If the merchant has operations in any of the following countries, send the applicable ISO codes in this parameter:
null. The list of countries, in order, are Cuba, Iran, Syria, North Korea, and Crimea Region. |
| primary_url | No | String (255 chars) | The URL of the organization's website. |
| phone | Yes | Phone Structure | The phone number for the organization. |
| 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. |
| 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": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"job_title": "cfo",
"ca_owner_compliance": {
"is_beneficial_owner": true
}
},
"legal_entity_name": "Foo Bar Inc",
"year_of_formation": 2009,
"country_of_formation": "CA",
"significant_beneficiaries": {
"non_domestic_locations": [
"CA"
]
},
"primary_url": "http://www.example.com",
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"entity_description": "Foo Bar Inc does important work.",
"address": {
"address1": "123 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"mcc": "1900",
"ca_entity_compliance": {
"gst_hst": "123456789RT0001",
"legal_form": "partnership",
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"date_of_birth": {
"year": 1900,
"month": 1,
"day": 1
}
}
]
}
}
}
Organization Response
This structure describes an organization and its compliance information.
Fields
| Field | Type | Description |
| account_owner | Account Owner Response | Information about the account owner. |
| legal_entity_name | String (255 chars) | The legal name of the organization. |
| primary_url | String (255 chars) | The URL of the organization's website. |
| phone | Phone Structure | The phone number for the organization. |
| entity_description | String (255 chars) | A description of the organization. |
| address | KYC Address Response | The full business address of the organization. |
| mcc | 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 | CA Entity Compliance Response | Canada specific fields. Returned for Canadian entities only. |
| us_entity_compliance | US Entity Compliance Response | US specific fields. Returned for US entities only. |
Example
{
"organization": {
"account_owner": {
"name": {
"first": "Foo",
"last": "Bar"
},
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"date_of_birth_is_present": true,
"address": {
"address1": "456 Diagon Alley",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"email": "example@example.com",
"job_title": "cfo",
"ca_owner_compliance": {
"is_beneficial_owner": true
}
},
"legal_entity_name": "Foo Bar Inc",
"primary_url": "http://www.example.com",
"phone": {
"country_code": "+1",
"phone_number": "5556667777"
},
"entity_description": "Foo Bar Inc does important work.",
"address": {
"address1": "123 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"mcc": "1900",
"ca_entity_compliance": {
"gst_hst": "123456789RT0001",
"legal_form": "partnership",
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
},
"date_of_birth_is_present": true
}
]
}
}
}
CA Entity Compliance Structure
This structure is used for Canadian entities only.
Fields
| Field | Required | Type | Description |
| additional_ |
Yes* | Array | An array of beneficial owners. *Your platform can pass an empty array if the business does not have any beneficial owners. |
| legal_ |
Yes | String (255 chars) | The type of business. The Individual, Business, and Organization Structures each accept different legal form types. Possible values are listed below.
|
| business_ |
No | String (255 chars) | The business number is used to validate a registered business or nonprofit in Canada. It is required for all businesses/organizations processing in CA:
|
| gst_hst | No | String (255 chars) | The GST/HST number used to validate a legal business or nonprofit organizations in Canada which are enrolled in the Canadian Revenue Agency program. When applicable, this field is required for businesses and nonprofit organizations. This field is optional for individuals. Note: This parameter will be deprecated in a future API version. |
Example
{
"ca_entity_compliance": {
"additional_beneficial_owners": [
{
"name": {
"first": "Bob",
"last": "Smitherson"
},
"address": {
"address1": "456 Fake Street",
"city": "Wandering River",
"postal_code": "T0A 3M0",
"region": "AB",
"country": "CA"
},
"date_of_birth": {
"year": 1991,
"month": 7,
"day": 8
},
"ca_owner_compliance": {
"social_insurance_number": "123-456-789"
},
"phone": {
"country_code": "+1",
"phone_number": "6666667777"
}
}
]
},
"business_number": "123456789",
"legal_form": "limited_liability_company"
}
CA Entity Compliance Response
This structure is used for Canadian entities only.
Fields
| Field | Type | Description |
| additional_ |
Array | An array of beneficial owners. |
| legal_ |
String (255 chars) | The type of business. The Individual, Business, and Organization Structures each return different legal form types. Possible values are listed below.
|
| business_ |
String (255 chars) | The business number is used to validate a registered business or nonprofit in Canada. |
| gst_hst | String (255 chars) | The GST/HST number used to validate a legal business or nonprofit organization in Canada. |
Example
{
"ca_entity_compliance": {
"additional_beneficial_owners": [
{
"name": {
"first": "Bob",
"last": "Smitherson"
},
"address": {
"address1": "456 Fake Street",
"city": "Wandering River",
"postal_code": "T0A 3M0",
"region": "AB",
"country": "CA"
},
"date_of_birth_is_present": true,
"ca_owner_compliance": {
"social_insurance_number_is_present": true
},
"phone": {
"country_code": "+1",
"phone_number": "6666667777"
}
}
]
},
"business_number": "123456789",
"legal_form": "limited_liability_company"
}
US Entity Compliance Structure
This structure is used for U.S. entities only.
Fields
| Field | Required | Type | Description |
| additional_ |
Yes* | Array | An array of beneficial owners. *Your platform can pass an empty array if the business does not have any beneficial owners. |
| 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. |
| legal_form | Yes | String (255 chars) | The type of business. The Individual, Business, and Organization Structures each accept different legal form types. Possible values are listed below.
|
Example
{
"us_entity_compliance": {
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Redwood City",
"postal_code": "94063",
"region": "CA",
"country": "US"
},
"date_of_birth": {
"year": 1991,
"month": 7,
"day": 8
},
"us_owner_compliance": {
"social_security_number_last_4": "6666"
},
"phone": {
"country_code": "+1",
"phone_number": "6666667777"
}
}
]
},
"ein": "12-1234567",
"legal_form": "limited_liability_company"
}
US Entity Compliance Response
This structure is used for U.S. entities only.
Fields
| Field | Type | Description |
| additional_ |
Array | An array of beneficial owners. |
| ein | 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. |
| legal_form | String (255 chars) | The type of business. The Individual, Business, and Organization Structures each return different legal form types. Possible values are listed below.
|
Example
{
"us_entity_compliance": {
"additional_beneficial_owners": [
{
"name": {
"first": "Bizz",
"last": "Buzz"
},
"address": {
"address1": "456 Fake Street",
"city": "Redwood City",
"postal_code": "94063",
"region": "CA",
"country": "US"
},
"date_of_birth_is_present": true,
"us_owner_compliance": {
"social_security_number_is_present": true
},
"phone": {
"country_code": "+1",
"phone_number": "6666667777"
}
}
]
},
"ein": "12-1234567",
"legal_form": "limited_liability_company"
}
CA Owner Compliance Structure
Contains information used to identify a user in Canada.
Fields
| Field | Required | Type | Description |
| social_ |
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. |
| is_beneficial_owner | Yes* | Boolean | Note: This field should only be supplied for business or organization account owners.
TRUE for nonprofit organizations. |
Note
For business and nonprofit organization merchants, account_owner represents the controller. Your platform must use the term “controller” in your KYC user interface.
controller - A single individual with significant responsibility to control, manage, or direct a legal entity customer, including an executive officer or senior manager (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer); or any other individual who regularly performs similar functions (i.e., the control prong). This list of positions is illustrative, not exclusive, as there is significant diversity in how legal entities are structured.
Example
{
"social_insurance_number": "123-456-789",
"is_beneficial_owner": false
}
CA Owner Compliance Response
Contains information used to identify a user in Canada.
Fields
| Field | Type | Description |
| social_ |
Boolean | Identifies if a Social Insurance Number (SIN) number was provided in KYC. |
| is_beneficial_owner | Boolean | Note: This field should only be returned for business or organization account owners.
TRUE for nonprofit organizations. |
Example
{
"social_insurance_number_is_present": true,
"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. If we are unable to validate the personal identity of the merchant or any beneficial owners, then the API call will return an error. The full 9-digit social_security_number must be submitted for US merchants and any beneficial owners 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 government issued Social Security Number (SSN).
The number must be exactly 4 digits (values 0 through 9) in length. |
| is_beneficial_owner | Yes | Boolean | Note: This field should only be supplied for business or organization account owners.
TRUE for nonprofit organizations.
|
Note
For business and nonprofit organization merchants, account_owner represents the controller. Your platform must use the term “controller” in your KYC user interface.
controller - A single individual with significant responsibility to control, manage, or direct a legal entity customer, including an executive officer or senior manager (e.g., a Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, Managing Member, General Partner, President, Vice President, or Treasurer); or any other individual who regularly performs similar functions (i.e., the control prong). This list of positions is illustrative, not exclusive, as there is significant diversity in how legal entities are structured.
Example Full Social Security Number
{
"us_owner_compliance": {
"social_security_number": "111-22-1234",
"social_security_number_last_4": null,
"is_beneficial_owner": false
}
}
Example Last Four Digits Only
{
"us_owner_compliance": {
"social_security_number": null,
"social_security_number_last_4": "1234",
"is_beneficial_owner": false
}
}
US Owner Compliance Response
Contains information identifying a US Owner as a valid person.
Fields
| Field | Type | Description |
| social_security_number_is_present | Boolean | Identifies if SSN was provided in KYC. |
| is_beneficial_owner | Boolean | Note: This field should only be present for business or organization account owners.
TRUE for nonprofit organizations.
|
Example
{
"us_owner_compliance": {
"social_security_number_is_present": true,
"is_beneficial_owner": false
}
}
Additional Beneficial Owner Structure
Personal details associated with additional beneficial owners.
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. |
| phone | Yes | Phone Structure | The phone number of the beneficial owner. |
| ca_owner_compliance | No* | CA Owner Compliance Structure | Social insurance number. *This field is optional if the beneficial owner’s country is Canada. |
| us_owner_compliance | Yes* | US Owner Compliance Structure | Social security last four digits, or full nine digit social security. *This field is required if the beneficial owner’s country is the United States. |
CA example
{
"name": {
"first": "Bob",
"last": "Smitherson"
},
"address": {
"address1": "456 Fake Street",
"city": "Wandering River",
"postal_code": "T0A 3M0",
"region": "AB",
"country": "CA"
},
"date_of_birth": {
"year": 1991,
"month": 7,
"day": 8
},
"ca_owner_compliance": {
"social_insurance_number": "123-456-789"
},
"phone": {
"country_code": "+1",
"phone_number": "6666667777"
}
}
US example
{
"name": {
"first": "Damien",
"last": "Holmes"
},
"address": {
"address1": "666 Fake Street",
"city": "Redwood City",
"postal_code": "94063",
"region": "CA",
"country": "US"
},
"date_of_birth": {
"year": 1991,
"month": 7,
"day": 8
},
"us_owner_compliance": {
"social_security_number_last_4": "1234"
},
"phone": {
"country_code": "+1",
"phone_number": "6508675309"
}
}
Additional Beneficial Owner Response
Personal details associated with additional beneficial owners.
Fields
| Field | Type | Description |
| name | Name Response | The name of the beneficial owner. |
| address | KYC Address Response | The address of the beneficial owner. |
| date_of_birth_is_present | Boolean | The birthdate of the beneficial owner. |
| phone | Phone Response | The phone number of the beneficial owner. |
| ca_owner_compliance | CA Owner Compliance Response | Social insurance number. |
| us_owner_compliance | US Owner Compliance Response | Social security information. |
CA example
{
"name": {
"first": "Bob",
"last": "Smitherson"
},
"address": {
"address1": "456 Fake Street",
"city": "Wandering River",
"postal_code": "T0A 3M0",
"region": "AB",
"country": "CA"
},
"date_of_birth_is_present": true,
"ca_owner_compliance": {
"social_insurance_number_is_present": true
},
"phone": {
"country_code": "+1",
"phone_number": "6666667777"
}
}
US example
{
"name": {
"first": "Damien",
"last": "Holmes"
},
"address": {
"address1": "666 Fake Street",
"city": "Redwood City",
"postal_code": "94063",
"region": "CA",
"country": "US"
},
"date_of_birth_is_present": true,
"us_owner_compliance": {
"social_security_number_is_present": true
},
"phone": {
"country_code": "+1",
"phone_number": "6508675309"
}
}
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"
}
}
Phone Response
Contains the user’s or entity’s registered phone number.
Fields
| Field | Type | Description |
| country_code | String (255 chars) | The country code of the primary phone number entered by the user. |
| phone_number | 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. US postal codes must be valid, 5 didgit strings. CA postal codes must be six digits. The format is `A1A 1A1`, where A is a letter and 1 is a digit, with a space separating the third and fourth characters. UK postal codes must be 5-7 digits. |
| country | Yes | String (255 chars) | The country where the user resides. |
Example
{
"address": {
"address1": "456 Diagon Alley",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
}
}
KYC Address Response
Contains the user’s address information, including region and postcode.
Fields
| Field | Type | Description |
| address1 | 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 | String (255 chars) | A continuation of the users address. |
| city | String (255 chars) | The city where the user resides. |
| region | String (255 chars) | The region where the user resides. |
| postal_code | String (255 chars) | The postcode where the user resides. US postal codes must be valid, 5 didgit strings. CA postal codes must be six digits. The format is `A1A 1A1`, where A is a letter and 1 is a digit, with a space separating the third and fourth characters. UK postal codes must be 5-7 digits. |
| country | String (255 chars) | The country where the user resides. |
Example
{
"address": {
"address1": "456 Diagon Alley",
"city": "Toronto",
"postal_code": "M4C 1M5",
"region": "",
"country": "CA"
}
}
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"
}
Name Response
Contains the full name of the user.
Fields
| Field | Type | Description |
| first | String (35 chars) | The user's first name. Truncated after the first 35 characters. |
| middle | String (35 chars) | The user's middle name. Truncated after the first 35 characters. |
| last | String (35 chars) | The user's last name. Truncated after the first 35 characters. |
Example
{
"first": "John",
"middle": "Quincy",
"last": "Adams"
}