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,
      "source": ["MANUAL"],
      "added_via": "DASHBOARD",
      "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,
      "source": ["REGISTRY_LOOKUP"],
      "added_via": "ONBOARDING_FORM",
      "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,
      "source": ["MANUAL"],
      "added_via": "API",
      "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,
      "source": ["REGISTRY_LOOKUP"],
      "added_via": "ONBOARDING_FORM",
      "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 27 days ago

Did this page help you?