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

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 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.
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.
job_title Yes * String (255 chars) The controller's job title. We recommend displaying the following common controller job titles in your user interface:
  • ceo
  • cfo
  • coo
  • president
  • chairman
  • executive
  • owner
  • Other (provide an input text field)
Note: This field should only be supplied for business or organization account owners.
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.
email 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 (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.
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"
            }
        },
        "mcc": 7999,
        "primary_url": "https://www.foobar.com",
        "ca_entity_compliance": {
            "additional_beneficial_owners": [

            ],
            "legal_form": "individual"
        }
    }
}

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": "individual"
        }
    }
}

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 No 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.
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",
        "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
                    }
                }
            ]
        }
    }
}

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.
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",
        "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.
primary_url No 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.
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",
        "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"
        },
        "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.
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",
        "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_beneficial_owners Yes* Array An array of beneficial owners.

*Your platform can pass an empty array if the business does not have any beneficial owners.
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.
  • The Individual Structure accepts:
    • individual
    • sole_proprietor
  • The Business Structure accepts:
    • corporation
    • limited_liability_company
    • partnership
  • The Organization Structure accepts:
    • government_agency
    • nonprofit_corporation
    • personal_trust
    • statutory_trust
    • unincorporated_association
business_number No String (255 chars) The business number is used to validate a registered business or nonprofit in Canada. It is required for:
  • corporations
  • government agencies
  • limited liability companies
  • nonprofit corporations
  • partnerships
  • personal trusts
  • statutory trusts
  • unincorporated associations
Note: Business number is optional for sole proprietors, and not collected for individuals.
gst_hst No 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.

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_beneficial_owners Array An array of beneficial owners.
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.
  • The Individual Structure returns:
    • individual
    • sole_proprietor
  • The Business Structure returns:
    • corporation
    • limited_liability_company
    • partnership
  • The Organization Structure returns:
    • government_agency
    • nonprofit_corporation
    • personal_trust
    • statutory_trust
    • unincorporated_association
business_number 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_beneficial_owners 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.
  • The Individual Structure accepts:
    • individual
    • sole_proprietor
  • The Business Structure accepts:
    • corporation
    • limited_liability_company
    • partnership
  • The Organization Structure accepts:
    • government_agency
    • nonprofit_corporation
    • personal_trust
    • statutory_trust
    • unincorporated_association

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_beneficial_owners 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.
  • The Individual Structure accepts:
    • individual
    • sole_proprietor
  • The Business Structure accepts:
    • corporation
    • limited_liability_company
    • partnership
  • The Organization Structure accepts:
    • government_agency
    • nonprofit_corporation
    • personal_trust
    • statutory_trust
    • unincorporated_association

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_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.
is_beneficial_owner Yes* Boolean Note: This field should only be supplied for business or organization account owners.

  • TRUE indicates that the controller owns 25% or more of the business’s equity.
  • FALSE indicates that the controller owns less than 25% of the business’s equity.

For nonprofit organizations, the beneficial ownership requirement is satisfied by collecting the personal information of a controller of the organization. WePay requires the account owner of the nonprofit organization to be a controller, so this field should always be 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_insurance_number_is_present 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 indicates that the controller owns 25% or more of the business’s equity.
  • FALSE indicates that the controller owns less than 25% of the business’s equity.

For nonprofit organizations, the beneficial ownership requirement is satisfied by collecting the personal information of a controller of the organization. WePay requires the account owner of the nonprofit organization to be a controller, so this field should always be 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 indicates that the controller owns 25% or more of the business’s equity.
  • FALSE indicates that the controller owns less than 25% of the business’s equity.

For nonprofit organizations, the beneficial ownership requirement is satisfied by collecting the personal information of a controller of the organization. WePay requires the account owner of the nonprofit organization to be a controller, so this field should always be 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 indicates that the controller owns 25% or more of the business’s equity.
  • FALSE indicates that the controller owns less than 25% of the business’s equity.

For nonprofit organizations, the beneficial ownership requirement is satisfied by collecting the personal information of a controller of the organization. WePay requires the account owner of the nonprofit organization to be a controller, so this field should always be 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.
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.
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"
}