Admin Guide
Last updated · April 2026

Compliance & Feature Access

Everything you need to manage user KYC verification and feature availability across Payrit services.

Admin only Compliance Feature flags KYC

🔐 How the access system works

When a user tries to use a Payrit service — creating a virtual account, making a cross-border transfer, etc. — two checks happen automatically before the action is allowed:

1 · Compliance check

Has this user been KYC-verified by the provider currently serving this service?

2 · Feature access check

Is this specific feature turned on for this user right now?

Both checks must pass. If either fails, the user is blocked with a message explaining why. As an admin, you control both through the dashboard.

💡

Changes made in the dashboard take effect immediately. There is no staging environment for these settings — caches are cleared automatically on every save.

🏦 Part 1 — Compliance (KYC Management)

A provider is a third-party KYC vendor that verifies our users' identities (e.g. Sumsub, Smile ID). Each service on Payrit is served by exactly one active provider at a time. When a user passes KYC with a provider, they can access all services that provider covers.

⚠️

Single-active rule: Only one provider can be active per service at any time. Activating a new provider automatically deactivates the current one. There is no way to have two providers active for the same service simultaneously.

How to add a new provider

  1. Go to Compliance → Providers → Add Provider Find the button in the top-right corner of the providers list
  2. Fill in the Provider ID A short uppercase identifier — e.g. SUMSUB, SMILEID. This cannot be changed later.
  3. Fill in the display Name Human-readable name shown in the dashboard — e.g. Sumsub
  4. Set Requires KYC Leave this checked in almost all cases. Unchecking it means the compliance check is skipped entirely and all users are allowed through automatically.
  5. Click Save A background job runs automatically to create a not_started record for every existing user. This takes a few minutes and is visible on the Bull Board.

How to add a service to a provider

Before a provider can serve a service, the service must be registered with it. New services are added as inactive by default — you must activate them separately.

  1. Open the provider's detail page Go to Compliance → Providers → click the provider name
  2. Click Add Service Select the service from the dropdown (e.g. VIRTUAL_ACCOUNTS_USD)
  3. Click Save The service appears in the table as Inactive. Proceed to activate it when ready.

How to activate a provider for a service (go live)

  1. Open the provider's detail page
  2. Find the service in the services table It will show as Inactive
  3. Toggle it to Active and confirm the dialog The dialog warns you that any other provider currently active for this service will be deactivated. Confirm to proceed.
✅

The change is live immediately. The compliance cache is cleared so the next user request picks up the new provider.

How to switch providers for a service

Example: switching from Sumsub to SmileID for VIRTUAL_ACCOUNTS_USD.

  1. Make sure SmileID has the service registered If not, add it (see above). It will be inactive.
  2. Toggle SmileID to Active for that service Sumsub is automatically deactivated for that service.
🚨

Important: Users who were approved by Sumsub are not automatically approved by SmileID. Their status with SmileID starts at not_started. You will need to re-verify them or manually update their status.

👤 User Compliance

Each user has one compliance record per provider. The record tracks their KYC approval status with that provider.

Status reference

Status What it means Can access services?
not_started User has not begun KYC, or a record was auto-seeded when the provider was created No
pending KYC submitted and under review No
approved KYC passed — user is fully verified Yes
rejected KYC failed — user did not pass verification No
deactivated Access manually turned off by admin (overrides prior approval) No

How to update a user's KYC status

  1. Go to Compliance → User Compliance
  2. Search by name or email Type the user's name or email address — a dropdown of matching users appears as you type. Click the correct person to select them. You never need to handle a MongoDB ID directly.
  3. Find the record for the relevant provider Each row shows the provider, current status, and last updated time
  4. Select the new status from the dropdown and save The user's cached status is cleared immediately — the next API call reflects the change.

How to re-seed compliance records

If some users are missing a compliance record for a provider (e.g. after a data migration), you can trigger a re-seed from the provider's detail page.

🔄

Re-seeding is safe to run multiple times. It only creates records for users who don't already have one — it never overwrites existing approved, rejected, or any other status.

How to sync KYC status from the provider's API

Use this when users have already gone through KYC with a provider externally but their approval status has not yet been written to Payrit's database. Instead of updating each user manually, the sync job fetches the real status from the provider's API for all users in bulk.

  1. Go to the provider's detail page
  2. Click Sync KYC Status The button is only visible for providers that support external sync (currently Borderless-based providers: compliance-fee5483c, compliance-3d0947c0).
  3. Confirm the dialog The job runs in the background and may take several minutes depending on user count.
ℹ️

When to use this: After onboarding a new provider where users are already KYC-verified externally. Also run it after a provider migration to back-fill statuses for users who completed KYC under the previous provider.

⚠️

Overwrites existing statuses. Unlike re-seeding, the sync job does overwrite stored statuses with the latest value from the provider. Each user's compliance cache is cleared immediately after their record is updated.

✅

Safe to re-run. Running it multiple times is harmless — each run fetches the freshest status from the provider. Monitor progress on the Bull Board dashboard.

🚀 Part 2 — Feature Access (Feature Flags)

A feature is a service or action on Payrit (e.g. VIRTUAL_ACCOUNTS_USD, CROSS_BORDER_WITHDRAWAL_KES). Each registered feature has a default access setting that controls whether all users can use it.

Open   defaultEnabled: true

All KYC-approved users can use this feature. No individual records needed.

Closed   defaultEnabled: false

No one can use this feature unless explicitly granted access via a user override.

💡

You do not need to create a record for every user. The default applies to everyone without an explicit override. You only create overrides when a user's access should differ from the default.

How to register a new feature

A feature must be registered before you can manage its access.

  1. Go to Feature Access → Features → Register Feature
  2. Select the Service Name from the dropdown These match the FeatureName values — e.g. VIRTUAL_ACCOUNTS_USD
  3. Set Default Access Open for a full GA rollout. Closed for a beta rollout where access is granted one user at a time.
  4. Optionally add a Description For internal reference only — not shown to users
  5. Click Save

How to graduate a feature from beta to GA (open to all)

  1. Go to Feature Access → Features
  2. Find the feature and toggle Default Access to Open
  3. Confirm the dialog All users without an explicit override will now have access. Users you previously granted beta access to keep their access. Users you previously blocked keep their block.

🎛️ User Feature Overrides

An override is a per-user, per-feature record that takes priority over the feature default. It is only created when a user's access should differ from everyone else.

How to grant a beta user access to a closed feature

  1. Go to Feature Access → User Overrides
  2. Search by name or email and select the user Type the user's name or email — a dropdown of matches appears. Click the correct person. You never need a MongoDB ID.
  3. Click Add Override, select the feature, set Enabled to ON Add a reason such as "Beta tester — Cohort A" for your audit trail
  4. Click Save The user can now access the feature even though defaultEnabled is false for everyone else.

How to block a specific user from a GA feature

  1. Go to Feature Access → User Overrides
  2. Search by name or email and select the user Type the user's name or email — a dropdown of matches appears. Click the correct person.
  3. Click Add Override, select the feature, set Enabled to OFF Add a reason such as "Flagged for suspicious activity" for your audit trail
  4. Click Save The user is now blocked even though the feature is open to everyone else.

How to remove a user override (revert to default)

  1. Go to Feature Access → User Overrides
  2. Search by name or email and select the user Type the user's name or email — a dropdown of matches appears. Click the correct person.
  3. Find the override in the table and click Remove
  4. Confirm the dialog The user now follows the feature default. If the feature is open, they have access. If it's closed, they don't.

📋 Common workflows

1 Onboarding a new KYC provider

  1. Create the providerSet requiresKyc: true
  2. Wait for the seed job to completeCheck the Bull Board dashboard for job status
  3. Add the relevant services to the providerThey will be inactive
  4. Go liveActivate the provider for each service when ready

2 Rolling out a new feature to beta users

  1. Register the feature with Default Access = Closed
  2. For each beta user, add a user override with Enabled = ONNote the reason for the audit trail
  3. When ready for GA, toggle Default Access to OpenAll users without overrides instantly get access. Beta override records become redundant but are harmless.

3 Switching KYC providers mid-flight

  1. Register the new provider and add the services
  2. Activate the new provider for each serviceOld provider is deactivated automatically
  3. Bulk-update users who were already approvedTheir status with the new provider starts at not_started. Use the user compliance panel to set them to approved or coordinate a re-verification campaign.

🔍 Debugging why a user can't access a service

Check in this order:

Step Where to check What to look for Fix
1 Feature Access → User Overrides Does this user have an override set to Disabled? Remove the override or set it to Enabled
2 Feature Access → Features Is the feature Closed and this user has no override? Add an Enabled override for this user, or open the feature to everyone
3 Compliance → User Compliance Is the user's KYC status not_started, pending, rejected, or deactivated? Update their status or ask them to complete KYC
4 Compliance → Providers Is there no active provider for this service? Activate a provider for the service

📌 Key rules to remember

  • One active provider per service. Activating a new provider automatically deactivates the previous one — you cannot have two active simultaneously.
  • Switching providers resets user compliance. Users approved by the old provider are not_started with the new one and must be re-verified.
  • Feature overrides always win over the default. An explicit enabled: false override blocks a user even if the feature is open to everyone.
  • No override record = use the feature default. You only need to create an override when a user should behave differently from everyone else. There is no need to seed records.
  • All changes take effect immediately. There is no staging or delayed rollout — caches are cleared on every admin save.
  • Seeding is safe to run multiple times. It only creates records for users who don't already have one. It never overwrites existing statuses.
  • Deactivating without activating another provider leaves a service dead. Any user trying to use that service will be blocked with a "not currently available" message until a new provider is activated.