Skip to main content

Migrate from v1 — quick version

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/* + med.* webhooks)Temporarily returning 503 during the migration.
Webhooks fee.*, med.*, 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 endpoints4 routes still work as deprecated aliases (sunset 2026-11-21) and 7 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/qrcode (without hyphen)POST /v1/accounts/{id}/pix/out/qr-code

Removed endpoints (404 on v2)​

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

v1 route (removed)Replacement
POST /v1/webhooks/replayStatement polling in a short window
GET /v1/integrator/webhooksGET /v1/webhooks
GET /v1/integrator/webhooks/{id}/deliveriesNo replacement
POST /v1/integrator/events/replayNo replacement
POST /v1/integrator/events/replay/batchNo replacement
POST /v1/accounts/{id}/pix/med/{medId}/sendPOST .../pix/med/{medId}/decide (but MED is at 503 today)
POST /v1/accounts/{id}/pix/med/{medId}/responsePOST .../pix/med/{medId}/answer (but MED is at 503 today)

Support​

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