Onboarding and KYC

What it is

Onboarding is the checklist that has to complete before a supplier can be funded: collect and verify identity and business documents, obtain access to the supplier’s marketplace accounts, agree the product/service configuration, and sign the contract. It is driven by an onboarding template selected per supplier and per marketplace.

Where it lives

Concern Location

Concern	Location
Supplier tab	`/suppliers/:supplierKey/onboarding` → `suppliers/supplier/supplier-onboarding/supplier-onboarding.component.ts`
Service	`suppliers/supplier/supplier-onboarding/supplier-onboarding.service.ts` (+ `-mock.service.ts`), implementing `SupplierOnboardingInterface`
Compliance	`suppliers/services/supplier-compliance-action.service.ts`, `supplier-compliance-action-status.service.ts`, `suppliers/model/compliance.model.ts`, `supplier-compilance-status.ts`
Templates (back office)	`/manage/onboarding` → `manage/onboarding/` with the `onboarding` store slice (`manage/store/onboarding.{actions,reducer}.ts`) and `shared/onboarding/service/onboarding.service.ts`
Sub-features	`supplier-onboarding-details/`, `supplier-onboarding-compliances/`, `supplier-onboarding-marketplace-access/`, `supplier-onboarding-marketplace-permissions/`, `supplier-sales-information/`, `services-product-matrix/`, `smsnumbers/`, `supplier-verify-document-dialog/`, `onboarding-process-modal/`, and five `marketplace-auth-*` action folders

Supplier tab

/suppliers/:supplierKey/onboarding → suppliers/supplier/supplier-onboarding/supplier-onboarding.component.ts

Service

suppliers/supplier/supplier-onboarding/supplier-onboarding.service.ts (+ -mock.service.ts), implementing SupplierOnboardingInterface

Compliance

suppliers/services/supplier-compliance-action.service.ts, supplier-compliance-action-status.service.ts, suppliers/model/compliance.model.ts, supplier-compilance-status.ts

Templates (back office)

/manage/onboarding → manage/onboarding/ with the onboarding store slice (manage/store/onboarding.{actions,reducer}.ts) and shared/onboarding/service/onboarding.service.ts

Sub-features

supplier-onboarding-details/, supplier-onboarding-compliances/, supplier-onboarding-marketplace-access/, supplier-onboarding-marketplace-permissions/, supplier-sales-information/, services-product-matrix/, smsnumbers/, supplier-verify-document-dialog/, onboarding-process-modal/, and five marketplace-auth-* action folders

Compliance actions and KYC

Onboarding steps are modelled as compliance actions, each identified by a hardcoded UUID in supplier-onboarding.service.ts:

Constant Meaning

Constant	Meaning
`KYC_IDENTITY_KEY`	Identity verification (`869f7aaf-…`)
`KYC_ADDRESS_KEY`	Address verification (`f9be5d82-…`)
`KYC_DOCUSIGN_KEY`	Contract signature via DocuSign (`9a3f6e03-…`)
`ACCOUNT_ACCESS_INVITATION_KEY`	Marketplace account-access invitation (`c5f8e904-…`)
`AMAZON_SELLER_CENTRAM_PERM_KEY`	Amazon Seller Central permission check (`331d90cc-…`)
`ONBOARDING_PROGRESS_KEY`	The aggregate progress record (`87b86b36-…`)
`ONBOARDING_ACTION_KEY` / `ONBOARDING_ACTION_TYPE`	The onboarding check action (`d24c3716-…`, type `onboarding_check`)

KYC_IDENTITY_KEY

Identity verification (869f7aaf-…)

KYC_ADDRESS_KEY

Address verification (f9be5d82-…)

KYC_DOCUSIGN_KEY

Contract signature via DocuSign (9a3f6e03-…)

ACCOUNT_ACCESS_INVITATION_KEY

Marketplace account-access invitation (c5f8e904-…)

AMAZON_SELLER_CENTRAM_PERM_KEY

Amazon Seller Central permission check (331d90cc-…)

ONBOARDING_PROGRESS_KEY

The aggregate progress record (87b86b36-…)

ONBOARDING_ACTION_KEY / ONBOARDING_ACTION_TYPE

The onboarding check action (d24c3716-…, type onboarding_check)

COMPLIANCE_ACTION_KEYS groups the first five; the supplier effect FETCH_COMPLIANCE_ACTIONS_WITH_FILES loads their statuses plus attached files into SupplierModel.kycDocumentsStatuses.

These UUIDs are environment-independent constants embedded in the front end. If a compliance action is recreated in the backend with a new key, the front end silently stops finding it. Any change here is a coordinated backend + front-end change.

The same file also hardcodes marketplace keys used for onboarding branching: AMAZON_SELLER_CENTRAL_MARKETPLACE_KEY, TOPHATTER_…, WALLMART_… (sic), SHOPIFY_…, PAYONEER_…, MORECOMMERCE_…, EBAY_…, VOLUSION_…, PAYPAL_…, STRIPE_…, AUTHORIZE_…, TARGET_…, NEWEGG_…, PINGPONG_…. TARGET_MARKETPLACE_KEY is imported by SupplierDetailsModel.isTarget.

Compliance endpoints

All on internalApiUrl:

Endpoint Use

Endpoint	Use
`suppliers/:key/compliance_status`	Current status of every compliance action.
`suppliers/:key/compliance_status/:complianceKey/:action/:version`	A specific action’s status at a version.
`suppliers/:key/compliance_snapshot/list`, `…/compliance_snapshot/:itemKey`	Point-in-time snapshots of the compliance picture.
`compliance_action_status/:version` (POST), `…/:statusKey/:version` (PUT)	Record or update an action status.
`compliance_status/:statusKey` (PUT)	Update the aggregate status.
`suppliers/:key/identity_check/sole/:partial`, `…/identity_check/company/:partial`	Identity verification for sole traders vs companies — two distinct flows.
`suppliers/:key/check_amazon_api`	Verify Amazon API access still works.
`suppliers/:key/marqeta_kyc_compliances`, `…/marqeta_kyc_compliances/owners`	Marqeta’s own KYC requirements (GET/PUT for the business, GET/PUT for owners) — required before a Marqeta card can be issued. See cards.

suppliers/:key/compliance_status

Current status of every compliance action.

suppliers/:key/compliance_status/:complianceKey/:action/:version

A specific action’s status at a version.

suppliers/:key/compliance_snapshot/list, …/compliance_snapshot/:itemKey

Point-in-time snapshots of the compliance picture.

compliance_action_status/:version (POST), …/:statusKey/:version (PUT)

Record or update an action status.

compliance_status/:statusKey (PUT)

Update the aggregate status.

suppliers/:key/identity_check/sole/:partial, …/identity_check/company/:partial

Identity verification for sole traders vs companies — two distinct flows.

suppliers/:key/check_amazon_api

Verify Amazon API access still works.

suppliers/:key/marqeta_kyc_compliances, …/marqeta_kyc_compliances/owners

Marqeta’s own KYC requirements (GET/PUT for the business, GET/PUT for owners) — required before a Marqeta card can be issued. See cards.

Document verification

supplier-verify-document-dialog/ plus supplier-verify-document.service.ts is the reviewer UI: an uploaded document is displayed and marked verified or rejected. suppliers/model/documentation/ holds the document models, and suppliers/services/documentation/documentation.service.ts the retrieval.

Documents may live in any of four backends depending on age and type — b2bDocumentsApiUrl, pybDocumentsApiUrl (behind the PYB_DOCUMENTS flag), documentsApiUrl and s3FilesProviderApi. shared/apps-document/, shared/b2b-document/ and shared/pyb-documents/ are the three client wrappers.

Which document backend a given attachment is in is not always inferable from the front end. When a document fails to load, check all three wrappers before assuming a bug.

Marketplace account access

Payability needs read access to the supplier’s marketplace account to see earnings. Five action folders implement that negotiation:

Folder Action

Folder	Action
`marketplace-auth-invite-resent/`	Re-send the access invitation to the supplier.
`marketplace-auth-code-get/`	Obtain the authorisation code to hand to the marketplace.
`marketplace-auth-code-save/`	Persist a code supplied by the supplier.
`marketplace-auth-recheck-perm/`	Re-verify that granted permissions are still in place.
`marketplace-auth-remove-access/`	Revoke Payability’s access.

marketplace-auth-invite-resent/

Re-send the access invitation to the supplier.

marketplace-auth-code-get/

Obtain the authorisation code to hand to the marketplace.

marketplace-auth-code-save/

Persist a code supplied by the supplier.

marketplace-auth-recheck-perm/

Re-verify that granted permissions are still in place.

marketplace-auth-remove-access/

Revoke Payability’s access.

supplier-onboarding-marketplace-access/ and supplier-onboarding-marketplace-permissions/ show the resulting state.

Services and product matrix

services-product-matrix/ configures which Payability products a supplier gets, per marketplace. It is a grid of services against marketplaces:

Service Role

Service	Role
`product-matrix.service.ts` (+ mock)	Load and persist the matrix.
`product-matrix-initialize-tables.service.ts`	Build the initial table structure from the supplier’s marketplaces and the available products.
`flex-participation.service.ts` (+ mock)	Flex product participation per marketplace.

product-matrix.service.ts (+ mock)

Load and persist the matrix.

product-matrix-initialize-tables.service.ts

Build the initial table structure from the supplier’s marketplaces and the available products.

flex-participation.service.ts (+ mock)

Flex product participation per marketplace.

Sales information and SMS

supplier-sales-information/ captures estimated revenue and sales context used downstream by underwriting.

smsnumbers/ provisions the SMS number used for supplier notifications and 2FA. It is one of the few features that spans two backends: authToolsApiUrl (provisioning) and messagingUrl (sending) — see sms-numbers-provider.service.ts.

Two-factor authentication

suppliers/supplier/supplier-2fa/ is its own Angular module (supplier-2fa.module.ts) with supplier-2fa.service.ts, gated by the TWO_FA feature flag. It manages the supplier’s 2FA enrolment from the operator side.

Related: suppliers/supplier/supplier-change-password-dialog/ and suppliers/supplier/supplier-unlock/ handle credential resets and unlocking, and suppliers/services/supplier-auth-token.service.ts issues supplier auth tokens via authToolsApiUrl.

Onboarding templates (back office)

/manage/onboarding administers the templates themselves:

Route Screen

Route	Screen
`manage/onboarding/list`	All templates.
`manage/onboarding/add`, `manage/onboarding/:onboardingTemplateKey/edit`	Create/edit a template — the ordered step list.
`manage/onboarding/:onboardingTemplateKey/marketplaces`	Which marketplaces the template applies to.

manage/onboarding/list

All templates.

manage/onboarding/add, manage/onboarding/:onboardingTemplateKey/edit

Create/edit a template — the ordered step list.

manage/onboarding/:onboardingTemplateKey/marketplaces

Which marketplaces the template applies to.

State is the onboarding slice (manage/store/onboarding.reducer.ts — a small map-of-handlers reducer with no effects); the API wrapper is shared/onboarding/service/onboarding.service.ts on internalApiUrl.

A supplier’s chosen template is recorded on the supplier as onboardingTemplateCode, and overall completion as onboardingStatus.

The EVA onboarding summary

The EVA_ONBOARDING_SUMMARY feature flag switches part of the onboarding view to an EVA-rendered iframe. When it is on, the summary you see is not this codebase — see iframe messaging and EVA. The ONBOARDING__INIT_LOAD_EARNINGS_PROCESS message type lets EVA start an earnings load in the parent.

Business rules and constraints

Rule Detail

Rule	Detail
Sole trader vs company	Identity verification uses two different endpoints (`identity_check/sole/…` vs `identity_check/company/…`); the branch is driven by `businessTypeCode` / `incorporatedInTheUS`.
Amazon Seller Central is special-cased	It has its own permission-check compliance action and its own API health check (`check_amazon_api`). Amazon Vendor accounts follow a different path — see `isAmazonVendor`.
Marqeta KYC is separate from Payability KYC	A supplier can pass Payability’s KYC and still fail Marqeta’s. Both must pass before a Marqeta card is issued.
Onboarding does not gate the UI	`onboardingStatus` is informational in the front end. Nothing in the routing prevents opening the advances tab for an un-onboarded supplier; the backend rejects the operation.

Sole trader vs company

Identity verification uses two different endpoints (identity_check/sole/… vs identity_check/company/…); the branch is driven by businessTypeCode / incorporatedInTheUS.

Amazon Seller Central is special-cased

It has its own permission-check compliance action and its own API health check (check_amazon_api). Amazon Vendor accounts follow a different path — see isAmazonVendor.

Marqeta KYC is separate from Payability KYC

A supplier can pass Payability’s KYC and still fail Marqeta’s. Both must pass before a Marqeta card is issued.

Onboarding does not gate the UI

onboardingStatus is informational in the front end. Nothing in the routing prevents opening the advances tab for an un-onboarded supplier; the backend rejects the operation.

Gotchas

The service file name is supplier-onboarding.service.ts, but stale build residue supplier-oboarding.service.js (missing the n) also exists. Ignore the .js.
JSON fixtures (supplier-action-01.json … -04.json, supplier-onboarding-uploads.json) sit in the feature folder and are used by the mock service and specs, not at runtime.
WALLMART_MARKETPLACE_KEY is misspelled in source. Match the existing spelling when referencing it.
FETCH_COMPLIANCE_ACTIONS_WITH_FILES maps each result array to its first element (actionsArr[0]), so only the most recent status per action reaches the store.