Persons and ownership

For business accounts, Paypercut requires information about the individuals associated with the company.

These individuals are represented as persons and are used for identity verification and regulatory compliance.

When persons are required

Persons are required when the connected account represents a business entity.

Typical roles include:

Representative (legal representative of the business)
Owner (individual with ownership or control)
Director or executive (depending on requirements)

The required roles and number of persons depend on:

Country
Business type
Requested capabilities

Relationship to requirements

Person data is part of the overall verification model.

Missing or incomplete person information appears in:

requirements.currently_due
requirements.past_due

Example:

{
  "requirements": {
    "currently_due": [
      "representative.first_name",
      "owners[0].last_name"
    ]
  }
}

Your platform must collect and submit this information to satisfy onboarding requirements.

Create a person

Create a person associated with a connected account.

POST /v1/accounts/{account_id}/persons

{
  "first_name": "Ivan",
  "last_name": "Petrov",
  "role": "representative"
}

Response

{
  "id": "01KAV365TH7FWS3WMBRBWJ4M0W",
  "account": "01KN7T8K7WRF9C8MF1CA4KPM6Z",
  "first_name": "Ivan",
  "last_name": "Petrov",
  "role": "representative",
  "verification": {
    "status": "pending"
  }
}

Update a person

Update information for an existing person.

POST /v1/accounts/{account_id}/persons/{person_id}

{
  "date_of_birth": "1990-01-01",
  "address": {
    "line1": "Example street 1",
    "city": "Sofia",
    "country": "BG"
  }
}

Attach verification documents

Persons may require identity documents for verification.

Upload a file and attach it to the person:

POST /v1/files

The request must be sent as multipart/form-data.

{
  "id": "file_123",
  "purpose": "identity_document"
}

Attach to person:

POST /v1/accounts/{account_id}/persons/{person_id}

{
  "verification": {
    "document": {
      "front": "file_123"
    }
  }
}

Ownership structure

For some accounts, you must provide information about ownership.

This typically includes:

Identifying individuals with significant ownership or control
Providing personal and verification data for those individuals

Ownership requirements vary by country and may change over time. Always rely on the requirements field to determine what data must be collected.

Verification status

Each person has a verification status:

pending — information submitted but not yet verified
verified — identity successfully verified
failed — verification failed and requires correction

Example:

{
  "id": "person_123",
  "verification": {
    "status": "verified"
  }
}

Best practices

Create persons early in the onboarding flow
Continuously update person data as requirements evolve
Do not hardcode required roles or fields
Always rely on the requirements field for guidance

Notes

A connected account may have multiple persons
Each person is scoped to a single account
Person data is part of the account verification lifecycle

Verification requirements

Document uploads