KYC Verification
Identity verification for customers on the Vivamo platform
Vivamo supports Know Your Customer (KYC) verification to confirm a customer's identity before they transact. KYC with Vivamo is generally required per AML, regulatory or compliance requirements, and is scoped to payments, disbursements, or both.
A customer who is verified once doesn't need to verify again, even if they're connected to multiple operators on the Vivamo platform.
Integration paths
There are three ways to get a customer verified. Pick whichever fits your product:
- SDK-enforced (recommended). The SDK takes care of verification automatically the first time the customer tries to pay or receive a disbursement. Your backend does nothing.
- Operator-initiated. You trigger verification yourself (at signup, for example) by calling Get Customer KYC Info and mounting the SDK widget on your page.
- Legacy (deprecated). The
verifyAfterCreationflag on Create Customer, or the raw verification URLs returned onkycVerification.data. Both still work, but they'll be removed in a future release.
1. SDK-enforced (recommended)
The zero-effort path. When KYC is required and the customer hasn't completed it, the first Payment or Disbursement they initiate will trigger the verification flow. The SDK handles everything: showing the verification options, polling for completion, and firing the usual payment-completed or disbursement-completed events once the customer is verified and their transaction goes through.
You don't need to mount a separate widget. The same vivamo.createElements() call you already make handles the KYC flow when it's needed.
2. Operator-initiated
Use this when you want a customer verified before they ever see a payment or disbursement form. Common cases are during signup, or when you're gating a non-payment feature on identity verification. Vivamo will still initiate the KYC flow during payment/disbursement initiation if this step is skipped or not implemented.
1. Get the KYC info
Retrieve the customer's KYC information using the Get Customer KYC Info endpoint. This includes a clientSecretKey that you'll use to mount the SDK widget in the next step.
2. Mount the SDK widget (with event listener)
Call the createKycElements SDK method with the clientSecretKey from the previous step. This mounts a KYC verification widget on your page, which walks the customer through submitting their information and documents. The SDK polls for completion and fires a kyc-completed event when the status changes to verified, verified_manually, rejected, or expired.
3. Legacy flows (deprecated)
Two older paths still work for backwards compatibility, but both will be removed. Don't use them for new integrations.
verifyAfterCreationflag
Create Customer accepts a verifyAfterCreation boolean that kicks off KYC as part of the creation call. The operator-initiated flow above gives you the same outcome but with a status and a clientSecretKey you can react to explicitly, which is why it replaces this one.
Raw verification URLs
Get Customer KYC Info also returns raw provider links on kycVerification.data: driversLicenseVerificationUrl, passportVerificationUrl, and a generic url. You can hand these to the customer directly (in an email or SMS, for instance) if you don't want to use the SDK. There's no polling and no kyc-completed event, so you'll need to watch for the kyc_verification webhook to know when the customer is done.
Link expiration
The underlying verification link expires after 1 hour. The SDK renews expired links automatically when the customer loads the widget, so you don't have to handle renewal yourself. The clientSecretKey itself stays valid for 24 hours.
Verification statuses
| Status | Description |
|---|---|
pending | The verification link has been generated and is awaiting the customer's submission. |
verified | The customer passed identity verification automatically. |
under_review | The submission requires manual review by your team. |
rejected | The customer failed identity verification. |
expired | The verification link expired before the customer completed it. |
verified_manually | You manually approved the customer via the API. |
rejected_manually | You manually rejected the customer via the API. |
Manual review
Some submissions can't be resolved automatically. When that happens, the status moves to under_review and we send a kyc_verification webhook to your backend. Customers sitting in under_review are blocked from transacting until you resolve them.
You can't manually verify a customer who hasn't attempted verification themselves. Vital information (age, for example) may not be on file yet.
Retrieving customers for review
Approving or rejecting
Call Set Customer KYC Manually Verified:
Pass verify: false to reject instead.
Webhooks
Vivamo sends a kyc_verification webhook when a customer's KYC status changes. See the Webhooks guide for authentication details.
For rejected verifications, a reason field explains the failure.
Notes
- KYC requirements are set during onboarding. Contact Vivamo support if you need to change them.
proof_of_id(Driver's License or Passport) is the only verification type right now. Non-document verification isn't available yet.