Onboard via Hosted Form

With the hosted form, Harbor collects the Customer's information, documents and face check on its own pages. You create the Customer and send them the link to the form. You don't build forms or handle their files.

Steps

• Create the Customer. The response has an agreement_link and a verification_link. See Customers.
• The Customer accepts the agreement through agreement_link.
• The Customer completes the hosted form through verification_link.
• Harbor reviews the information.
• Follow the Customer's status until they're verified.

Get the Link

verification_link is in the Customer object. It opens the individual form (/gokyc) or the business form (/gokyb), depending on the Customer's type. For example, a new business:

{
    "data": {
        "uuid": "cus_yO7nLlHGI6LIFm3HMMSG5hTkXR2sGoXf3ufozH7B",
        "object": "customer",
        "status": "unfinished",
        "type": "business",
        ...,
        "has_signed_agreement": false,
        "agreement_link": "https://harbor-sandbox.owlpay.com/agreements?uuid=agt_7Fb4WNrHMt06qhs9Uu8Pi813ktOvX2ZSgwAlUw4S",
        "verification_link": "https://harbor-sandbox.owlpay.com/gokyb?expires=1794381913&hash=4283c9f78ba4e2c8256fac88a640453856c12c23806a27c1669756961b9785ae"
    }
}

The link expires:

• Individuals: 10 minutes after it's generated.
• Businesses: 30 days after it's generated.

To get a new link, retrieve the Customer. Each time, the response has a new verification_link, and older links keep working until they expire. Once the Customer is verified, verification_link is null.

GET /api/v1/customers/{customer_uuid}

An individual's link is short-lived, so get it right before you send the Customer to the form. An expired link shows an "Invalid or Expired Request" page.

What the Customer Does

Individuals complete the form in one sitting, usually in 3 to 10 minutes:

• Enter their personal details, occupation, source of wealth and purpose of use.
• Scan their identity document with the camera: ID card, passport or driver's license.
• Complete a face check with the camera.

Businesses usually take a few hours to a few days, because they need to gather company documents:

• Enter the company details: industry, registration number, address and phone.
• Add the associated persons: beneficial owners with more than 20%, directors and the legal representative.
• Upload the company documents, such as registration documents, certificate of incumbency and organization chart.
• Upload an identity document for each associated person.
• The person filling in the form completes a face check with the camera.

There's one link per Customer. For a business, the person filling in the form uploads the documents for everyone.

The Customer can stop and continue later. Their progress is saved, and the form continues where they left off, with the same link or a new one.

Follow the Status

The hosted form doesn't create an onboarding record, so follow the Customer's status:

• unfinished: the Customer hasn't finished the form.
• finished: the Customer finished the form, and the review hasn't started yet.
• verifying: Harbor is reviewing the information.
• verified: the Customer is approved and can transact.
• rejected: something needs to be corrected.
• declined: the Customer is declined. This is final.

The Customer object also has a state field, a simpler version of the same progress: not_started, in_progress, pending_review, verified, update_required, declined or suspended. update_required means the Customer needs to correct their information or answer a request for information.

To get notified instead of checking, subscribe to these webhook events:

• customer.kyc.verifying: the Customer submitted the form, and the review started. There's no event for finished, so use this one to know the form is done.
• customer.kyc.verified: the Customer is approved.
• customer.kyc.rejected: something needs to be corrected.
• customer.kyc.declined: the Customer is declined.

See Onboarding Lifecycle.

If the Customer Is Rejected

Get a new verification_link and send it to the Customer. When they open it, the form shows what needs to be corrected. If the corrections aren't ready yet, the page says "Corrections Required" and asks for a new link. Try again a little later.

A rejected Customer also has a review_reason, with instructions for the Customer when the reviewer wrote some. It's often null, for example when the document was rejected automatically. The form still shows what to correct.

{
    "data": {
        "uuid": "cus_ta7zykRrIK9aPE9LZA4YHktzE7JXx8aSh4HLe3C2",
        "status": "rejected",
        "state": "update_required",
        ...,
        "verification_link": "https://harbor-sandbox.owlpay.com/gokyc?expires=1791791217&hash=9a17e3d2c44f80a8848385b0ed272c12309f3f7d367e253f3b5e4dd461af23c8",
        "rfi_link": null,
        "review_reason": null
    }
}

Common reasons for a rejection:

• Individuals: the name or date of birth doesn't match the identity document, the face check doesn't match the document, or the Customer lives in a country Harbor doesn't serve.
• Businesses: the company is registered in a country or US state Harbor doesn't serve, documents are screenshots or edited files instead of photos or scans of the originals, beneficial owners with more than 20% are missing, or the registration documents aren't official government documents.

Notes

• Open the link in the Customer's browser, or in an in-app browser tab (SFSafariViewController on iOS, Chrome Custom Tabs on Android). Inside an iframe or a web view, the camera often doesn't work.
• The hosted form is in English.
• After the Customer finishes the form, they stay on the form's confirmation page. There's no redirect back to your site.
• The agreement isn't part of the hosted form. Send agreement_link first. For a new agreement link, see Get an Agreement Link.
• In Sandbox, Customers are verified automatically, so the hosted form shows the Customer as already verified.
• A review usually takes about 1 business day for individuals and about 5 business days for businesses.