# Business Onboarding
A business is onboarded by a person acting for it, such as a director or an authorized signatory. That person needs their own Paytrie user. With their access token you create a corporate enrollment with the corporation's details, upload its incorporation documents and submit it for review. Once Paytrie verifies it, the corporation gets its own account, and you transact as that account.
### Get an access token for the applicant [#get-an-access-token-for-the-applicant]
Find or create the person's Paytrie user as described in [Customer Onboarding](/v2/customer-onboarding), then get an access token for them through the [Authentication](/v2/authentication) flow. Every request below sends both your API key and that token.
### Create the enrollment [#create-the-enrollment]
Send all of the corporation's details in a single request. The enrollment starts as a `draft`.
### Upload the documents and submit [#upload-the-documents-and-submit]
Upload the certificate of incorporation and the articles of incorporation, then submit them. Submitting is what moves the enrollment to `in-review`.
### Wait for verification [#wait-for-verification]
Poll the enrollment until its `status` is `verified`, then transact as the corporation's user it names in `corporationUserId`.
## Create the enrollment [#create-the-enrollment-1]
```bash
curl -X POST "https://api.paytrie.com/v2/users/me/corporation" \
-H "x-api-key: your-api-key" \
-H "Authorization: Bearer applicant-access-token" \
-H "Content-Type: application/json" \
-d '{
"corporationName": "Acme Inc.",
"corporationNumber": "123456789",
"corporationEmail": "accounts@acme.com",
"phone": "4161234567",
"address": {
"addressLine1": "123 King St W",
"addressLine2": "Suite 200",
"city": "Toronto",
"province": "on",
"postalCode": "m5h1a1",
"country": "CA"
},
"businessNature": "Software",
"purpose": "payments",
"sourceOfFunds": "business_revenue",
"dateOfIncorporation": "2021-01-01",
"msbRegistered": false,
"isPep": false,
"tpd": false,
"directors": [
{
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@acme.com",
"occupation": "Director",
"dateOfBirth": "1985-04-12"
}
],
"hasBeneficialOwners": true,
"beneficialOwners": [
{
"firstName": "Jane",
"lastName": "Doe",
"email": "jane@acme.com",
"occupation": "Director",
"dateOfBirth": "1985-04-12"
}
],
"authorizedUser": {
"firstName": "Jane",
"lastName": "Doe",
"occupation": "Director",
"dateOfBirth": "1985-04-12",
"address": {
"addressLine1": "1 Front St",
"addressLine2": null,
"city": "Toronto",
"province": "on",
"postalCode": "m5j2x5",
"country": "CA"
}
}
}'
```
```json
{
"success": true,
"data": {
"id": "31b7fac8-8c2b-4839-930f-74a05427f4ec",
"status": "draft",
"corporationUserId": null,
"corporationName": "acme inc.",
"corporationNumber": "123456789",
"corporationEmail": "accounts@acme.com",
...
}
}
```
### Corporation fields [#corporation-fields]
`corporationName`, `corporationNumber` and `corporationEmail` are required to create the enrollment. Everything else can be sent in the same request or added later with `PATCH`, but must be set before the enrollment can be submitted.
| Field | Type | Required | What to send |
| --------------------- | ----------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `corporationName` | string | To create | The corporation's legal name, e.g. `Acme Inc.` |
| `corporationNumber` | string | To create | The corporation number from the certificate of incorporation, e.g. `123456789` |
| `corporationEmail` | string | To create | An email address for the corporation. It becomes the login of the corporation's own account, so it must not already belong to a Paytrie user |
| `phone` | string | To submit | The corporation's phone number as 10 digits with no spaces or symbols, e.g. `4161234567` |
| `address` | [address](#address) | To submit | The corporation's registered address |
| `businessNature` | string | To submit | A short description of what the business does, e.g. `Wholesale distribution of electronics` |
| `purpose` | string | To submit | Why the corporation will use Paytrie. One of `payments`, `payroll`, `treasury_management`, `trading_investments`, `merchant_transactions`, `defi_transactions` |
| `sourceOfFunds` | string | To submit | Where the corporation's funds come from. One of `business_revenue`, `investments_treasury`, `loans_financing`, `grants` |
| `dateOfIncorporation` | string | To submit | `YYYY-MM-DD`, e.g. `2021-01-01` |
| `msbRegistered` | boolean | To submit | `true` if the corporation is registered with FINTRAC as a money services business |
| `isPep` | boolean | To submit | Must be `false`: whether any individual associated with the corporation, or their direct relatives, is a politically exposed person (PEP) or the head of an international organization (HIO). Corporations where this is true cannot be onboarded through the API; contact Paytrie instead |
| `tpd` | boolean | To submit | Must be `false`: whether the corporation acts at the instruction of another person or entity. Corporations where this is true cannot be onboarded through the API; contact Paytrie instead |
| `directors` | array of [people](#person) | To submit | Every director, at least one |
| `hasBeneficialOwners` | boolean | To submit | `true` if any individual directly or indirectly owns 25% or more of the corporation |
| `beneficialOwners` | array of [people](#person) | To submit when `hasBeneficialOwners` is `true` | Every individual who owns 25% or more. Send `[]` when `hasBeneficialOwners` is `false` |
| `authorizedUser` | [authorized user](#authorized-user) | To submit | The person authorized to act for the corporation, usually the applicant |
Values outside these rules, such as a `purpose` not in the list or a date in another format, fail with `422` naming the field.
### Address [#address]
Used for `address` and `authorizedUser.address`.
| Field | Type | What to send |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `addressLine1` | string | Street address, e.g. `123 King St W` |
| `addressLine2` | string or `null` | Unit or suite, e.g. `Suite 200`. Send `null` if there is none |
| `city` | string | e.g. `Toronto` |
| `province` | string | For Canada, the two-letter province or territory code: `ab`, `bc`, `mb`, `nb`, `nl`, `ns`, `nt`, `nu`, `on`, `pe`, `qc`, `sk` or `yt`. For the United States, the two-letter state code, e.g. `ny`. Otherwise the region |
| `postalCode` | string | For Canada, a valid postal code such as `M5H 1A1` or `m5h1a1`. For the United States, a ZIP code such as `10001` or `10001-1234` |
| `country` | string | ISO 3166-1 alpha-2 country code, e.g. `CA` |
A Canadian or US address with an unknown province, state or postal code fails with `400`.
`province` takes a two-letter code such as `on`, while `incorporationJurisdiction` at submission takes a name such as `ontario`. The two fields use different formats.
### Person [#person]
Each entry in `directors` and `beneficialOwners`. List a person in both arrays if they are a director and also own 25% or more.
| Field | Type | What to send |
| ------------- | ------ | ------------------------------ |
| `firstName` | string | Legal first name |
| `lastName` | string | Legal last name |
| `email` | string | The person's own email address |
| `occupation` | string | e.g. `Director`, `CEO` |
| `dateOfBirth` | string | `YYYY-MM-DD` |
### Authorized user [#authorized-user]
| Field | Type | What to send |
| ------------- | ------------------- | ---------------------------------------------- |
| `firstName` | string | Legal first name |
| `lastName` | string | Legal last name |
| `occupation` | string | Their role at the corporation, e.g. `Director` |
| `dateOfBirth` | string | `YYYY-MM-DD` |
| `address` | [address](#address) | Their residential address |
`corporationName` and `businessNature` are stored in lowercase. When you update `directors`, `beneficialOwners`, `address` or `authorizedUser` with `PATCH`, send the whole value: the list or object you send replaces the one on file.
Each person can hold one enrollment. The request fails with `409` if the applicant already has one, if another enrollment uses the same corporate email, or if a verified corporation already has the same name or number. It fails with `400` if an address is not valid for its country.
View complete request parameters and response schema
## Correct or complete a draft [#correct-or-complete-a-draft]
This step is optional. If you sent every field when you created the enrollment, go straight to uploading the documents.
While the enrollment is a `draft`, send any of the same fields to change them or fill in ones you left out. Use it to fix a mistake before submitting, or to add the fields a submission reported as missing. You cannot create a second enrollment for the same applicant instead, since that fails with `409`. Updating never submits the enrollment, and it fails with `403` once the enrollment is `in-review`.
```bash
curl -X PATCH "https://api.paytrie.com/v2/users/me/corporation" \
-H "x-api-key: your-api-key" \
-H "Authorization: Bearer applicant-access-token" \
-H "Content-Type: application/json" \
-d '{ "phone": "4167654321" }'
```
View complete request parameters and response schema
## Upload the documents and submit [#upload-the-documents-and-submit-1]
Documents are uploaded straight to storage through signed URLs. Request one URL per file, up to 5 files of at most 10 MB each. Set each file's `contentType` to one of:
| `contentType` | File type |
| ----------------- | ----------------------------------- |
| `application/pdf` | PDF |
| `image/jpeg` | JPEG (`image/jpg` is also accepted) |
| `image/png` | PNG |
| `image/webp` | WebP |
| `image/heic` | HEIC |
| `image/heif` | HEIF |
Any other value is rejected with `422`.
```bash
curl -X POST "https://api.paytrie.com/v2/users/me/corporation/documents/upload-urls" \
-H "x-api-key: your-api-key" \
-H "Authorization: Bearer applicant-access-token" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{ "name": "certificate-of-incorporation.pdf", "contentType": "application/pdf", "size": 204800 },
{ "name": "articles-of-incorporation.pdf", "contentType": "application/pdf", "size": 512000 }
]
}'
```
```json
{
"success": true,
"data": {
"uploads": [
{
"objectName": "corporate/31b7fac8-8c2b-4839-930f-74a05427f4ec/9a1c....pdf",
"uploadUrl": "https://storage.googleapis.com/...",
"requiredHeaders": {
"Content-Type": "application/pdf",
"x-goog-content-length-range": "0,10485760",
"x-goog-meta-file-name": "certificate-of-incorporation.pdf"
},
"expiresAt": "2024-01-01T00:15:00.000Z"
},
...
]
}
}
```
`PUT` each file to its `uploadUrl` with exactly the `requiredHeaders`. The URL's signature covers every one of them, so the upload is rejected if any is missing or changed:
```bash
curl -X PUT "https://storage.googleapis.com/..." \
-H "Content-Type: application/pdf" \
-H "x-goog-content-length-range: 0,10485760" \
-H "x-goog-meta-file-name: certificate-of-incorporation.pdf" \
--data-binary @certificate-of-incorporation.pdf
```
Then submit the enrollment with the `objectNames` and the jurisdiction the corporation was incorporated in:
```bash
curl -X POST "https://api.paytrie.com/v2/users/me/corporation/documents" \
-H "x-api-key: your-api-key" \
-H "Authorization: Bearer applicant-access-token" \
-H "Content-Type: application/json" \
-d '{
"objectNames": [
"corporate/31b7fac8-8c2b-4839-930f-74a05427f4ec/9a1c....pdf",
"corporate/31b7fac8-8c2b-4839-930f-74a05427f4ec/4f0e....pdf"
],
"incorporationJurisdiction": "ontario"
}'
```
Set `incorporationJurisdiction` to one of these values exactly as written:
| `incorporationJurisdiction` | Jurisdiction |
| --------------------------- | --------------------------- |
| `federal` | Government of Canada |
| `alberta` | Alberta |
| `british_columbia` | British Columbia |
| `manitoba` | Manitoba |
| `new_brunswick` | New Brunswick |
| `newfoundland` | Newfoundland and Labrador |
| `nova_scotia` | Nova Scotia |
| `ontario` | Ontario |
| `pei` | Prince Edward Island |
| `quebec` | Quebec |
| `saskatchewan` | Saskatchewan |
| `nwt` | Northwest Territories |
| `nunavut` | Nunavut |
| `yukon` | Yukon |
| `non_canadian` | Incorporated outside Canada |
Any other value, such as `ON` or `Ontario`, is rejected with `422`.
This is the only request that moves the enrollment from `draft` to `in-review`. Creating or updating the enrollment never does, however complete it is. On success the enrollment can no longer be updated.
If any required detail is missing, the request fails with `422` and names the missing fields, for example `This enrollment cannot be submitted yet. Missing: phone, directors`. The enrollment stays a `draft`, so fill in those fields with `PATCH` and submit again.
View complete request parameters and response schema
## Wait for verification [#wait-for-verification-1]
Paytrie reviews every enrollment manually. Allow up to 24 hours, and poll no more often than every 15 minutes. Read the enrollment to follow its progress:
```bash
curl -X GET "https://api.paytrie.com/v2/users/me/corporation" \
-H "x-api-key: your-api-key" \
-H "Authorization: Bearer applicant-access-token"
```
| `status` | Meaning |
| ----------- | ------------------------------------------------------------- |
| `draft` | Details and documents are still being collected |
| `in-review` | Submitted and waiting for Paytrie's review |
| `verified` | Approved. `corporationUserId` names the corporation's account |
## Send more documents during review [#send-more-documents-during-review]
If Paytrie needs more documents to complete the review, we contact you directly. The API does not report it, and `status` stays `in-review` in the meantime.
Request upload URLs and `PUT` each file exactly as in [Upload the documents and submit](#upload-the-documents-and-submit), then add the files to the enrollment:
```bash
curl -X POST "https://api.paytrie.com/v2/users/me/corporation/additional-documents" \
-H "x-api-key: your-api-key" \
-H "Authorization: Bearer applicant-access-token" \
-H "Content-Type: application/json" \
-d '{
"objectNames": [
"corporate/31b7fac8-8c2b-4839-930f-74a05427f4ec/7d2b....pdf"
]
}'
```
The request returns `204`. The files are added to those already on file, and the enrollment goes back to Paytrie's review. It fails with `409` while the enrollment is still a `draft`.
Do not submit them with `POST /v2/users/me/corporation/documents` again. That replaces the documents already on file instead of adding to them.
View complete request parameters and response schema
## Transact as the corporation [#transact-as-the-corporation]
When the enrollment is `verified`, `corporationUserId` is the corporation's own Paytrie user. Its email is the `corporationEmail` you enrolled with, and it is linked to your integration. Get quotes and create [transactions](/v2/transactions) for that user as you would for any other user, authenticating as described in [Knowing how you can act on a user](/v2/authentication#knowing-how-you-can-act-on-a-user).
The applicant's access token does not cover the corporation's user. To get one for it, run the [authentication flow](/v2/authentication#quick-start) with `corporationEmail`. The login code is emailed to that address, so someone who can read the corporation's inbox has to pass it to you.
The applicant's own user stays a personal account. Transactions for the business always go through `corporationUserId`.