KYC onboarding

Overview

Onboard a client before running payin or payout flows: provision the Due customer, complete KYC (hosted or API-driven), request endorsements for the channels you need, and accept terms of service when required.

Portal proxies these endpoints to Due and returns Due’s responses verbatim. Example responses below are illustrative; exact fields come from Due and may evolve.

1. Provision the Due customer

Call POST /customers to create the Due customer for the authenticated client.

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/customers \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "individual",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "country": "US",
    "category": "self_employed",
    "kycReturnUrl": "https://example.com/due/return"
  }'

type is individual or business.
kycReturnUrl is optional and controls where the user lands after a hosted KYC session.

This endpoint is idempotent: calling it again for the same client returns the existing Due customer instead of creating a new one. Use GET /customers to fetch the customer and its status at any time.

2. Check KYC state and requirements

GET /kyc returns the customer’s KYC state and outstanding requirements. Drive your onboarding UI from this response.

curl --request GET \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc \
  --header 'Authorization: Bearer [token]'

3. Complete KYC

Due supports two paths. The hosted session is the fastest way to get started; the API-driven flow gives you full control of the UI.

Option A: hosted KYC session (recommended)

Call POST /kyc/session to create a hosted session, then redirect the user to the returned URL.

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/session \
  --header 'Authorization: Bearer [token]'

After the user finishes, they are sent to the kycReturnUrl you provided at provisioning. Subscribe to webhooks to detect approval. GET /kyc returns the current state whenever you need to read it directly.

Option B: API-driven KYC (build your own UI)

1. Start a submission

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc \
  --header 'Authorization: Bearer [token]'

2. Read the submission’s required fields

curl --request GET \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/submissions/{submissionId} \
  --header 'Authorization: Bearer [token]'

3. Submit collected information

POST /kyc/submissions/{submissionId}/info accepts the form values as key-value pairs. Due validates them and returns field-level errors for anything missing or malformed.

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/submissions/{submissionId}/info \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-31"
  }'

4. Upload documents

First create the document against the submission to receive an upload token:

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/submissions/{submissionId}/documents \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "passport"
  }'

Example response:

{
  "data": {
    "token": "doc_upload_token"
  }
}

Then upload the file bytes with that token:

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/submissions/documents/{token} \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "dataBase64": "[base64-encoded file]",
    "filename": "passport.jpg"
  }'

dataBase64 is required. The decoded file can be up to 10MB.
The MIME type is inferred from the filename extension (jpg, jpeg, png, webp, heic, pdf), or pass contentType explicitly.

5. Complete the submission

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/submissions/{submissionId}/complete \
  --header 'Authorization: Bearer [token]'

6. Detect the outcome

Subscribe to webhooks to learn when the customer is approved. GET /kyc returns the current state whenever you need to read it directly.

4. Endorsements

Some channels require channel-specific approvals on top of base KYC. Each channel from GET /channels lists its endorsementsRequired. List the customer’s endorsements:

curl --request GET \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/endorsements \
  --header 'Authorization: Bearer [token]'

Request an endorsement by code:

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/endorsements/{code} \
  --header 'Authorization: Bearer [token]'

Requesting an endorsement that already exists returns a 409. Treat it as already in progress and fetch its state instead.

Check an endorsement’s state and any extra requirements it adds:

curl --request GET \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/kyc/endorsements/{code} \
  --header 'Authorization: Bearer [token]'

If an endorsement adds requirements, they show up in GET /kyc; collect them through the same submission flow above.

5. Terms of service

Some requirements include a terms of service token. Fetch the document and record the user’s acceptance:

curl --request GET \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/tos/{token} \
  --header 'Authorization: Bearer [token]'

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/integrations/due/tos/{token} \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --data '{
    "ipAddress": "203.0.113.10"
  }'

ipAddress is required and should be the end user’s IP address, not your server’s.

Transfer, recipient, and virtual account endpoints require a provisioned Due customer with approved KYC. Some channels additionally require endorsements; check endorsementsRequired on the channel before initiating a transfer.

​Overview

​1. Provision the Due customer

​2. Check KYC state and requirements

​3. Complete KYC

​Option A: hosted KYC session (recommended)

​Option B: API-driven KYC (build your own UI)

​1. Start a submission

​2. Read the submission’s required fields

​3. Submit collected information

​4. Upload documents

​5. Complete the submission

​6. Detect the outcome

​4. Endorsements

​5. Terms of service

​Next steps

Overview

1. Provision the Due customer

2. Check KYC state and requirements

3. Complete KYC

Option A: hosted KYC session (recommended)

Option B: API-driven KYC (build your own UI)

1. Start a submission

2. Read the submission’s required fields

3. Submit collected information

4. Upload documents

5. Complete the submission

6. Detect the outcome

4. Endorsements

5. Terms of service

Next steps