Decision Callbacks

Endpoint Configuration: callback_url

📘
Important:
This callback is only sent for business verification sessions that are NOT linked to a business profile.

The decision callback delivers the final snapshot of the KYB workflow once it reaches a terminal state.

When It's Triggered

KYB workflow reaches a terminal state:
- APPROVED: All business checks passed
- DECLINED: One or more checks failed
- MANUAL_REVIEW: Requires human review
- FAILED: Technical error in processing

Payload Structure: `BusinessVerificationResultPayload`

{
  "verification_session_id": "bvs_abc123",
  "template_id": "tmpl_kyb_standard",
  "client_reference_id": "business_12345",
  "client_reference_data": {
    "business_tier": "enterprise",
    "onboarding_source": "sales_referral",
    "account_manager": "[email protected]"
  },
  "aiprise_summary": {
    "decision": "APPROVED",
    "status": "COMPLETED",
    "warning_codes": [],
    "reasons": [],
    "notes": "Business verification completed successfully"
  },
  "status": "COMPLETED",
  "created_at": 1702345678000,
  "status_reasons": [],
  "business_input": {
    "business_data": {
      "legal_name": "Acme Corporation Ltd",
      "trading_name": "Acme",
      "company_number": "12345678",
      "jurisdiction": "GB",
      "incorporation_date": "2015-03-15",
      "business_type": "LIMITED_COMPANY",
      "industry": "FINTECH",
      "website": "https://acme.com",
      "phone": "+44 20 1234 5678",
      "email": "[email protected]",
      "registered_address": {
        "street": "123 Business Park",
        "city": "London",
        "postal_code": "EC1A 1BB",
        "country": "GB"
      },
      "trading_address": {
        "street": "456 High Street",
        "city": "London",
        "postal_code": "W1A 1AA",
        "country": "GB"
      }
    },
    "additional_business_info": {
      "incorporation_certificate_url": "https://presigned-url/cert.pdf",
      "articles_of_association_url": "https://presigned-url/articles.pdf",
      "proof_of_address_url": "https://presigned-url/utility-bill.pdf"
    }
  },
  "business_info": {
    "formation_date": "2015-03-15",
    "business_age_years": 9,
    "industry_classification": {
      "primary": "FINTECH",
      "sic_code": "64190",
      "description": "Financial technology services"
    },
    "company_size": {
      "employees": 150,
      "revenue_band": "10M-50M",
      "size_classification": "MEDIUM"
    },
    "business_structure": "LIMITED_COMPANY",
    "tax_identifiers": {
      "vat_number": "GB123456789",
      "tax_id": "1234567890"
    }
  },
  "registration_info": {
    "registry_checks": [
      {
        "registry_name": "Companies House UK",
        "status": "ACTIVE",
        "registration_number": "12345678",
        "verified": true,
        "last_updated": "2024-12-01",
        "filing_status": "UP_TO_DATE"
      }
    ],
    "business_status": "ACTIVE",
    "good_standing": true
  },
  "aml_info": {
    "result": "CLEAR",
    "screening_status": "COMPLETED",
    "matches": [],
    "monitoring_enabled": true,
    "next_monitoring_run": "2024-02-01T00:00:00Z",
    "lists_checked": [
      "OFAC SDN",
      "EU Consolidated Sanctions",
      "UK HMT Sanctions",
      "UN Sanctions"
    ]
  },
  "fraud_insights": {
    "overall_risk_score": 18,
    "risk_level": "LOW",
    "signals": [
      {
        "signal_type": "company_age",
        "risk_score": 5,
        "description": "Established business (9 years)"
      },
      {
        "signal_type": "registry_verification",
        "risk_score": 8,
        "description": "Registry data matches submitted information"
      },
      {
        "signal_type": "address_verification",
        "risk_score": 5,
        "description": "Business address verified via proof of address"
      }
    ]
  },
  "lookup_info": [
    {
      "provider": "companies_house",
      "status": "MATCH",
      "verified_fields": [
        "legal_name",
        "company_number",
        "incorporation_date",
        "registered_address",
        "business_type"
      ],
      "data_freshness": "2024-12-01"
    },
    {
      "provider": "credit_bureau",
      "status": "MATCH",
      "credit_score": 82,
      "credit_rating": "GOOD"
    }
  },
  "risk_info": {
    "risk_score": 22,
    "risk_tier": "LOW",
    "contributing_factors": [
      {
        "factor": "new_business_relationship",
        "weight": 10
      },
      {
        "factor": "high_risk_industry",
        "weight": 12
      }
    ]
  },
  "related_persons": [
    {
      "person_reference_id": "person_ceo_001",
      "roles": ["CEO", "DIRECTOR"],
      "user_profile": {
        "first_name": "John",
        "last_name": "Smith",
        "date_of_birth": "1980-05-15",
        "nationality": "GB"
      },
      "ownership_percent": 45.0,
      "shares_allocated": 4500,
      "verification_status": "APPROVED",
      "kyc_completed": true,
      "aml_status": "CLEAR"
    },
    {
      "person_reference_id": "person_cfo_002",
      "roles": ["CFO", "DIRECTOR"],
      "user_profile": {
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1985-08-22",
        "nationality": "GB"
      },
      "ownership_percent": 30.0,
      "shares_allocated": 3000,
      "verification_status": "APPROVED",
      "kyc_completed": true,
      "aml_status": "CLEAR"
    },
    {
      "person_reference_id": "person_ubo_003",
      "roles": ["UBO"],
      "user_profile": {
        "first_name": "Robert",
        "last_name": "Johnson",
        "date_of_birth": "1975-11-30",
        "nationality": "GB"
      },
      "ownership_percent": 25.0,
      "shares_allocated": 2500,
      "verification_status": "APPROVED",
      "kyc_completed": true,
      "aml_status": "CLEAR"
    }
  ],
  "related_companies": [
    {
      "company_reference_id": "company_parent_001",
      "legal_name": "Acme Holdings PLC",
      "jurisdiction": "GB",
      "company_number": "87654321",
      "relationship_type": "PARENT",
      "ownership_percent": 100.0,
      "verification_status": "APPROVED",
      "kyb_completed": true
    }
  ]
}

Key Payload Sections

Section	Description
`aiprise_summary`	High-level decision, status, and reasons
`business_input`	Submitted business data and document URLs
`business_info`	Derived business attributes (age, size, industry)
`registration_info`	Government registry lookups and verification
`aml_info`	AML screening results for the business entity
`fraud_insights`	Business fraud detection signals
`lookup_info`	External data verification (credit bureaus, registries)
`risk_info`	Overall business risk assessment
`related_persons`	Officers, directors, and UBOs (Ultimate Beneficial Owners)
`related_companies`	Parent companies, subsidiaries, related entities

Decision Flow for Business Verification

callback_url received
    ↓
Verify HMAC signature
    ↓
Parse aiprise_summary.decision
    ↓
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│    APPROVED     │    DECLINED     │  MANUAL_REVIEW  │     FAILED      │
└────────┬────────┴────────┬────────┴────────┬────────┴────────┬────────┘
         ↓                 ↓                 ↓                 ↓
   Enable account    Deny onboarding   Queue for review   Retry/notify
   Set credit limits Notify business   Notify compliance  Technical team
   Generate contract Log reasons       Complex structure  Error handling
   Assign rep        Compliance flag   Additional docs

Updated about 7 hours ago