Integration Prompt

--- BEGIN URBANPAYX INTEGRATION PROMPT ---

You are integrating **UrbanPayX** into my application end to end. UrbanPayX is a payments middleware for real estate: one API for Open Banking payments, card processing, escrow accounts, KYC/KYB verification, and contract e-signing across European markets.

**My application**

- Framework / language:
- Frontend / backend surface:
- Database:
- Use case:

**Flows I need — implement ONLY the ones I check:**

- [ ] Payments — collect a payment from a payer
- [ ] KYC — verify an individual
- [ ] KYB — verify a business
- [ ] Contracts — send a document for e-signing
- [ ] Webhooks — receive status updates

**How to get exact details:** for any endpoint's precise request/response schema, query the MCP server at `https://docs.urbanpayx.com/mcp` (tools `list-endpoints`, `get-endpoint`, `search-endpoints`), or read `https://docs.urbanpayx.com/llms.txt` and the OpenAPI spec. Do not guess field names — look them up.

**Step 1 — Authentication (always do this first)**

1. In the dashboard, create an API credential (key + secret).
2. Server-side, exchange them for a short-lived access token: `POST {BASE_URL}/api/v1/auth/api-token` with body `{ "api_key": "...", "api_secret": "..." }` → returns `{ "access_token": "...", "token_type": "bearer" }`.
3. Send `Authorization: Bearer <access_token>` on every other request. Tokens are short-lived — refresh when they expire. Never put the key, secret, or token in client-side code.

**Base URLs**

- API: sandbox `https://api-sandbox.urbanpayx.com`, production `https://api.urbanpayx.com`
- Hosted payment page: sandbox `https://pay-sandbox.urbanpayx.com`, production `https://pay.urbanpayx.com`
- Docs / MCP / machine index (shared across environments): `https://docs.urbanpayx.com`, `https://docs.urbanpayx.com/mcp`, `https://docs.urbanpayx.com/llms.txt`
- Build and test against sandbox first, then switch the base URL to production when you go live.

**Prerequisites — Operating Company and Project** (required before Payments and Contracts)

Payments and contract requests are scoped to a Project, which belongs to an Operating Company (OpCo). Set these up once:
1. Create an OpCo: `POST /api/v1/opcos/create` with `opco_type`, `name`, `domain`, `legal_entity_name`, `company_registration_number`, `merchant_jurisdiction`, `mcc_code`, `merchant_iban`. It starts in `draft`.
2. Submit it for approval: `POST /api/v1/opcos/{opco_id}/submit`, then poll `GET /api/v1/opcos/{opco_id}`. OpCo statuses: `draft`, `pending_superadmin_review`, `awaiting_approval`, `activated`, `rejected`, `deactivated`. A payment link can only be created once the OpCo is `activated`.
3. Create a Project under it: `POST /api/v1/projects/create` with `opco_id` (plus optional `project_name`). Use the returned `project_id` when creating payment links and contracts.

**Payments** (if selected)

1. `POST /api/v1/checkout/paylink` with `amount`, `currency`, `description`, `project_id` (plus optional `user_id`, `business_customer_id`, `contract_request_id`, `callback_url`). Send a unique `X-Idempotency-Key` header to prevent duplicate payments. The response contains the checkout URL.
2. Redirect the payer to the checkout URL returned by the call (it points at the hosted payment page for your environment).
3. Track status via `GET /api/v1/transactions/{transaction_id}` or the `payment.status_changed` webhook. Statuses: `pending`, `processing`, `success`, `failed`, `expired`, `canceled`. Cancel an unpaid intent with `POST /api/v1/checkout/intent/{transaction_id}/cancel`.

**KYC** (if selected)

1. `POST /api/v1/kyc/users` with `email` (plus optional `full_name`, `verification_mode`).
2. `POST /api/v1/kyc/verify` → returns a hosted verification link; send the user there.
3. Track via `GET /api/v1/kyc/status/USER_ID` or the `kyc.status_changed` webhook. Statuses: `none`, `pending`, `approved`, `rejected`, `on_hold`. Read the full result with `GET /api/v1/kyc/detail/USER_ID`.

**KYB** (if selected)

1. `POST /api/v1/kyb/businesses` with `company_name`, `registration_number`, `country` (plus optional `legal_address`, `tax_id`, `contact_email`).
2. `POST /api/v1/kyb/verify` → returns a hosted verification link.
3. Track via `GET /api/v1/kyb/status/{business_id}` (or your verification callback URL). Statuses: `none`, `pending`, `approved`, `rejected`, `on_hold`.

**Contracts** (if selected)

1. Create and publish a template (`POST /api/v1/contracts/templates`, then `POST /api/v1/contracts/templates/{template_version_id}/publish`), or reuse an existing published template version.
2. Send in one step with `POST /api/v1/contracts/send` (compose-and-send): provide the `template_version_id`, the ordered `signers` (each with a `role` and who fills it — an end user, a business, or an external email), and optionally a `payment_gate` to hold signing until a transaction succeeds.
3. Track via `GET /api/v1/contracts/requests/{request_id}` or the `contract.request.status_changed`, `contract.request.completed`, and `contract.participant.status_changed` webhooks. Request statuses: `created`, `awaiting_signature`, `awaiting_transaction`, `completed`, `declined`, `canceled`, `expired`. Download the signed PDF at `GET /api/v1/contracts/requests/{request_id}/document`.

**Webhooks** (if selected)

1. `PUT /api/v1/webhooks/subscription` with `webhook_url` (an HTTPS endpoint), `webhook_enabled: true`, and `webhook_events` (the event types you want).
2. Verify every delivery: each request carries an `X-UPX-Signature: sha256=<hex>` header. Compute an HMAC-SHA256 of the raw request body with your webhook secret and compare it in constant time. Reject on mismatch.
3. Be idempotent — dedupe on the event id; the same event may be delivered more than once.
4. Events include `payment.status_changed`, `kyc.status_changed`, `contract.request.status_changed`, `contract.request.completed`, `contract.participant.status_changed`. List them live with `GET /api/v1/webhooks/events`, send a test with `POST /api/v1/webhooks/subscription/test`, and rotate the secret with `POST /api/v1/webhooks/subscription/rotate-secret`.

**Checklist before you ship**

- [ ] Access token obtained server-side; key/secret/token never reach the browser.
- [ ] `X-Idempotency-Key` set on payment creation.
- [ ] Webhook endpoint verifies `X-UPX-Signature` and is idempotent on the event id.
- [ ] Status handling covers every status value for the flows you use.
- [ ] Verified end-to-end in sandbox before requesting production access.

--- END URBANPAYX INTEGRATION PROMPT ---