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"
  }
}

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.

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.

PUT /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.

The request must be sent as 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.

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.

Verification Sessions API

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.

Overview