Changelog and Versioning

This page documents the UrbanPay API versioning policy, breaking change commitments, and a log of changes.

Current version

The UrbanPay API is currently at v1 (/api/v1/). All endpoints use this version prefix.

Versioning policy

We will not make breaking changes to v1 without advance notice.

A breaking change is any change that could cause a working integration to fail. This includes: removing endpoints, removing or renaming fields in response bodies, changing the type of existing fields, adding new required request parameters, or changing the meaning of existing status codes.

The following are NOT breaking changes and may happen at any time: adding new endpoints, adding new optional fields to request or response bodies, adding new webhook event types, adding new optional query parameters, changing error message text (the HTTP status codes remain stable), and improving validation error detail messages.

How we communicate changes

Non-breaking changes are documented here in the changelog as they are released. No advance notice is required.

Breaking changes (if ever necessary) will be communicated through:

A notice in this changelog at least 30 days before the change
A deprecation header (Deprecation: true) on affected endpoints during the notice period
Email notification to all registered client contacts

Our goal is to evolve the API additively so that breaking changes are never necessary.

Deprecation policy

When an endpoint or field is deprecated:

It continues to work for at least 30 days after the deprecation notice
The response includes a Deprecation: true header and a Sunset header with the removal date
The replacement (if any) is documented in this changelog
After the sunset date, the endpoint may return 410 Gone

No endpoints are currently deprecated.

Changelog

September 2026

API

Added Bulk Payment Links: create up to 500 payment links at once from a CSV/XLSX file or JSON rows, with preview, background batches, per-row results, retry of failed rows and cancellation (/checkout/paylink/bulk). See Bulk Payment Links
Added archiving for projects, contract templates, contract flows and workflows. Archived items are hidden from default lists and cannot be used for new requests; existing requests are untouched (POST .../archive, POST .../unarchive). The list endpoints accept include_archived, and project responses include archived_at
Added DELETE /opcos/{opco_id} to delete an operating company that is still in draft
The payment.status_changed webhook now includes amount (decimal string), currency, contract_request_id, reconciliation_state, status_detail and status_reason. A payment moved into manual review now also emits this event, with reconciliation_state carrying the change. The envelope occurred_at is now the time of the status transition. The event version stays v1
The payer's return URL now always carries transaction_id, including for your own callback_url and for platform-created links (payment schedules, bulk links, workflow payments). An existing transaction_id you set is never replaced. Read the payment status from GET /transactions/{transaction_id}, not from the URL
Contract requests can include view-only CC recipients, returned as cc_recipients on contract request responses
GET /contracts/templates accepts updated_from and include_ad_hoc; GET /contracts/workflows accepts status
KYC/KYB verification detail responses now include warnings (findings from the automated checks that explain an in-review or declined result) and id_verification_status. KYC/KYB status summaries include in_review and by_effective_status
Wallet screening responses now include risk_drivers, wallet_activity, attributed_coverage and entity attribution fields for the screened address (entity_name, entity_type, entity_subtype)
Added free-text search (q) to GET /screening/wallets and GET /monitoring/transactions
POST /recurring-payments/{definition_id}/retry accepts an optional run_id; retrying the same failed run is idempotent

Documentation

Endpoints used only by the dashboard (sign-in, MFA, team management, notifications, support tickets, health checks) are no longer listed in the public API reference. Integrations that use API credentials are not affected
Clarified rate limit headers: a 429 Too Many Requests response includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Successful responses do not carry these headers

August 2026

API

Added Payment Schedules: recurring collection plans with per-period send timing, item-level editing, and skip/insert support (/payment-schedules)
The /llms.txt machine-readable documentation index is live (see MCP Server)

July 2026

API

Added Custom Verification Workflows: build KYC/KYB levels from individual verification modules instead of only catalog levels (/kyc/custom-levels, /kyb/custom-levels)
Added Travel Rule: submit and track cross-border transfer disclosures (/travel-rule/transfers)
Added Transaction Monitoring: submit transactions for ongoing monitoring and manage the monitoring policy (/monitoring/transactions, /monitoring/policy)
Added Wallet Screening (KYT): screen cryptocurrency wallet addresses and request wallet ownership proofs (/screening/wallet, /screening/wallet-ownership/requests)
Added Webhook Destinations: register multiple webhook endpoints per client instead of a single webhook_url, each with its own secret (/webhooks/destinations)
Added Recurring Payments: schedule a payment link to be minted and sent to the payer on a recurring cadence (/recurring-payments)
Added an optional bank-selection checkout flow for eligible clients
Added personal_number and additional identity fields to the KYC verification detail response
Added source-of-funds questionnaire file downloads (/kyc/detail/USER_ID/questionnaire-files/{qfile_id})
Added IP analysis and document address fields to the KYC verification detail response

June 2026

API

Added KYB Verification Detail: extracted company data and check outcomes for business verifications, mirroring the existing KYC detail endpoint (/kyb/detail/{business_id})
Added KYC and KYB resubmission: reopen only the failed steps of an existing verification session instead of starting a new one (/kyc/USER_ID/resubmit, /kyb/{business_customer_id}/resubmit)
Added callback_url support on KYC and KYB verification initiation
Added per-client visibility groups for extended KYC/KYB verification detail fields (decrypted document number, source-of-funds answers, proof-of-address, AML hit details, downloadable documents)
Added Compose and Send Contract: publish a template, build a signing workflow, and send it to signers in a single call (/contracts/send)
Added redirect URLs for completed contract signing sessions
Contract signing workflows can now include business customers and external (non-account) signers, not only registered users

May 2026

API

Added the Workflows engine: build multi-step automations triggered on a schedule or via webhook, with steps for creating OpCos, projects, and users, making HTTP calls, sending notifications and emails, and waiting on external events (/workflows, /workflow-runs, /workflow-triggers)

April 2026

API

Added the ability to cancel an outstanding payment intent before it completes (POST /checkout/intent/{transaction_id}/cancel)

March 2026

Documentation

Added Getting Started guide with 7-step quickstart flow
Added Core Concepts guide (OpCos, Projects, Users, Transactions)
Added Authentication Guide (two auth methods, MFA, security challenges)
Added KYC Verification Guide (both modes, bulk operations)
Added Sandbox and Testing guide (test flows, webhook testing, outcome simulation)
Added Transaction Lifecycle guide (state machine, webhook payloads, handling patterns)
Added Roles and Permissions matrix
Added Error Reference (all HTTP status codes with causes and fixes)
Added Launch Checklist for production readiness
Added Pagination guide
Added this Changelog and Versioning page

API

No API changes in this release. These updates are documentation-only.

Upcoming

Planned improvements (not yet released):

Standardized error response format with machine-readable error codes

These will be documented here when they ship.

Questions

If you have questions about API changes or need guidance on adapting your integration, contact support from the dashboard.