Reference

Migrate from v1 — quick version

What you need to change to move from API v1 to v2.

Reading time: 2 minutes. For an endpoint-by-endpoint audit, see Migrate from v1 — full reference.

This guide is for integrators already in production on API v1 (https://api.corpxapi.com). New integrations should go straight to v2 and read the quick start guide.

What changes (update in your code)

ItemBefore (v1)After (v2)
API base URLhttps://api.corpxapi.com/v1https://tenant.api.corpx.com/v1
OAuth Token URLold Cognito domainhttps://auth.api.corpx.com/oauth2/token
client_id / client_secretcurrentnew (delivered via secure channel along with the cutover date)
OAuth Scopesapi/fullapi2/read api2/write

What does NOT change

  • All /v1/accounts/{accountId}/... paths (with the 4 caveats below)
  • Your webhook URL and your HMAC secret
  • account_id are still the same UUIDs
  • Webhook payloads and headers
  • BigPix body — still {amount, key, ...} (chunking stays server-side)

5 specific caveats

If your integration depends on any of the items below, read the full reference before the cutover. Otherwise, just switch URL + credentials.

CaveatWhat changed
Statement (GET /v1/accounts/{id}/statement)Same path, but now real-time (no local cache). Latency goes from ~50 ms to ~500 ms–1.5 s, and the derived tariff_ref field is no longer included in rows. Counterparty bank details are reduced to name + document — branch, account, bankCode, bankIspb, pixKey are no longer present in statement rows (the settlement bank does not expose these on its statement endpoint). For the full payload, use GET /v1/accounts/{id}/pix/payments/lookup?endToEndId=... or wait for the outbound webhook (pix.in.completed / pix.out.completed). Details in §4.1 of the reference.
PIX QR-code — flattened responseThe 4 QR endpoints (POST /pix/qr-code/dynamic, POST /pix/qr-code/static, GET /pix/qr-code/lookup, DELETE /pix/qr-code) lost the envelope {statusCode, title, type, message, data: {...}}. Fields are now top-level; data.payload became emv; data.location was removed. Details in §4.9 of the reference.
MED (/v1/accounts/{id}/pix/med/*)Active again, with a different contract: the GET lists what the pix.med.opened / pix.med.updated webhooks recorded (subscribing to both is now part of integrating MED) and does not return dispute status; answer is now result + reason and only records your defense, which travels with the attachments to the analysis team; the evidence routes work again (3-step upload). There is no decision route — refunding or refusing the disputed PIX is not done by this API. Details in §4.2 of the reference.
Webhooks fee.*, edi.* + fee field on transaction objectTemporarily suspended. Fees appear as standalone lines in the statement (type=internal-transfer to CORPX_FEE_ACCOUNT_ID with identifier=fee-{slug}-...).
Deprecated and removed endpoints5 routes still work as deprecated aliases (sunset 2026-11-21) and 9 routes return 404 — see the tables below.

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

They keep responding normally but include Deprecation: true + Sunset: Sat, 21 Nov 2026 00:00:00 GMT + Link: <successor-url>; rel="successor-version" headers. Migrate to the successor on your next maintenance window.

Deprecated route (still works)Canonical replacement
GET /v1/accounts/{id}/pix/payments/{paymentId}GET /v1/accounts/{id}/pix/payments/lookup?identifier=...
GET /v1/accounts/{id}/payments/{paymentId} (alias without /pix/)GET /v1/accounts/{id}/pix/payments/lookup?identifier=...
GET /v1/accounts/{id}/pix/qr-code (without /lookup)GET /v1/accounts/{id}/pix/qr-code/lookup?identifier=...
POST /v1/accounts/{id}/pix/out/qr-code (sync)POST /v1/accounts/{id}/pix/out/qr-code/async
POST /v1/accounts/{id}/pix/out/qrcode (without hyphen)POST /v1/accounts/{id}/pix/out/qr-code/async

Removed endpoints (404 on v2)

If you never called any of these, ignore this section.

v1 route (removed)Replacement
GET /v1/accounts/{id}/pix/qr-codes (paginated list)GET /v1/accounts/{id}/pix/qr-code/lookup?identifier=... (one QR) or GET /v1/accounts/{id}/pix/qr-codes/stats (aggregates)
POST /v1/webhooks/replayStatement polling in a short window
GET /v1/integrator/webhooksGET /v1/webhooks
GET /v1/integrator/webhooks/{id}/deliveriesGET /v1/webhooks/{subscriptionId}/deliveries (+ /{deliveryId} and /{deliveryId}/retry)
POST /v1/integrator/events/replayNo replacement
POST /v1/integrator/events/replay/batchNo replacement
POST /v1/accounts/{id}/pix/med/{medId}/responsePOST .../pix/med/{medId}/answer (new body: result + reason)
POST /v1/accounts/{id}/pix/med/{medId}/sendNo replacement — it never existed on the settlement side
POST /v1/accounts/{id}/pix/med/{medId}/decideNo replacement — CorpX does not decide MEDs; use answer to record your defence

Support

Contact: api@corpx.com — response within 1h on business hours.