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": "business",
  "country": "BG",
  "email": "merchant@example.com",
  "capabilities": {
    "payments": { "requested": true },
    "payouts": { "requested": true }
  }
}

Response

{
  "id": "01KN7T8K7WRF9C8MF1CA4KPM6Z",
  "requirements": {
    "currently_due": [
      "business_profile.name",
      "company.tax_id",
      "representative.first_name"
    ]
  },
  "capabilities": {
    "payments": "inactive",
    "payouts": "inactive"
  }
}

Accounts API

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.

POST /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": "Ivan",
  "last_name": "Petrov",
  "role": "representative"
}

Step 5: Upload documents

Upload verification documents.

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

POST /v1/files

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

Attach the file to the account or person:

POST /v1/accounts/01KN7T8K7WRF9C8MF1CA4KPM6Z

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

Step 6: Add payout details

Attach a payout destination to the account.

POST /v1/accounts/01KN7T8K7WRF9C8MF1CA4KPM6Z/external_accounts

{
  "type": "bank_account",
  "iban": "BG80BNBG96611020345678"
}

Step 7: 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_123",
      "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 8: Monitor account status

Listen for account updates via webhooks.

Event:

account.updated

Example payload

{
  "requirements": {
    "currently_due": [],
    "pending_verification": ["company.verification.document"]
  }
}

Step 9: Account becomes operational

Once all requirements are satisfied and verification is complete:

{
  "capabilities": {
    "payments": "active",
    "payouts": "active"
  },
  "charges_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.

Overview