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 (verifying their identity if your compliance policy calls for it), 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. Identity verification is available for users but is not a precondition for taking a payment.

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.

Verification and payments

Verification state does not gate payment link generation. A user can receive a payment link whatever their kyc_status or external_verification_status is, and there is no verification-related error code on the payment endpoint.

If your compliance policy requires a verified user, read the status yourself and enforce it in your own code before calling POST /checkout/paylink.

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 payment.status_changed webhook to your server as the payment progresses. The payload carries previous_payment_status and current_payment_status.
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. Optionally verify them, either via UrbanPayX KYC or external attestation
7. If your policy requires it, wait for approved or verified before paying

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