KYC/KYB Frontend Integration Guide

This guide walks you through integrating Yativo KYC (individual) and KYB (business) verification into your application. You can choose a hosted approach for quick integration or a fully custom API integration for maximum control.

Integration approaches

Approach	Best For	Effort	Customization
Hosted KYC/KYB Link	Quick launch, iframe embed	Low	Limited
Custom API Integration	Full control, native UI	High	Full

Option A: Hosted links (recommended)

The simplest integration. You create a customer, then redirect them to Yativo’s hosted verification flow at https://kyc.yativo.com.

Step 1: Keep your API key on your backend

Every call to Yativo is made with your API key (X-Api-Key and X-Api-Secret). Make those calls from your backend only. Your web or mobile app talks to your backend, and your backend talks to Yativo.

Never put your API key or secret in browser or mobile code. Anyone could read it and act on your account. The code samples below that read process.env run on your server.

Step 2: Create a customer

async function createCustomer(customerData) {
  const response = await fetch('https://api.yativo.com/api/v1/customer', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.YATIVO_API_KEY,
      'X-Api-Secret': process.env.YATIVO_API_SECRET,
      'Content-Type': 'application/json',
      'Idempotency-Key': `create-customer-${customerData.email}-${Date.now()}`,
    },
    body: JSON.stringify({
      customer_name: customerData.name,
      customer_email: customerData.email,
      customer_phone: customerData.phone,
      customer_country: customerData.country, // ISO 3166-1 alpha-2, e.g. "US"
      customer_type: 'individual', // or 'business'
    }),
  });

  const data = await response.json();
  return data.data.customer_id;
}

Step 3: Redirect to hosted KYC

function redirectToKYC(customerId) {
  // Redirect individual customers
  window.location.href = `https://kyc.yativo.com/individual/${customerId}`;
}

function redirectToKYB(customerId) {
  // Redirect business customers
  window.location.href = `https://kyc.yativo.com/business/${customerId}`;
}

Embedding in an iframe

If you prefer to embed verification within your application instead of a full redirect:

<iframe
  src="https://kyc.yativo.com/individual/CUSTOMER_ID"
  allow="camera; microphone"
  width="100%"
  height="700px"
  style="border: none; border-radius: 8px;"
  title="Identity Verification"
></iframe>

The allow="camera; microphone" attribute is required for document capture and selfie steps to work correctly in the iframe.

Step 4: Wait for the endorsement result

Verification results arrive only through the customer’s endorsements. Each endorsement covers one service, such as base or sepa, and has its own status. Listen for the endorsement.updated webhook on your backend, then tell your frontend. See Handle endorsement updates. While you wait, show the customer that verification is in progress. Don’t show an approval until the endorsement for the service they need is approved.

Option B: Custom API integration

Build your own multi-step form that collects customer data and submits it directly to the KYC API.

Step 1: Collect personal information

import { useState } from 'react';

function PersonalInfoStep({ onNext }) {
  const [form, setForm] = useState({
    first_name: '',
    last_name: '',
    email: '',
    phone: '',
    calling_code: '+1',
    gender: '',
    birth_date: '',
    nationality: '',
    taxId: '',
    // Nigerian nationals only
    bvn: '',
    nin: '',
  });

  const handleChange = (field) => (e) =>
    setForm((prev) => ({ ...prev, [field]: e.target.value }));

  const isNigerian = form.nationality === 'NG';

  return (
    <form onSubmit={(e) => { e.preventDefault(); onNext(form); }}>
      <input
        placeholder="First Name"
        value={form.first_name}
        onChange={handleChange('first_name')}
        required
      />
      <input
        placeholder="Last Name"
        value={form.last_name}
        onChange={handleChange('last_name')}
        required
      />
      <input
        type="email"
        placeholder="Email"
        value={form.email}
        onChange={handleChange('email')}
        required
      />
      {/* Gender accepts only "male" or "female" */}
      <select value={form.gender} onChange={handleChange('gender')} required>
        <option value="">Select gender</option>
        <option value="male">Male</option>
        <option value="female">Female</option>
      </select>
      <input
        type="date"
        value={form.birth_date}
        onChange={handleChange('birth_date')}
        required
      />
      <input
        placeholder="Nationality (ISO alpha-2, e.g. US)"
        value={form.nationality}
        onChange={handleChange('nationality')}
        required
      />
      {isNigerian && (
        <>
          <input
            placeholder="BVN (11 digits)"
            value={form.bvn}
            onChange={handleChange('bvn')}
            maxLength={11}
            required
          />
          <input
            placeholder="NIN (11 digits)"
            value={form.nin}
            onChange={handleChange('nin')}
            maxLength={11}
            required
          />
        </>
      )}
      <button type="submit">Next</button>
    </form>
  );
}

When nationality is "NG", both bvn and nin (each exactly 11 digits) are required by the API. Show these fields conditionally based on the selected nationality.

Step 2: Upload files via Yativo storage

Before submitting the KYC form, upload document images using Yativo’s storage endpoint. This keeps payloads small and avoids base64 encoding large files.

/**
 * Upload a file to Yativo storage and return a hosted URL
 * to pass into the KYC payload.
 */
async function uploadDocument(file) {
  const formData = new FormData();
  formData.append('document', file); // field name must be "document"

  const response = await fetch('https://api.yativo.com/api/v1/storage/upload', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.YATIVO_API_KEY,
      'X-Api-Secret': process.env.YATIVO_API_SECRET,
      // Do NOT set Content-Type — let the browser set it with the boundary
    },
    body: formData,
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.message || 'File upload failed');
  }

  const data = await response.json();
  return data.data.document; // Pass this URL in the KYC payload
}

You can also pass files as base64-encoded strings inline, but the hosted URL approach is recommended for files over ~500 KB.

function fileToBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(reader.result); // Returns data URL (base64)
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}

Step 3: Collect residential address

function AddressStep({ onNext }) {
  const [address, setAddress] = useState({
    street_line_1: '',
    city: '',
    state: '',
    postal_code: '',
    country: '',
  });
  const [proofFile, setProofFile] = useState(null);
  const [uploading, setUploading] = useState(false);

  const handleFileChange = async (e) => {
    const file = e.target.files[0];
    if (!file) return;
    setUploading(true);
    try {
      const url = await uploadDocument(file);
      setProofFile(url);
    } finally {
      setUploading(false);
    }
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    onNext({ ...address, proof_of_address_file: proofFile });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        placeholder="Street Address"
        value={address.street_line_1}
        onChange={(e) => setAddress((a) => ({ ...a, street_line_1: e.target.value }))}
        required
      />
      <input
        placeholder="City"
        value={address.city}
        onChange={(e) => setAddress((a) => ({ ...a, city: e.target.value }))}
        required
      />
      <input
        placeholder="State / Province"
        value={address.state}
        onChange={(e) => setAddress((a) => ({ ...a, state: e.target.value }))}
        required
      />
      <input
        placeholder="Postal Code"
        value={address.postal_code}
        onChange={(e) => setAddress((a) => ({ ...a, postal_code: e.target.value }))}
        required
      />
      <label>
        Proof of Address (utility bill, bank statement, etc.)
        <input type="file" accept="image/*,.pdf" onChange={handleFileChange} required />
        {uploading && <span>Uploading…</span>}
        {proofFile && <p>✓ Uploaded</p>}
      </label>
      <button type="submit" disabled={uploading || !proofFile}>
        Next
      </button>
    </form>
  );
}

Step 4: Collect ID document

function IdDocumentStep({ onNext }) {
  const [doc, setDoc] = useState({
    type: 'passport',
    issuing_country: '',
    number: '',
    date_issued: '',
    expiration_date: '',
    image_front_file: null,
    image_back_file: null,
  });

  const handleFileUpload = (field) => async (e) => {
    const file = e.target.files[0];
    if (!file) return;
    const url = await uploadDocument(file);
    setDoc((d) => ({ ...d, [field]: url }));
  };

  const needsBack = doc.type !== 'passport';

  return (
    <form onSubmit={(e) => { e.preventDefault(); onNext([doc]); }}>
      <select
        value={doc.type}
        onChange={(e) => setDoc((d) => ({ ...d, type: e.target.value }))}
      >
        <option value="passport">Passport</option>
        <option value="national_id">National ID</option>
        <option value="other">Other</option>
      </select>
      <input
        placeholder="Document Number"
        value={doc.number}
        onChange={(e) => setDoc((d) => ({ ...d, number: e.target.value }))}
        required
      />
      <label>
        Issue Date
        <input
          type="date"
          value={doc.date_issued}
          onChange={(e) => setDoc((d) => ({ ...d, date_issued: e.target.value }))}
          required
        />
      </label>
      <label>
        Expiration Date
        <input
          type="date"
          value={doc.expiration_date}
          onChange={(e) => setDoc((d) => ({ ...d, expiration_date: e.target.value }))}
          required
        />
      </label>
      <label>
        Front of Document
        <input type="file" accept="image/*,.pdf" onChange={handleFileUpload('image_front_file')} required />
        {doc.image_front_file && <p>✓ Front uploaded</p>}
      </label>
      {needsBack && (
        <label>
          Back of Document
          <input type="file" accept="image/*,.pdf" onChange={handleFileUpload('image_back_file')} required />
          {doc.image_back_file && <p>✓ Back uploaded</p>}
        </label>
      )}
      <button type="submit">Next</button>
    </form>
  );
}

Step 5: Collect financial information

The values sent to the API are snake_case identifiers, not display labels. Use the exact values below — the API will reject any other values.

function FinancialInfoStep({ onNext }) {
  const [financial, setFinancial] = useState({
    employment_status: '',
    most_recent_occupation_code: '',
    source_of_funds: '',
    account_purpose: '',
    account_purpose_other: '',
    expected_monthly_payments_usd: '',
    acting_as_intermediary: false,
  });

  const showOtherPurpose = financial.account_purpose === 'other';

  return (
    <form onSubmit={(e) => { e.preventDefault(); onNext(financial); }}>
      <select
        value={financial.employment_status}
        onChange={(e) => setFinancial((f) => ({ ...f, employment_status: e.target.value }))}
        required
      >
        <option value="">Employment Status</option>
        <option value="employed">Employed</option>
        <option value="self_employed">Self-Employed</option>
        <option value="unemployed">Unemployed</option>
        <option value="retired">Retired</option>
        <option value="student">Student</option>
        <option value="homemaker">Homemaker</option>
        <option value="exempt">Exempt</option>
      </select>

      <select
        value={financial.source_of_funds}
        onChange={(e) => setFinancial((f) => ({ ...f, source_of_funds: e.target.value }))}
        required
      >
        <option value="">Source of Funds</option>
        <option value="salary">Salary</option>
        <option value="company_funds">Company Funds</option>
        <option value="savings">Savings</option>
        <option value="investments_loans">Investments / Loans</option>
        <option value="inheritance">Inheritance</option>
        <option value="gifts">Gifts</option>
        <option value="government_benefits">Government Benefits</option>
        <option value="pension_retirement">Pension / Retirement</option>
        <option value="sale_of_assets_real_estate">Sale of Assets / Real Estate</option>
        <option value="ecommerce_reseller">E-commerce / Reseller</option>
        <option value="gambling_proceeds">Gambling Proceeds</option>
        <option value="someone_elses_funds">Someone Else's Funds</option>
      </select>

      <select
        value={financial.account_purpose}
        onChange={(e) => setFinancial((f) => ({ ...f, account_purpose: e.target.value }))}
        required
      >
        <option value="">Account Purpose</option>
        <option value="receive_salary">Receive Salary</option>
        <option value="purchase_goods_and_services">Purchase Goods & Services</option>
        <option value="personal_or_living_expenses">Personal / Living Expenses</option>
        <option value="payments_to_friends_or_family_abroad">Payments to Friends/Family Abroad</option>
        <option value="receive_payment_for_freelancing">Receive Payment for Freelancing</option>
        <option value="investment_purposes">Investment Purposes</option>
        <option value="protect_wealth">Protect Wealth</option>
        <option value="ecommerce_retail_payments">E-commerce / Retail Payments</option>
        <option value="operating_a_company">Operating a Company</option>
        <option value="charitable_donations">Charitable Donations</option>
        <option value="other">Other</option>
      </select>

      {showOtherPurpose && (
        <input
          placeholder="Describe your account purpose"
          value={financial.account_purpose_other}
          onChange={(e) => setFinancial((f) => ({ ...f, account_purpose_other: e.target.value }))}
          required
        />
      )}

      <select
        value={financial.expected_monthly_payments_usd}
        onChange={(e) => setFinancial((f) => ({ ...f, expected_monthly_payments_usd: e.target.value }))}
        required
      >
        <option value="">Expected Monthly Volume (USD)</option>
        <option value="0_4999">Less than $5,000</option>
        <option value="5000_9999">$5,000 – $9,999</option>
        <option value="10000_49999">$10,000 – $49,999</option>
        <option value="50000_plus">$50,000 or more</option>
      </select>

      <label>
        <input
          type="checkbox"
          checked={financial.acting_as_intermediary}
          onChange={(e) => setFinancial((f) => ({ ...f, acting_as_intermediary: e.target.checked }))}
        />
        Acting on behalf of a third party
      </label>

      <button type="submit">Next</button>
    </form>
  );
}

Step 6: Submit to the KYC API

async function submitKYC(customerId, formData) {
  const payload = {
    customer_id: customerId,
    // Personal info
    ...formData.personal,
    // Residential address (including proof_of_address_file URL)
    residential_address: formData.address,
    // ID documents (array of document objects with uploaded URLs)
    identifying_information: formData.documents,
    // Financial & purpose
    ...formData.financial,
    // Selfie image URL from storage upload
    selfie_image: formData.selfieUrl,
    // Supporting documents
    uploaded_documents: formData.supportingDocs,
  };

  // Remove account_purpose_other unless account_purpose is "other"
  if (payload.account_purpose !== 'other') {
    delete payload.account_purpose_other;
  }

  const response = await fetch('https://kyc.yativo.com/api/individual-kyc/submit', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Idempotency-Key': `kyc-${customerId}-${Date.now()}`,
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'KYC submission failed');
  }

  return response.json();
}

The KYC submission endpoint is at https://kyc.yativo.com, not the main API. Send the same API key headers you use for every other request.

Handle endorsement updates

Register your webhook once with POST /business/webhook (see Webhooks). Yativo sends endorsement.updated with the customer’s full list of endorsements each time one changes:

type EndorsementStatus =
  | 'not_started' | 'submitted' | 'pending' | 'under_review'
  | 'approved' | 'rejected' | 'declined';

interface Endorsement {
  service: string;          // e.g. "base", "sepa", "faster_payments"
  status: EndorsementStatus;
}

// Express.js. Verify the `Signature` header first (see Webhooks).
app.post('/webhooks/yativo', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();
  res.sendStatus(200);

  const event = JSON.parse(req.body);
  if (event['event.type'] !== 'endorsement.updated') return;

  const { customer_id, endorsements } = event.payload as {
    customer_id: string;
    endorsements: Endorsement[];
  };

  await saveEndorsements(customer_id, endorsements);

  for (const e of endorsements) {
    if (e.status === 'approved') await enableService(customer_id, e.service);
    if (e.status === 'rejected') await askCustomerToFix(customer_id, e.service);
  }
});

To refresh your stored copy, for example after downtime, read the endorsement list from GET /customer/{customer_id} on your backend. There, service is title-cased ("Faster payments"), and each entry also has hosted_kyc_url, errors and requirements_due to show the customer what to fix. See Track verification with endorsements.

UI/UX best practices

Progress indicators Show a clear multi-step progress bar so customers know where they are in the verification process. For individual KYC: Personal Info → Address & Documents → ID Document → Financial Info → Review & Submit. Clear error messages Display field-level validation errors immediately, not just on submit. Translate API error codes into user-friendly language. The API returns a data object with field-specific error arrays on 422 responses. Document upload previews Always show a preview of uploaded documents before submission. This helps customers catch blurry or incorrectly oriented images before they fail review.

function DocumentPreview({ url, label }) {
  if (!url) return null;
  const isImage = /\.(jpg|jpeg|png|heic)$/i.test(url) || url.startsWith('data:image');
  return (
    <div style={{ marginTop: 8 }}>
      <p style={{ fontSize: 12, color: '#666' }}>{label} preview:</p>
      {isImage ? (
        <img
          src={url}
          alt={label}
          style={{ maxWidth: 300, maxHeight: 200, objectFit: 'contain', border: '1px solid #ddd' }}
        />
      ) : (
        <p style={{ color: '#888' }}>📄 PDF uploaded</p>
      )}
    </div>
  );
}

Mobile camera support Use capture="environment" on file inputs to open the rear camera directly on mobile:

<!-- Opens rear camera for document capture -->
<input type="file" accept="image/*" capture="environment" />

<!-- Opens front camera for selfie -->
<input type="file" accept="image/*" capture="user" />

Selfie guidance For the selfie step, display on-screen guidelines (oval face outline, lighting tips) before the customer takes their photo to reduce re-submission rates. Retry on rejection When a customer’s KYC is rejected, use the kyc_link from the status response to send them back to the hosted flow for corrections.

const statusData = await getKycStatus(customerId);
if (statusData.status === 'rejected') {
  const kycLink = statusData.kyc_link;
  // Show retry button that redirects to kycLink
  console.log('Rejection reasons:', statusData.kyc_rejection_reasons);
}

Get Started

Payments

Wallets

Customers & Compliance

Transactions

Products

Developer Tools

SDKs

Regional Guides

KYC/KYB Frontend Integration Guide

Integration approaches

Option A: Hosted links (recommended)

Step 1: Keep your API key on your backend

Step 2: Create a customer

Step 3: Redirect to hosted KYC

Embedding in an iframe

Step 4: Wait for the endorsement result

Option B: Custom API integration

Step 1: Collect personal information

Step 2: Upload files via Yativo storage

Step 3: Collect residential address

Step 4: Collect ID document

Step 5: Collect financial information

Step 6: Submit to the KYC API

Handle endorsement updates

UI/UX best practices

​Integration approaches

​Option A: Hosted links (recommended)

​Step 1: Keep your API key on your backend

​Step 2: Create a customer

​Step 3: Redirect to hosted KYC

​Embedding in an iframe

​Step 4: Wait for the endorsement result

​Option B: Custom API integration

​Step 1: Collect personal information

​Step 2: Upload files via Yativo storage

​Step 3: Collect residential address

​Step 4: Collect ID document

​Step 5: Collect financial information

​Step 6: Submit to the KYC API

​Handle endorsement updates

​UI/UX best practices

Integration approaches

Option A: Hosted links (recommended)

Step 1: Keep your API key on your backend

Step 2: Create a customer

Step 3: Redirect to hosted KYC

Embedding in an iframe

Step 4: Wait for the endorsement result

Option B: Custom API integration

Step 1: Collect personal information

Step 2: Upload files via Yativo storage

Step 3: Collect residential address

Step 4: Collect ID document

Step 5: Collect financial information

Step 6: Submit to the KYC API

Handle endorsement updates

UI/UX best practices