Core Concepts

Before you start making API calls, it helps to understand the four entities that make up every payment in UrbanPayX — and how they connect.

The domain model at a glance

Every payment flows through this chain:

Client (you)
  +-- Operating Company (OpCo) — your regulated entity in the payment network
       +-- Project — a container for organizing payments
            +-- User — the person making the payment
                 +-- Transaction — the payment itself

You create an OpCo, link a Project to it, add Users (with identity verification), and then generate payment links for those Users under that Project. The Transaction tracks the payment through to completion.

Operating Companies (OpCos)

An OpCo represents your business entity in the payment network. It is registered as a Sub-TPP (Third Party Provider) with the underlying banking infrastructure and is the entity that receives funds.

Why OpCos exist

Open banking regulations require every payment receiver to be a registered entity. The OpCo is your identity in that system — it carries your business details, registration number, settlement IBAN, and regulatory information.

OpCo types

Type	When to use	Required fields
`licensed_tpp_sole_trader`	Sole trader / individual	`sole_trader` object with `fullName`, `address`, `dateOfBirth`
`licensed_tpp_non_sole_trader_private`	Private company	`ubos` (beneficial owners), `directors`, `signatories` arrays

OpCo lifecycle

DRAFT --> AWAITING_APPROVAL --> ACTIVATED
                            --> REJECTED
                            --> DEACTIVATED

Status	Meaning	What you can do
`draft`	Created locally, not yet submitted	Edit freely, add business details
`awaiting_approval`	Submitted for regulatory review	Wait. In sandbox this takes minutes; in production, 3-5 business days.
`activated`	Approved and ready	Create projects, process payments
`rejected`	Failed regulatory review	Check `status_reason` for details. Create a new OpCo with corrections.
`deactivated`	Previously active, now disabled	Contact support. Cannot be used for new payments.

Key rules

Only draft OpCos can be edited. Once submitted, the details are locked.
An OpCo must be activated before any payment can be processed through it.
Each OpCo gets a provider_entity_id from the upstream provider upon activation — this is its identity in the banking system.

Core fields

Field	Description
`name`	Recognized business name
`legal_entity_name`	Full legal entity name
`company_registration_number`	Business registration number
`merchant_jurisdiction`	Country code (e.g., `DE`, `GB`)
`merchant_iban`	Settlement bank IBAN
`domain`	Fully qualified domain name
`mcc_code`	4-digit Merchant Category Code

Projects

A Project is a container for organizing payments under an OpCo. Think of it as a way to group transactions by business unit, property, product line, or any other dimension that makes sense for your operations.

Why Projects exist

Projects let you separate payment activity within a single OpCo. For a real estate company, each property might be a Project. For a platform, each merchant or business unit could be its own Project.

Project fields

Field	Description
`project_name`	Human-readable name
`opco_id`	The OpCo this project belongs to
`is_frozen`	When `true`, no new payments can be created

Key rules

A Project must be linked to an OpCo that is not rejected or deactivated.
Payments can only be created under a Project whose OpCo is activated.
If a Project is frozen (is_frozen = true), all payment initiation is blocked. Contact support if your project is frozen.

Users (end-payers)

A User is the person making a payment. Before you can generate a payment link for someone, they must exist as a User in UrbanPayX and pass identity verification.

User creation

Create a user with their email and name. Each user is unique per client by email address — you cannot have two users with the same email under your account.

POST /api/v1/kyc/users
{
  "email": "[email protected]",
  "full_name": "Jane Smith",
  "verification_mode": "urbanpayx_kyc"
}

The verification_mode determines how the user's identity is verified. If omitted, it defaults to your client-level setting.

Verification modes

UrbanPayX supports two ways to verify user identity:

1. UrbanPayX KYC (urbanpayx_kyc) — UrbanPayX handles verification via a third-party identity provider. The user completes ID document upload and liveness checks through a hosted verification page.

kyc_status: none --> pending --> approved
                             --> rejected

2. External Attestation (external_attestation) — You handle verification yourself using your own processes, then tell UrbanPayX the result via API.

external_verification_status: pending --> verified
                                      --> rejected

See the KYC Verification Guide for detailed flows, step-by-step instructions, and bulk operations.

Payment eligibility

A user can only receive a payment link when their verification is complete:

Verification mode	Eligible when
`urbanpayx_kyc`	`kyc_status = approved`
`external_attestation`	`external_verification_status = verified`

If you try to generate a payment link for a user who is not yet verified, the API returns a 400 error with a specific code indicating what is missing.

Transactions (payments)

A Transaction represents a single payment. It is created when you generate a payment link and tracks the payment through to completion (or failure).

How a payment works

You generate a payment link — POST /api/v1/checkout/paylink with the amount, currency, user, and project.
The user completes checkout — They are redirected to a bank authentication page where they authorize the payment from their bank account.
The transaction status updates — UrbanPayX sends a webhook to your server as the payment progresses through statuses.
The user is redirected — After checkout, the user is redirected to your callback_url.

Transaction statuses

Status	Terminal?	Meaning
`pending`	No	Payment link created, waiting for user
`processing`	No	User is completing bank authentication
`success`	Yes	Payment confirmed
`failed`	Yes	Bank rejected the payment
`expired`	Yes	Payment link expired before completion
`canceled`	Yes	Payment was canceled

See the Transaction Lifecycle Guide for the full state machine, webhook payloads, and handling recommendations.

Key fields

Field	Description
`amount`	Payment amount (decimal, must be > 0)
`currency`	Always `EUR`
`checkout_url`	URL where the user completes payment
`ref_id`	Short reference ID for the transaction
`status`	Current payment status

Idempotency

Always include an X-Idempotency-Key header when creating transactions. This prevents duplicate payments if your request is retried. See the Transaction Lifecycle Guide for details.

How it all connects

Here is the complete flow from account setup to receiving a payment:

One-time setup:

Create an OpCo with your business details (POST /opcos/create)
Submit it for approval (PATCH /opcos/{id}/submit)
Wait for activation (minutes in sandbox, days in production)
Create a Project under your activated OpCo (POST /projects/create)

Per-user setup:

Create a User (POST /kyc/users)
6. Verify them — either via UrbanPayX KYC or external attestation
7. Wait for verification to complete (approved or verified)

Per-payment:

Generate a payment link (POST /checkout/paylink) with the amount, user, and project
9. Send the checkout_url to your user
10. Listen for payment.status_changed webhooks to track the outcome
11. Handle the final status (success, failed, expired, or canceled)

Related guides

Getting Started — Make your first payment in 15 minutes
Authentication Guide — Token lifecycle, MFA, and security challenges
KYC Verification Guide — Detailed verification flows for both modes
Transaction Lifecycle — State machine, webhooks, and handling patterns
Roles and Permissions — Who can do what
Error Reference — Every error explained