Managing Entities

Create and manage individual and business entities for identity verification and compliance

Entities represent individuals or businesses that require identity verification for regulatory compliance, risk management, or processing account requirements. This guide covers when to create entities, how to structure entity data for KYC verification, and how to track verification status for individuals and businesses.

Entities are required for processing accounts and recommended for other account types that handle high-value transactions. For standard customer accounts used only for collecting payments, entities are typically optional unless your use case requires KYC verification.

Prerequisites

Before creating entities, it's helpful to learn about the following topics.

Learn about entities and when KYC is required

Understand when entity verification is required, the difference between individual and business entities, and compliance requirements.

Learn how to create accounts

Understand how to create processing accounts that require entity verification and when to attach entities inline versus referencing existing entities.

When to Create Entities

Create entity records when you need to verify the identity of individuals or businesses for regulatory compliance, risk management, or processing account requirements.

Common use cases

Onboarding processing accounts (merchants, partners) who will receive payouts
Verifying beneficial owners and representatives for business accounts
Meeting KYC/KYB requirements for high-value transactions or regulatory compliance
Enabling payout capabilities that require identity verification
Supporting marketplace platforms with seller verification requirements
Maintaining compliance records for processing accounts handling funds

Inline vs Standalone: You can create entities inline when creating processing accounts, or create standalone entity records that can be referenced by multiple accounts. Use standalone entities when the same individual or business will be associated with multiple accounts.

Creating Individual Entities

Create individual entities for people who need identity verification.

Create a basic individual entity

Create an individual entity with minimal required information for identity verification.

create_individual.py

import payload
 
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Create a basic individual entity
entity = pl.Entity.create(
    type='individual',
    legal_name='John Smith',
    country='US',
    phone_number='5555551234',
    tax_id={'value': '123456789'},
    address={
        'address_line_1': '123 Main Street',
        'city': 'New York',
        'state_province': 'NY',
        'postal_code': '10001',
    },
)
 
print(f"Entity created: {entity.id}")

This creates an individual entity with:

type='individual' specifies this is a person, not a business
legal_name is the full legal name used for KYC and tax reporting
country drives tax ID requirements and compliance rules (US or CA)
phone_number is required for verification and communication
tax_id.value is the tax identifier (SSN for US individuals)
address is the residential address used for verification

Use this pattern for processing accounts owned by individuals, sole proprietors, or freelancers who need to receive payouts.

Create individual entity with full details

Create an individual entity with additional optional fields for comprehensive identity verification.

create_individual_complete.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create individual entity with complete details
entity = pl.Entity.create(
    type="individual",
    legal_name="Jane Smith",
    country="US",
    phone_number="5555551234",
    tax_id={"value": "987654321"},
    address={
        "address_line_1": "456 Oak Avenue",
        "address_line_2": "Apt 2B",
        "city": "Los Angeles",
        "state_province": "CA",
        "postal_code": "90001",
    },
)
 
print(f"Entity created: {entity.id}")
print(f"Email: {entity.email}")

This example includes additional fields:

date_of_birth helps with identity verification and age requirements
email provides a contact method for verification communications
address.address_line_2 for apartment or suite numbers
All standard required fields for KYC verification

Use this pattern when you need comprehensive identity records for high-risk processing accounts or regulatory requirements.

Creating Business Entities

Create business entities for companies that require verification as processing accounts.

Create a basic business entity

Create a business entity with core company information and a single stakeholder.

create_business.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create a basic business entity
entity = pl.Entity.create(
    type="business",
    legal_name="Acme Corporation",
    country="US",
    phone_number="5555551234",
    tax_id={"value": "123456789"},
    address={
        "address_line_1": "789 Business Blvd",
        "city": "San Francisco",
        "state_province": "CA",
        "postal_code": "94102",
    },
    business={
        "category": "software",
        "structure": "llc",
        "formation": {
            "date": "2025-02-04",
            "state_province": "CA",
        },
        "website": "https://example.com",
        "stakeholders": [
            {
                "country": "US",
                "personal_information": {
                    "full_name": "John Doe",
                    "email": "[email protected]",
                    "birth_date": "1980-01-15",
                    "phone_number": "5555559999",
                },
                "address": {
                    "address_line_1": "123 Owner St",
                    "city": "San Francisco",
                    "state_province": "CA",
                    "postal_code": "94102",
                },
                "govt_id": {"tax_id": {"value": "123456789"}},
                "association": {
                    "ownership": {"percentage": 100, "years_owned": "5"},
                    "title": "Owner",
                    "roles": {},
                },
            }
        ],
    },
)
 
print(f"Business entity created: {entity.id}")
print(f"Business name: {entity.legal_name}")

This creates a business entity with:

type='business' specifies this is a company
legal_name is the registered business name
business.category describes the business type (e.g., real_estate, retail, software)
business.structure is the legal structure (llc, corporation, partnership, etc.)
business.stakeholders array contains beneficial owners and company representatives
Each stakeholder includes personal information, government ID (tax ID), address, and ownership details

Use this pattern for small businesses with straightforward ownership structures like single-owner LLCs or simple partnerships.

Create business entity with multiple stakeholders

Create a business entity with comprehensive company details and multiple beneficial owners.

create_business_complete.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Create business entity with complete details
entity = pl.Entity.create(
    type="business",
    legal_name="Example LLC",
    country="US",
    phone_number="5555551234",
    tax_id={"value": "987654321"},
    address={
        "address_line_1": "100 Corporate Dr",
        "city": "Austin",
        "state_province": "TX",
        "postal_code": "78701",
    },
    business={
        "category": "real_estate",
        "structure": "llc",
        "website": "https://example.com",
        "formation": {"state_province": "TX", "date": "2019-05-15"},
        "primary_contact": {"name": "Jane Smith", "email": "[email protected]"},
        "stakeholders": [
            {
                "country": "US",
                "personal_information": {
                    "full_name": "Jane Smith",
                    "email": "[email protected]",
                    "birth_date": "1975-08-20",
                    "phone_number": "5555558888",
                },
                "address": {
                    "address_line_1": "200 Elm St",
                    "city": "Austin",
                    "state_province": "TX",
                    "postal_code": "78701",
                },
                "govt_id": {"tax_id": {"value": "111223333"}},
                "association": {
                    "ownership": {"percentage": 60, "years_owned": "7"},
                    "roles": {},
                    "title": "CEO",
                },
            },
            {
                "country": "US",
                "personal_information": {
                    "full_name": "Robert Johnson",
                    "email": "[email protected]",
                    "birth_date": "1978-11-10",
                    "phone_number": "5555557777",
                },
                "address": {
                    "address_line_1": "300 Pine Ave",
                    "city": "Austin",
                    "state_province": "TX",
                    "postal_code": "78702",
                },
                "govt_id": {"tax_id": {"value": "444556666"}},
                "association": {
                    "ownership": {"percentage": 40, "years_owned": "7"},
                    "roles": {},
                    "title": "COO",
                },
            },
        ],
    },
)
 
print(f"Business entity created: {entity.id}")
print(f"Stakeholders: {len(entity.business['stakeholders'])}")

This example includes:

Complete business formation details (state/province, date)
Website and primary contact information
Multiple stakeholders with ownership details including percentage and years owned
Each stakeholder has their own address, government ID, and personal information

Use this pattern for complex business structures with multiple owners, corporations with multiple beneficial owners, or businesses requiring comprehensive KYC records.

Beneficial Owners: Include all individuals who own 25% or more of the business as stakeholders. Each stakeholder must include ownership details with percentage (their equity ownership) and years_owned (how long they've owned the stake). The total ownership percentage across all stakeholders must be at least 25%.

Updating Entities

Update existing entity records when information changes or verification requires additional details.

Updating individual entities

update_individual.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Update individual entity
entity = pl.Entity.get("ent_individual123")
 
entity.update(
    phone_number="5555559999",
    address={
        "address_line_1": "999 New Address St",
        "city": "Seattle",
        "state_province": "WA",
        "postal_code": "98101",
    },
)
 
print(f"Entity updated: {entity.id}")
print(f"New phone: {entity.phone_number}")

Common updates for individuals include:

Address changes when customers move
Phone number updates for communication
Email updates for verification notifications
Correcting information that caused verification failures

Updating business entities

update_business.py

import payload
 
pl = payload.Session("secret_key_3bW9...", api_version="v2")
 
# Update business entity
entity = pl.Entity.get("ent_business123")
 
entity.update(
    phone_number="5555558888",
    address={
        "address_line_1": "500 Updated Plaza",
        "city": "Denver",
        "state_province": "CO",
        "postal_code": "80202",
    },
    business={
        "website": "https://newwebsite.com",
        "primary_contact": {
            "name": "Sarah Williams",
            "email": "[email protected]",
        },
    },
)
 
print(entity)
 
print(f"Business updated: {entity.id}")
print(f"New address: {entity.address['city']}, {entity.address['state_province']}")

Common updates for businesses include:

Adding or removing stakeholders when ownership changes
Updating business addresses or contact information
Modifying beneficial owner designations
Correcting information for re-verification

Re-verification: Significant changes to entity information may trigger re-verification. This is normal for maintaining compliance when ownership structures or key details change.

Tracking Verification Status

Monitor entity verification status to ensure compliance and handle verification failures.

Coming Soon: Real-time verification status tracking and automated webhook notifications are currently in development and will be available soon.

Checking verification status

check_status.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Check entity verification status
entity = pl.Entity.get('ent_abc123')
 
print(f"Entity ID: {entity.id}")
print(f"Legal name: {entity.legal_name}")
print(f"Verification status: {entity.verification.status}")
 
if entity.verification.status == 'verified':
    print('Entity is verified and ready for processing')
elif entity.verification.status == 'pending':
    print('Verification in progress...')
elif entity.verification.status == 'failed':
    print('Verification failed - review failure reasons')
    print(f"Failure reasons: {entity.verification.failure_reasons}")
elif entity.verification.status == 'requires_attention':
    print('Additional information needed')

Entity verification status values:

pending - Verification is in progress
verified - Entity has been successfully verified
failed - Verification failed (review entity.verification.failure_reasons)
requires_attention - Additional information or documentation needed

Handling verification failures

When verification fails, review the failure_reasons array to understand what needs correction:

handle_failures.py

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
# Handle verification failures
entity = pl.Entity.get('ent_failed123')
 
if entity.verification.status == 'failed':
    print('Verification failed. Failure reasons:')
    for reason in entity.verification.failure_reasons:
        print(f"  - {reason}")
 
    # Example: Fix address issue and update entity
    updated_entity = entity.update(
        address={
            'address_line_1': '123 Corrected Street',
            'city': 'Portland',
            'state_province': 'OR',
            'postal_code': '97201'
        }
    )
 
    print('Entity updated with corrected information')
    print(f"New status: {updated_entity.verification.status}")

Common failure reasons include:

Incorrect or incomplete address information
Tax ID mismatch or invalid format
Name mismatch with official records
Insufficient beneficial owner information for businesses
Invalid or expired business registration details

Update the entity with corrected information to trigger re-verification.

Webhook Monitoring: Subscribe to processing_status webhook events to receive real-time notifications when entity verification status changes. See Webhooks for setup details.

Next Steps

Configure processing accounts, monitor verification, and build compliant payment flows

Set Up Processing Accounts

Create processing accounts with Accounts API and attach verified entities, use Enrollment Link for hosted onboarding with automatic entity collection, and configure Processing Settings for payment routing and transaction rules.

Monitor Verification Status

Subscribe to Webhooks for real-time entity verification notifications, implement Signature Verification to secure webhook endpoints, and track verification changes to maintain compliance records.

Enable Payout Capabilities

Configure Automated Funding for processing accounts with verified entities, set up Default Payment Methods for payout destinations, and build payout flows with proper entity verification checks.

Maintain Compliance

Review verification requirements in Entity Overview, implement ongoing monitoring for entity status changes, maintain audit trails of verification history, and handle re-verification when entity information changes.

Default Methods Automated Funding