Xtopay API v2.0: What Changed and Why

After six months of feedback from our beta cohort, we've shipped a significant update to the Xtopay API. v2.0 breaks with some v1 conventions to establish patterns that will carry us for the next few years without further breaking changes.

v1 will remain supported until December 31, 2026. You can continue using it without any changes. But if you're starting a new integration or want access to new features (real-time usage streaming, credit wallet management, the new storefront API), v2 is the path forward.

What changed

Unified resource IDs

In v1, resource IDs were opaque UUIDs. In v2, they're prefixed strings that encode the resource type: cus_ for customers, txn_ for transactions, sub_ for subscriptions, wh_ for webhooks. This makes debugging significantly easier — you know exactly what type of resource an ID refers to without an extra API call.

Structured error responses

v1 returned errors as { error: 'string message' }. v2 returns a structured error object with a machine-readable code, a human-readable message, and optionally a docs_url pointing to the relevant documentation section.

Cursor-based pagination

v1 used page/limit offset pagination. v2 uses cursor-based pagination: all list endpoints return a next_cursor and prev_cursor. Pass a cursor as a query parameter to fetch the next or previous page. This is more efficient for large datasets and prevents missed records when new items are inserted mid-pagination.

All v2 endpoints use the base URL https://api.xtopay.co/v2. Your existing v1 calls at /v1 will continue to work until end of 2026.

New in v2

• Real-time usage event streaming via SSE at GET /stream/usage
• Credit wallet management: create packages, deduct credits, query balances
• Storefront API: create and manage hosted payment pages programmatically
• Batch operations: submit up to 100 usage events in a single API call
• Idempotency keys: pass Idempotency-Key header on any POST to safely retry

Migration checklist

Most v1 integrations can migrate to v2 in under an hour. The main changes to make are: update the base URL, handle the new ID format in your database if you store them, update error handling to use error.code instead of error.message for programmatic decisions, and update any pagination logic.