End-to-end onboarding
This guide describes a complete onboarding flow for a connected account using the Paypercut APIs.
It demonstrates how to progress from account creation to an operational state where the account can accept payments and receive payouts.
Step 1: Create a connected account
Create a new account and request the required capabilities
POST /v1/accounts
{
"type": "custom",
"business_type": "company",
"country": "BG",
"email": "merchant@example.com",
"capabilities": {
"card_payments": { "requested": true },
"payouts": { "requested": true }
}
}
Response
{
"id": "01KN7T8K7WRF9C8MF1CA4KPM6Z",
"requirements": {
"currently_due": [
"business_profile.name",
"company.tax_id",
"representative.first_name"
]
},
"capabilities": {
"card_payments": "inactive",
"payouts": "inactive"
}
}
Step 2: Collect required information
Use the requirements.currently_due field to determine what information must be collected.
Typical required data includes:
- Business profile information
- Company registration data
- Representative details
Your platform should dynamically render forms based on these requirements.
Step 3: Update the account
Submit collected data using the account update endpoint.
PUT /v1/accounts/01KN7T8K7WRF9C8MF1CA4KPM6Z
{
"business_profile": {
"name": "ACME Ltd"
},
"company": {
"tax_id": "BG123456789"
}
}
Step 4: Create persons
If the account represents a business, create associated persons such as representatives or owners.
POST /v1/accounts/01KN7T8K7WRF9C8MF1CA4KPM6Z/persons
{
"first_name": "Yavor",
"last_name": "Yankov",
"relationship": {
"title": "Director",
"representative": true
},
"dob": {
"day": 1,
"month": 4,
"year": 1984
},
"nationality": "BG",
"address": {
"country": "BG"
}
}
Step 5: Upload documents
Upload verification documents.
multipart/form-data.POST /v1/files
{
"id": "01KMZAXSM0WHZSV0BRC8FAW5WM",
"purpose": "identity_document"
}
Attach the file to the account or person:
PUT /v1/accounts/01KN7T8K7WRF9C8MF1CA4KPM6Z
{
"documents": {
"proof_of_registration": {
"files": ["01KMZAXSM0WHZSV0BRC8FAW5WM"]
}
}
}
Step 6: Start identity verification
After submitting account details and creating the representative, start identity verification.
Creating verification sessions requires additional permission that is not granted by default. Contact your account manager to enable access before using this endpoint.
POST /v1/identity/verification_sessions
After creating the session, deliver the verification flow to the representative.
This can be done by:
- Redirecting the user
- Embedding the flow in your application
- Sending the verification link via email
Your platform is responsible for presenting the identity verification flow. Paypercut does not contact the end user directly.
Step 7: Add payout details
Attach a payout destination to the account.
POST /v1/accounts/01KN7T8K7WRF9C8MF1CA4KPM6Z/external_accounts
{
"external_account": {
"object": "bank_account",
"country": "BG",
"currency": "EUR",
"holder_name": "ACME Ltd",
"holder_type": "company",
"numbers": {
"scheme": "iban",
"iban": "BG89370400440532013000",
"bic": "COBADEFFXXX"
}
}
}
Step 8: Complete compliance tasks
Some onboarding flows require additional compliance actions, such as accepting agreements.
Retrieve the account compliance status:
GET /v1/risk/account_status
If tasks are returned, render them in your platform UI.
Example response
{
"account_id": "01KN7T8K7WRF9C8MF1CA4KPM6Z",
"blocking": true,
"status": "action_required",
"tasks": [
{
"id": "task_01KN918Z521RGDDTH65DF7AQAZ",
"kind": "agreement_bundle",
"blocking": true
}
]
}
Present the documents and collect acceptance from an authorized person.
Submit the attestation:
POST /v1/attestations
After submission, re-fetch the account status to confirm that the task has been resolved.
Step 9: Monitor account status
Listen for account updates via webhooks.
Event:
account.updated
Example payload
{
"requirements": {
"currently_due": [],
"pending_verification": ["company.verification.document"]
}
}
Step 10: Account becomes operational
Once all requirements are satisfied and verification is complete:
{
"capabilities": {
"card_payments": "active",
"payouts": "active"
},
"payments_enabled": true,
"payouts_enabled": true
}
Integration principle
The onboarding flow must always be driven by:
- requirements
- capabilities
Avoid hardcoding onboarding steps. The API response defines the required state and next actions.

