Business identity (KYC)

Why Tyxter asks for this

Tyxter operates in Brazil, and three of the things it does on your behalf are regulated around the legal entity, not the API key:

• NF-e fiscal notes— Brazilian fiscal invoices legally require the buyer's identity (CNPJ/CPF, legal name, registered address, tax regime).
• Phone provisioning — when Tyxter acquires a Brazilian number for you through Salvy, Anatel-regulated subscriber-identity obligations attach to that number.
• Open Finance payment initiation— production Agentic Payments connections initiate PIX payments under Tyxter's regulated relationship with its payment initiation partner.

One business_identity record per organization covers all three. It is org-level: every project and environment under the organization shares the same approval.

What requires approval

Exactly two operations check the gate today, and only in production:

• Production Salvy provisioning — provisioning a Tyxter-acquired number with a tx_live_ key (or from the dashboard in a production environment).
• Production agentic-payments connection registration — registering an Iniciador agentic-payments connection for a production environment (a dashboard / credential-setup flow).

The gate runs before any state is written: a blocked request commits nothing — no phone number row, no reservation, no charge — so it is safe to repeat the same call after approval.

What is never gated

• Everything in sandbox — provisioning, payments, the whole first-touch integration loop.
• BYON — connecting a number you already own via POST /v1/phone-numbers/connect.
• The Meta connection and messaging through your own WABA — that runs under your own Meta relationship and compliance perimeter.
• Templates, contacts, webhooks, API keys, billing top-ups, Abacate Pay connections.

What we collect

Status lifecycle

not_submitted  →  pending_review  →  approved
                                  →  rejected

• Auto-approval: identity submissions — CNPJ or CPF — approve the moment you accept the truthfulness declaration (verification_source = self_declared) — the common case never waits for a human. A submission without the accepted declaration is rejected up front.
• Advisory registry lookup: on CNPJ submissions Tyxter still looks the CNPJ up in the public registry, but the outcome is recorded for operators only — it never blocks, delays, or auto-rejects an approval, and a registry lookup failure never affects the result.
• Manual review: only the separate payments/banking verification — bank-account details used to settle merchant payments — goes to a Tyxter operator; it never auto-approves.
• Resubmission: you can resubmit from any state, including approved (to update your data) and rejected (to fix what was wrong). An identity resubmission with the accepted declaration re-approves instantly.

Error codes

Gated operations return 403 with one of two stable codes (both in the error catalogand on the operation's OpenAPI entry):

kyc_required — no usable identity on file: never submitted, or the last submission was rejected. Submit (or fix and resubmit) in the dashboard.

{
  "error": {
    "type": "authorization_error",
    "code": "kyc_required",
    "message": "Business identity verification is required before this operation. Submit your business identity at https://tyxter.com/kyc?organization_id=org_... (dashboard Settings → Business identity).",
    "request_id": "req_...",
    "trace_id":   "trc_..."
  }
}

kyc_pending — a submission exists and is awaiting review. Nothing to fix on the request; the operation unlocks on approval.

{
  "error": {
    "type": "authorization_error",
    "code": "kyc_pending",
    "message": "Business identity verification is still in progress. This operation unlocks once the identity is approved — track its status at https://tyxter.com/kyc?organization_id=org_....",
    "request_id": "req_...",
    "trace_id":   "trc_..."
  }
}

Where to complete it

Open https://tyxter.com/kyc — a stable link that signs the user in and lands on Settings → Business identity in their default project (the same page is reachable manually from dashboard Settings). Gate errors add an organization_id query parameter so users with more than one organization land on the identity that was blocked. Submitting requires an organization owner or admin role. There is one identity per organization (submissions update it in place), and there is no public /v1KYC endpoint — the dashboard is the only place to submit and the page shows the current status, the verification source, and the reviewer's reason if a submission was rejected.