Generate a checkout payment link for a transaction. The endpoint validates the input, creates a new transaction record with status pending, calls the payment provider to mint a checkout session, and returns the transaction together with the hosted checkout_url the payer uses to complete the payment.

Authentication & access

• Requires a client API token: Authorization: Bearer <token>.
• The caller must hold the checkout.paylink.create permission and have the OWNER or OPERATIONS role.
• The client must have payment links enabled. If the feature is disabled the request returns 403.

Payment subject

Each payment is initiated for exactly one subject — provide either user_id (an individual customer) or business_customer_id (a KYB-verified company). Providing both, or neither, is rejected (422).

The subject must already exist under your client and satisfy its verification policy before a link can be generated:

• Individual (user_id): KYC APPROVED (UrbanPayX KYC mode) or external status VERIFIED (external attestation mode).
• Business (business_customer_id): KYB APPROVED (UrbanPayX KYB mode) or external status VERIFIED (external attestation mode).

Pending, on-hold, rejected, or missing verification is rejected with 403.

Project & operating company preconditions

• project_id must reference a project owned by your client and not frozen by an administrator.
• The project's operating company (Opco) must be in ACTIVATED status and have a valid Sub-TPP ID. Otherwise the request returns 400.

Amount & currency

• amount must be greater than 0, at least 0.01, and use at most 2 decimal places.
• currency is EUR only for now.

Idempotency

X-Idempotency-Key (header, required) prevents duplicate payment links on retries.

• To retry, send the same key with an identical payload — you receive the original transaction instead of a new one.
• Reusing the same key with a different payload returns 409.
• A genuinely new payment must use a new key.
• An empty key returns 400.

Callback URL

callback_url (optional, HTTPS only) is where the payer is redirected after completing or canceling the payment. When omitted, it falls back to your client's default callback URL. A non-HTTPS URL is rejected (422).

Responses

• 200 — Link created. checkout_url holds the provider checkout URL and status is pending.
• 202 — The provider call result is uncertain (timeout or transport error). The transaction is persisted as pending with reconciliation_state = awaiting_provider_confirmation and is reconciled later via webhook. Do not retry with a new key — poll the transaction or wait for the webhook.

Error responses