Underwrite at apply. Monitor every instalment.

You are integrating Didit into a Buy-Now-Pay-Later (BNPL) checkout flow — Klarna / Affirm / Clearpay / Tabby / Tamara / Kueski archetype. The recipe handles three obligations on every BNPL plan:

  1. Verify the borrower at checkout — identity, liveness, face match, device + IP, AML against 1,300+ sanctions / PEP / adverse-media lists. ONE call to the Sessions API.
  2. Log every instalment charge — Transaction Monitoring catches velocity, structuring, and chargeback patterns. ONE call to the Transactions API per instalment.
  3. Continuous AML — the borrower is rescreened automatically across the lifetime of the plan. NO separate endpoint to call.

Cost:
  - Borrower Know Your Customer (KYC) bundle: $0.33 per application (Sessions API)
  - Transaction monitoring per instalment charge: $0.02 (Transactions API)
  - Ongoing AML monitoring: $0.07 per user per year (automatic on any session with AML enabled)
  - First 500 verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id from the Workflow Builder that bundles ID Verification + Passive Liveness + Face Match 1:1 + Device & IP Analysis + AML Screening.
  - Transaction Monitoring enabled in the Business Console (Transactions > Settings).

STEP 1 — Underwrite the borrower at checkout

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<wf id with KYC + AML bundle>",
      "vendor_data": "<your borrower id, max 256 chars>",
      "callback": "https://<your-app>/bnpl/apply/callback",
      "metadata": {
        "purpose": "bnpl_application",
        "plan_id": "<your internal plan reference>",
        "merchant_id": "<merchant id>",
        "principal_amount": "500.00",
        "currency": "GBP"
      }
    }

  Response: 201 Created with the hosted session URL. Embed the URL inline in the BNPL widget at checkout. Sub-2-second median verdict on completion.

STEP 2 — Read the signed webhook on application completion

  Didit POSTs to your callback. Session statuses are Title Case With Spaces:

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your borrower id>",
      "status": "Approved",
      "id_verification": { "status": "Approved" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94 },
      "ip_analysis": { "status": "Approved" },
      "aml": { "status": "Approved", "hits": [] }
    }

  Status enum (exact case): Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned.

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw bytes with your webhook secret.

  On Approved + clean AML + acceptable Device & IP, approve the plan and schedule the instalments. On Declined or AML hit, decline. On In Review or AWAITING_USER, hold the plan and route to your underwriting analyst queue.

STEP 3 — Log every instalment charge

  POST https://verification.didit.me/v3/transactions/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body (required fields verified live 2026-05-16):
    {
      "transaction_id": "<plan-id>-instalment-1",
      "transaction_category": "finance",
      "transaction_details": {
        "direction": "INBOUND",
        "amount": "125.00",
        "currency": "GBP",
        "currency_kind": "fiat",
        "action_type": "deposit"
      },
      "subject": {
        "entity_type": "individual",
        "vendor_data": "<your borrower id>",
        "full_name": "<borrower full name>"
      },
      "counterparty": {
        "entity_type": "individual",
        "full_name": "<merchant or BNPL settlement counterparty>"
      }
    }

  REQUIRED fields the API rejects if missing:
    - subject.vendor_data + subject.full_name
    - counterparty.full_name
    - transaction_details.direction + currency + currency_kind + amount

  Response shape (excerpted from a real successful 201):
    {
      "uuid": "<server transaction uuid>",
      "txn_id": "<your transaction_id echoed back>",
      "status": "APPROVED",
      "score": 0,
      "severity": null,
      "cost_breakdown": {
        "total_price": 0.02,
        "items": [{ "usage_type": "transaction_monitoring", "price": 0.02 }]
      }
    }

  Transaction status enum (exact case, UPPER_SNAKE_CASE): APPROVED | IN_REVIEW | DECLINED | AWAITING_USER.
  When a transaction enters AWAITING_USER, Didit creates a linked remediation session automatically and returns a verification URL on the response.

  Per-instalment cost: $0.02 (transaction-monitoring base).

  Branch logic:
    APPROVED       → charge the card / pull the bank transfer.
    IN_REVIEW      → hold the instalment, route to analyst queue.
    DECLINED       → hard-fail the instalment, mark the plan delinquent.
    AWAITING_USER  → redirect the borrower to the remediation session URL.

STEP 4 — Continuous AML monitoring is automatic

  Any session with AML enabled is rescreened DAILY by Didit's continuous monitoring at $0.07 per user per year. There is NO separate endpoint to call.

  When a previously-approved borrower crosses an AML threshold, the session status changes to "In Review" or "Declined" automatically and your webhook fires the update. Hold the remaining instalments and route the case to your collections / fraud team.

STEP 5 — Returning borrowers re-use the verified identity

  When a borrower comes back for a second plan, open a new session against their existing vendor_data — Didit reuses the previously verified document and face match where policy allows, and you avoid paying for the full bundle again. Pair with Reusable KYC for the lightest path.

WEBHOOK EVENT NAMES
  - Sessions: status changes flow through the standard session webhook.
  - Transactions: transaction.created · transaction.updated · transaction.status.changed · transaction.alert.generated.
  - Verify X-Signature-V2 on every payload.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review). Transaction statuses use UPPER_SNAKE_CASE (APPROVED, IN_REVIEW). They live in different APIs — don't mix them in the same code path.
  - Never approve a BNPL plan before the X-Signature-V2 webhook lands with status Approved + AML clear.
  - 200+ fraud signals are evaluated on every session at no extra cost — surface the score via the session decision payload, don't re-query.
  - Default record retention is 5 years post-relationship per the EU AML package; UK FCA rules and similar national rules sit on top.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/transaction-monitoring/overview
  - https://docs.didit.me/transaction-monitoring/transactions
  - https://docs.didit.me/core-technology/aml-screening/continuous-monitoring-aml-screening
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.