Getting Started

Accept payments from European bank accounts in your application. UrbanPayX handles the banking rails, KYC verification, and PSD2 compliance — you handle the product.

Time to complete: ~15 minutes in sandbox

What you'll build: By the end of this guide, you'll have created your first payment link and processed a test transaction through the full lifecycle: authenticate → set up your operating company → create a project → register a user → generate a payment link → track the transaction.

Authenticate -> Create OpCo -> Create Project -> Register & verify user -> Generate payment link

Prerequisites

Before you begin, make sure you have:

• An UrbanPayX account (email + password). If you don't have one yet, register at the dashboard or contact our team.
• Your API key and API secret — these were generated when your account was created. You'll find them in your dashboard under Settings.
• A tool for making HTTP requests (cURL, Postman, or your language's HTTP client).

Sandbox vs. Production: This guide uses the sandbox environment (api-sandbox.urbanpayx.com). Everything works identically to production except that OpCo approval takes minutes instead of days, and no real money moves.

Step 1: Authenticate

UrbanPayX supports two authentication methods. For server-to-server integrations (the most common case), use your API key and secret:

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/auth/api-token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "upx_your_api_key_here",
    "api_secret": "your_api_secret_here"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "client_id": "your-client-uuid",
  "actor_type": "client_api",
  "role": "operations"
}

The access_token is a JWT valid for 2 hours. Include it in all subsequent requests as a Bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Note: API key authentication always grants the operations role, which has access to all payment and KYC operations. For dashboard login (email/password), access tokens last 30 minutes and you'll receive a refresh_token (valid 30 days) to renew them. See the Authentication Guide for details on MFA, token refresh, and role-based access.

Step 2: Configure your callback URL

Before you can generate payment links, you need to set a callback URL. This is where your end users will be redirected after completing (or abandoning) a payment.

curl -X PUT https://api-sandbox.urbanpayx.com/api/v1/auth/client/settings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-app.com/payment/callback"
  }'

You should also configure a webhook_url if you want to receive real-time notifications when transaction statuses change. We strongly recommend this for production — see Webhook Setup for details.

Step 3: Create an Operating Company (OpCo)

An OpCo represents the legal entity that will receive funds. Think of it as your company's identity on the payment network. You need at least one activated OpCo before you can process payments.

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/opcos/create \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "opco_type": "licensed_tpp_sole_trader",
    "name": "My Company",
    "domain": "mycompany.com",
    "merchant_jurisdiction": "GB",
    "legal_entity_name": "My Company Ltd",
    "company_registration_number": "12345678",
    "primary_use_case": "PIS_ECOMMERCE",
    "merchant_iban": "GB29NWBK60161331926819",
    "merchant_bic": "NWBKGB2L",
    "mcc_code": "6513",
    "sole_trader": {
      "fullName": "John Smith",
      "address": "123 Main St, London, UK",
      "dateOfBirth": "1990-01-15"
    }
  }'

This creates the OpCo in DRAFT status. Now submit it for approval:

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/opcos/{opco_id}/submit \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The OpCo moves to AWAITING_APPROVAL. In sandbox, approval typically completes within minutes. In production, expect 3-5 business days.

You can check the status at any time:

curl -X GET https://api-sandbox.urbanpayx.com/api/v1/opcos/{opco_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Wait until status is ACTIVATED before proceeding.

OpCo types: Use licensed_tpp_sole_trader for sole traders (requires sole_trader object with personal details). Use licensed_tpp_non_sole_trader_private for companies (requires ubos, directors, and signatories arrays). See the OpCo reference for full field documentation.

Step 4: Create a Project

A Project is a container for organizing payments under an OpCo. You might create one project per property, business unit, or product line.

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/projects/create \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "Main Street Property",
    "opco_id": "your-activated-opco-id"
  }'

Response:

{
  "id": "project-uuid",
  "project_name": "Main Street Property",
  "opco_id": "your-activated-opco-id",
  "is_frozen": false,
  "created_at": "2026-03-26T10:00:00Z",
  "message": "Project created successfully"
}

Save the id — you'll need it when generating payment links.

Step 5: Register and verify a user

A User represents the person making a payment. Users must be created and verified before you can generate a payment link for them.

Create the user:

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/kyc/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "full_name": "Jane Doe"
  }'

Initiate KYC verification:

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/kyc/verify \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "full_name": "Jane Doe",
    "level_name": "id-and-liveness"
  }'

Response:

{
  "user_id": "user-uuid",
  "kyc_status": "pending",
  "verification_url": "https://verify.urbanpayx.com/...",
  "message": "KYC verification initiated"
}

The verification_url is where the user completes identity verification. Once approved, kyc_status changes to approved and you'll receive a kyc.status_changed webhook.

Alternative: External attestation. If you handle KYC yourself, set verification_mode to external_attestation when creating the user, then update their status via POST /api/v1/kyc/external/status/USER_ID. See the KYC Verification Guide for both modes.

Step 6: Generate a payment link

With an activated OpCo, a project, and a verified user, you can now generate a payment link:

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/checkout/paylink \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: unique-key-for-this-payment" \
  -d '{
    "amount": 150.00,
    "currency": "EUR",
    "user_id": "user-uuid",
    "project_id": "project-uuid",
    "description": "March rent payment"
  }'

Response:

{
  "id": "transaction-uuid",
  "status": "pending",
  "amount": "150.00",
  "currency": "EUR",
  "checkout_url": "https://pay.urbanpayx.com/...",
  "checkout_url_v2": "https://api-sandbox.urbanpayx.com/pay/transaction-uuid",
  "created_at": "2026-03-26T10:05:00Z"
}

Redirect your user to checkout_url (or checkout_url_v2 for UrbanPayX-hosted checkout) to complete the payment.

Idempotency: The X-Idempotency-Key header prevents duplicate payments. If you retry a request with the same key and payload, you'll get the original transaction back. If you reuse a key with a different payload, you'll get a 409 Conflict. Always use a unique key per payment intent.

Step 7: Track the transaction

After the user completes (or abandons) the payment, the transaction status will update. You have two ways to track it:

Option A — Webhooks (recommended): If you've configured a webhook_url, you'll receive a payment.status_changed event whenever the transaction status changes. This is the recommended approach for production.

Option B — Polling: You can manually refresh the transaction status:

curl -X POST https://api-sandbox.urbanpayx.com/api/v1/transactions/{transaction_id}/refresh-status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Or retrieve the current transaction details:

curl -X GET https://api-sandbox.urbanpayx.com/api/v1/transactions/{transaction_id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Transaction statuses:

success, failed, expired, and canceled are terminal — the transaction won't change after reaching one of these states. See the Transaction Lifecycle Guide for detailed state transition rules.

What's next?

You've just completed your first payment flow. Here's where to go from here:

• Core Concepts — Understand the domain model: OpCos, Projects, Users, and how they relate to each other.
• Authentication Guide — Deep dive into token management, MFA, refresh flows, and security challenges.
• Error Reference — Every error code, what it means, and how to fix it.
• Transaction Lifecycle — Full state machine, webhook events, and recommended handling patterns.
• Roles & Permissions — Which API actions require which roles, and how API key vs. dashboard auth differs.
• KYC Verification Guide — Both verification modes explained step by step.
• Webhook Setup — Configure webhooks, verify signatures, and handle delivery retries.

Quick reference