Create a payment link
Creates a new transaction and returns a payment checkout URL for the
payer. Requires a unique X-Idempotency-Key header: resubmitting the
same key with an identical payload returns the original transaction
(never double-charges or double-creates); resubmitting the same key with
a different payload returns 409, as does a concurrent request still
in flight with the same key.
The payment subject (user_id or business_customer_id, exactly one)
must already exist; its KYC/KYB status does not gate payment link
generation. The project's Opco must be ACTIVATED and have a Sub-TPP ID on
file.
Response can be 200 or 202. Normally returns 200 with the transaction
in PENDING status and a checkout_url. If the outcome of initiating the
payment was uncertain (for example a network timeout — the payment may
or may not have actually been accepted), returns 202 Accepted
instead, with reconciliation_state: AWAITING_PROVIDER_CONFIRMATION and
checkout_url possibly null. Treat 202 as "submitted, outcome pending",
not as a failure — poll Get Transaction or wait for a status webhook
rather than retrying.
Errors:
- 400:
X-Idempotency-Keyis empty; no callback URL is configured (set
one in the dashboard or passcallback_url) or it isn't HTTPS; the
project's Opco is not ACTIVATED or has no Sub-TPP ID on file - 403: payment links are disabled for this account; the project is frozen
- 404: the user/business customer, project, or its Opco was not found
- 409: idempotency key reused with a different payload, or still
processing; the linkedcontract_request_idalready has an active
payment transaction - 500: payment initiation failed unexpectedly; the transaction is
recorded asFAILED. Retrying with the same idempotency key
returns this same failed transaction again (the payment is not
reattempted) — use a new idempotency key to try again.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
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.createpermission 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): KYCAPPROVED(UrbanPayX KYC mode) or external statusVERIFIED(external attestation mode). - Business (
business_customer_id): KYBAPPROVED(UrbanPayX KYB mode) or external statusVERIFIED(external attestation mode).
Pending, on-hold, rejected, or missing verification is rejected with 403.
Project & operating company preconditions
project_idmust reference a project owned by your client and not frozen by an administrator.- The project's operating company (Opco) must be in
ACTIVATEDstatus and have a valid Sub-TPP ID. Otherwise the request returns400.
Amount & currency
amountmust be greater than0, at least0.01, and use at most 2 decimal places.currencyisEURonly 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_urlholds the provider checkout URL andstatusispending.202— The provider call result is uncertain (timeout or transport error). The transaction is persisted aspendingwithreconciliation_state = awaiting_provider_confirmationand is reconciled later via webhook. Do not retry with a new key — poll the transaction or wait for the webhook.
Error responses
| Status | When |
|---|---|
400 | Empty X-Idempotency-Key; Opco not ACTIVATED; Opco missing a valid Sub-TPP ID |
403 | Payment links disabled for the client; subject verification required / pending / on-hold / rejected; project is frozen |
404 | User, business customer, project, or Opco not found under this client |
409 | Same idempotency key is still being processed, or was reused with a different payload |
422 | Request body failed validation (e.g. both/neither subject id, bad amount, non-EUR currency, non-HTTPS callback) |
500 | Payment initiation failed before the transaction was created |