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.

Create the enrollment

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"
      }
    }
  }'

{
  "success": true,
  "data": {
    "id": "31b7fac8-8c2b-4839-930f-74a05427f4ec",
    "status": "draft",
    "corporationUserId": null,
    "corporationName": "acme inc.",
    "corporationNumber": "123456789",
    "corporationEmail": "accounts@acme.com",
    ...
  }
}

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.

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

Used for address and authorizedUser.address.

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

Each entry in directors and beneficialOwners. List a person in both arrays if they are a director and also own 25% or more.

Authorized user

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.

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.

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" }'

Upload the documents and submit

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:

Any other value is rejected with 422.

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 }
    ]
  }'

{
  "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:

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:

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:

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.

Wait for verification

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:

curl -X GET "https://api.paytrie.com/v2/users/me/corporation" \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer applicant-access-token"

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, then add the files to the enrollment:

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.

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 for that user as you would for any other user, authenticating as described in 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 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.