Changelog

v2 is a full rewrite of the platform on faster, more predictable infrastructure, with direct integration to the new settlement bank. Mostly backward compatible with v1.

Auth

• New base URL: https://tenant.api.corpx.com/v1 (was https://api.corpxapi.com/v1)
• New Token URL: https://auth.api.corpx.com/oauth2/token
• New client_id + client_secret per integrator (delivered via secure channel)
• Scopes: api/full → api2/read api2/write
• Idempotency-Key is now optional (auto-generated if missing)
• X-Tenant-Id is required on all /v1/* requests (except GET /v1/me and health); must match the account tenant when accountId is in the path

Statement consolidated into a single endpoint

• GET /v1/accounts/{accountId}/statement is now always live — queries the settlement bank in real time (no local cache).
• Derived endpoints that used to read from the same cache (/pix/transactions, /pix/payments, /payments alias) are also live now.
• The previous v1 API and backoffice remain online in read-only mode for 30 days after cutover for historical lookup.
• /transactions/real-statement, /transactions/legacy-statement and /payments/{id}/legacy do not exist on v2 — use /statement (current data) or the v1 read-only API (history).

Deprecated endpoints (still work until 2026-11-21)

4 paths that existed on v1 and weren’t kept in the canonical v2 shape come back as deprecated aliases. They keep responding normally, but attach 3 warning headers to the response:

Deprecation: true
Sunset: Sat, 21 Nov 2026 00:00:00 GMT
Link: </v1/accounts/.../new-path>; rel="successor-version"

These headers follow RFC 8594 (Deprecation) and RFC 9745 (Sunset). Planned sunset: 2026-11-21 — after that date they start returning 410 Gone. They no longer appear in the OpenAPI or the Postman collection.

• GET /v1/accounts/{id}/pix/payments/{paymentId} → use /pix/payments/lookup?identifier=
• GET /v1/accounts/{id}/payments/{paymentId} (alias without /pix/) → use /pix/payments/lookup?identifier=
• GET /v1/accounts/{id}/pix/qr-code (no /lookup) → use /pix/qr-code/lookup?identifier=
• POST /v1/accounts/{id}/pix/out/qrcode (no hyphen) → use /pix/out/qr-code

Removed endpoints (return 404 on v2)

• GET /v1/accounts/{id}/pix/qr-codes (paginated list) → look one QR up at a time with /pix/qr-code/lookup?identifier=, or use /pix/qr-codes/stats for aggregates
• POST /v1/webhooks/replay → no replacement
• GET /v1/integrator/webhooks → use GET /v1/webhooks
• GET /v1/integrator/webhooks/{id}/deliveries → no replacement (it got one since: GET /v1/webhooks/{subscriptionId}/deliveries, with detail and individual retry)
• POST /v1/integrator/events/replay + /batch → no replacement
• POST .../pix/med/{medId}/send + /response → use /decide + /answer

GET /v1/health still exists on v2 (and now has an additional GET /health alias for external health checks).

New endpoints

• GET /v1/me (debug for the authenticated client_id)
• GET /v1/transactions/{id}/timeline (no accountId in the path)
• GET /v1/accounts/{id}/pix/out/bigpix/{batchId} (aggregated BigPix batch status)
• GET /health (alias for /v1/health without the prefix)
• Boleto family (POST .../boleto/preview|pay, GET .../boleto/payments/{id}) — was 503 on v1, now active

Behavior changes (same path, new shape or semantics)

• Statement and derived endpoints: cache → live; no derived tariff_ref; X-Source: live header; max window per query 31 days.
• Internal transfer by-bank-account: accepts optional holderDocument + holderName (non-breaking).
• Locked balance unlock: v2 only validates lockId; extra fields are ignored (non-breaking).
• fee field on the transaction object removed temporarily — manual reconciliation via identifier=fee-{slug}-{operationReferenceId} in the statement. Returns with no payload change in a future release.

MED and webhooks temporarily suspended

• /v1/accounts/{id}/pix/med/* endpoints return HTTP 503 during the migration. Open disputes follow BACEN’s natural lifecycle — only the API integration is paused.
• Suspended webhooks: fee.*, pix.med.*, edi.*. Subscriptions to these events can stay active — once they’re back they resume automatically. Fees still show up in the statement as separate lines (with identifier=fee-{slug}-{ref}).

Compat (no change to your code)

• BigPix (POST .../pix/out/bigpix and .../bank-account/bigpix): body stays single ({amount, key, ...}); chunking remains server-side, same as v1.
• PIX out variants (/pix/out/async, /bank-account/async, /bank-account/bigpix): preserved.
• /v1/accounts/{accountId}/transfers/internal (all 3 modes): path and body preserved.
• /v1/accounts/{id}/pix/qr-code/static body: value stays as on v1.
• /v1/accounts/{id}/pix/out/qr-code/decode: path preserved.
• /v1/accounts/{id}/pix/keys (GET + POST + DELETE): kept.
• /v1/accounts/{id}/pix/key/{pixKey} (DICT lookup): kept.

Support

Contact: api@corpx.com during the tenant cutover — reply within 1h in business hours.