Payment Initiation

The Payment Initiation API generates checkout payment links that redirect end users to complete bank-based payments. UrbanpayX validates the transaction details, creates a pending transaction record, and calls the API to produce a secure checkout link. All endpoints use the /api/v1/checkout base path.

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/checkout/paylink`	Generate a checkout payment link for a new transaction

Payment Flow

Generate link — Call POST /paylink with the transaction amount, currency, user ID, and project ID. UrbanpayX creates a transaction in pending status and returns a checkout URL.
Redirect user — Direct the end user to the returned checkout URL. The user selects their bank and authorizes the payment.
Payment processing — Processes the bank payment. The transaction status moves from pending to processing.
Completion — Once the bank confirms the payment, the status updates to success or failed. The user is redirected to the project's configured payment_return_url.
Webhook notification — UrbanpayX sends a payment.status_changed webhook event for each status transition.

Related APIs

API	Usage
Transactions	Query transaction status via `GET /api/v1/transactions/{transaction_id}` or force a status refresh via `POST /refresh-status`
KYC Verification	Users must pass KYC verification before initiating a payment
Projects	Each payment link is scoped to a project, which defines the callback URL and associated operation company

Prerequisites

Before generating a payment link, ensure:

Your callback URL is configured — PUT /auth/client/settings
Your OpCo is activated — the project's OpCo must have status: activated
The user exists and is verified — kyc_status: approved (UrbanPayX KYC) or external_verification_status: verified (external attestation)
Payment link generation is enabled for your client

Required roles

OWNER or OPERATIONS — DEVELOPER role cannot generate payment links. API key tokens (which default to OPERATIONS) can generate payment links. See Roles and Permissions.

Related guides

Core Concepts — How OpCos, Projects, Users, and Transactions connect
Transaction Lifecycle — What happens after the payment link is generated
KYC Verification Guide — Verify users before creating payments
Error Reference — Common payment errors and fixes
Sandbox and Testing — Test the full payment flow