Skip to main content

​
KYB Onboarding

Before you can issue cards in production, Anima requires Know Your Business (KYB) verification. KYB confirms the legal identity of your business and its beneficial owners, satisfying card network compliance requirements. Anima runs KYB through Stripe Connect Custom accounts, so requirements collection and compliance handling stay application-controlled while Stripe handles the underlying verification.
Never issue cards before your KYB status reaches approved. If status regresses from approved to action_required, pause new card issuance immediately.

​
Status lifecycle

KYB moves through a predictable set of states: 
not_started → pending → action_required → in_review → approved / rejected
StatusMeaning
not_startedKYB has not been initiated for this identity
pendingSubmission is in progress
action_requiredStripe requires additional information — surface missing fields to the user
in_reviewStripe is actively reviewing the submission
approvedKYB passed — card issuing is enabled
rejectedKYB failed — contact support
Treat action_required as user-blocking. Surface the missing fields exactly as reported by Stripe requirements so users know precisely what to provide.

​
Start KYB

Call POST /api/identities/:id/kyb/start to initiate verification for an identity. 
const start = await fetch(
  `/api/identities/${identityId}/kyb/start`,
  { method: "POST" },
);

if (!start.ok) throw new Error("Failed to start KYB");

​
Check status

Poll GET /api/identities/:id/kyb/status to read the current state. 
const status = await fetch(`/api/identities/${identityId}/kyb/status`)
  .then((res) => res.json());

// not_started | pending | action_required | in_review | approved | rejected
console.log(status.state);

​
Requirements by business type

The documents Stripe requires depend on the business type and country of operation.
Business typeCountryRequired documents
IndividualUSGovernment-issued ID, date of birth, legal address
CompanyUSEIN, proof of incorporation, beneficial owner identity + controller identity
CompanyGB / EUCompany registration extract, UBO declaration, proof of trading address

​
Handle webhook events

Rather than polling, listen for account.updated events from Stripe to drive KYB state transitions in your system. 
if (event.type === "account.updated") {
  const account = event.data.object;

  const nextState =
    account.requirements?.disabled_reason
      ? "rejected"
      : account.requirements?.currently_due?.length
        ? "action_required"
        : account.requirements?.pending_verification?.length
          ? "in_review"
          : account.details_submitted
            ? "approved"
            : "pending";

  // Update your own database with the new KYB state
  await db.identities.update({
    stripeAccountId: account.id,
    kybState: nextState,
  });
}
Store both the internal KYB state and the raw Stripe account requirements object. This gives you a complete audit trail and makes support triage much faster when users report issues.

​
Next steps

  • Virtual Cards — Issue your first card once KYB is approved
  • Card Controls — Configure spending limits and merchant restrictions