Skip to main content

Changelog

This document records all notable changes to the CorpX API.

v2.0.0 (2026-05-03) - New CorpX platform​

The CorpX API has been reimplemented from the ground up on a faster and more predictable platform. No changes are required on your side: paths, HTTP methods, request payloads and response shapes remain the same.

What you actually get​

  • Top-tier performance: synchronous PIX out (POST /v1/accounts/{id}/pix/out) typically responds in a few seconds and settles in real time. Median latency is significantly lower than the previous stack.
  • Higher conversion rate: fewer transient rejections — we transparently retry momentary network degradations before surfacing an error to you.
  • Faster callbacks: we reconcile status directly with the network in parallel with partner webhooks, so your pix.out.*, pix.refund.* and qrcode.paid webhooks arrive with sub-second latency after final confirmation.
  • Consistent status: every payment has a single final outcome (COMPLETED, FAILED or TIMEOUT) — no flapping between states and no payments stuck in PENDING for hours.
  • Stronger idempotency: replaying the same Idempotency-Key on /pix/out always returns the same paymentId, with guaranteed no-duplication even under aggressive network failures.
  • Faster reads on list endpoints (/statement, /payments, /qr-codes).

Compatibility​

  • Same HTTP paths and methods.
  • Same JSON keys (camelCase) and same date formats (RFC 3339 UTC).
  • Same error envelope ({ errorCode, message }).
  • Same webhooks (pix.in.completed, pix.out.completed, pix.out.failed, qrcode.paid, pix.refund.completed, pix.refund.failed) with the same HMAC-SHA256 signature.

Optional warnings field​

Some responses may now include an optional warnings array indicating partial failures that do not block the operation (graceful degradation). When omitted, behaviour is unchanged.

Cutover​

Per-tenant migration with zero downtime. If you are reading this, your tenant is already on the new platform. api.corpxapi.com keeps serving during the transition window.

v1.30.3 (2026-04-30) - Duplicate webhooks removed (pix.refund.completed, pix.out.failed, qrcode.paid)​

Fixes​

  • Duplicate webhooks eliminated: in some scenarios the platform emitted two webhooks for the same event — one following the documented format and a second one with a legacy format that was never described in the documentation. The behavior is now corrected: each event generates exactly one notification, always in the documented format.

    Events affected:

    • pix.refund.completed (sent when a PIX refund completes)
    • pix.out.failed (sent when an outbound PIX fails)
    • qrcode.paid (sent when a QR code is paid)

    The legacy format was never present in docs/webhooks — it was a parallel emission from an internal routine that escaped the documentation. Integrations that relied only on documented fields will not notice any difference besides the absence of the duplicate notification.

  • data.status field in pix.refund.completed now always returns SUCCESS, aligned with the official status vocabulary. Previously, in some cases it leaked REFUNDED (the status of the original PIX transaction).

Fields and formats that disappear (only for integrations coupled to the undocumented legacy format)​

Legacy field / formatReplaced by (documented format)
id: refund_completed_{paymentId}_{ts}id as a sha256-hash string
id: pix_out_failed_{paymentId}_{ts}id as a sha256-hash string
id: qr_paid_{txid}_{ts}id as a sha256-hash string
data.status: COMPLETED (on pix.refund.completed)data.status: SUCCESS
data.status: REFUNDED (on pix.refund.completed)data.status: SUCCESS
data.refundId (on pix.refund.completed)use data.transactionId (already documented)
data.failedAt (on pix.out.failed)use occurredAt from the envelope
data.paymentId (on pix.out.failed)use data.transactionId (already documented)
payer.account / payee.accountpayer.accountNumber / payee.accountNumber

If your integration consumed any of these legacy-only fields, update it to use the documented fields before adopting this version.

Always deduplicate webhooks on your side using a strong key from the payload:

  • For pix.refund.completed: data.refundEndToEnd (BACEN D-code, globally unique).
  • For pix.out.failed: data.endToEnd (BACEN E-code) or data.identifier.
  • For qrcode.paid: data.endToEnd or data.qrcodeId.

These fields are unique per transaction and present on every event.

v1.30.2 (2026-04-30) - Webhook timestamps standardized to UTC​

Fixes​

  • Date fields inside data are now always in UTC with the Z suffix across every webhook. Previously some fields (receivedAt, completedAt, initiatedAt, chargedAt, openedAt) were forwarded without a timezone indicator, which led strict ISO 8601 parsers to interpret them as the consumer's local time — producing up to 3-hour drifts on BRT machines.
  • Standard consolidated and documented at Webhooks → Date and time format.
  • Documentation already showed Z (UTC) in all examples; now every emitted payload matches the standard.

v1.30.1 (2026-04-29) - qrcode.paid webhook kept (not deprecated)​

Deprecation reverted​

  • qrcode.paid remains officially supported. The deprecation notices that appeared in the Webhooks Guide (in PT, EN and ZH) were removed. The event is still valid and stable; no migration is required.
  • The equivalent event pix.in.completed with method: QR_CODE_DYNAMIC or QR_CODE_STATIC remains available as an alternative (and continues to be dispatched in parallel) — pick whichever best fits your integration.

v1.30.0 (2026-04-23) - Internal transfers: error mapping + identifier in webhook​

Fixes​

  • Banking partner account_disabled (TX00012) error mapping: when the source account is disabled at the banking partner, the API now returns HTTP 422 with errorCode: partner_account_disabled. Previously this case was mapped to HTTP 502 (Bad Gateway), misleading integrators into treating it as infrastructure failure rather than a business rule. The change applies to all three internal transfer endpoints (/transfers/internal, /transfers/internal/by-document, /transfers/internal/by-bank-account).
  • Unified banking partner error classification: HTTP errors from the core banking service (used for internal transfers and account lookups) now go through the same classifier already used by the other endpoints. Specific codes such as insufficient_balance, daily_limit_exceeded, account_disabled now return 422 instead of 502.

Improvements​

  • identifier and description now returned in the transfer.internal.out webhook: the integrator-supplied identifier and description from the original POST /transfers/internal* request are now propagated to the webhook sent to the payer account, allowing reconciliation without consulting the statement.
  • Custom payer description replaces the default Transferência Interna text in the statement (GET /statement) when provided in the request.
  • coreId now included in every ledger-entry webhook: the UUID of the banking partner's core ledger line (same value returned in the statement's coreId field) is now propagated in pix.in.completed, pix.out.completed, pix.out.failed, pix.refund.*, qrcode.paid, transfer.internal.*, fee.charged and fee.refunded. Allows reconciliation across webhook ↔ statement ↔ partner exports through a single stable key.
  • Standardized status across every ledger-entry webhook: data.status is now guaranteed on all PIX, QR, internal transfer, refund and fee events. Standardized vocabulary: SUCCESS (operation completed), FAILED (operation failed, with data.error), REVERSED (previously completed entry was reversed). MED events (pix.med.*) keep their own vocabulary (OPEN, PENDING_DECISION, ACCEPTED, REJECTED, CANCELED). Full table in docs/webhooks.

New errorCode values​

CodeHTTPMeaning
partner_account_disabled422The source account is disabled at the banking partner (reactivation required)

v1.29.0 (2026-04-18) - Lookup internal transfer recipient by document​

New Features​

  • Recipient preview for internal transfers: New endpoint GET /v1/accounts/{accountId}/transfers/internal/lookup/{document} lets you preview the holder name before executing an internal transfer by CPF/CNPJ. Useful for showing a confirmation step to the end user.
  • The name is returned with a privacy mask: the first name is kept in full; remaining surnames are reduced to their first letter followed by ***. Connectors like "de", "da", "dos" are preserved.
    • Example: "JOAO DA SILVA PEREIRA" → "JOAO da S*** P***"
  • The endpoint also returns the accountStatus at the banking partner.
  1. User enters the recipient's CPF/CNPJ
  2. Integrator calls GET /transfers/internal/lookup/{document} and shows maskedName for confirmation
  3. User confirms
  4. Integrator calls POST /transfers/internal/by-document to execute the transfer

v1.28.0 (2026-04-17) - Deprecated webhooks removed​

Breaking Changes​

  • payment.sent and payment.refunded webhooks disabled: These events were deprecated in v1.15.0 (2026-02-20) and have now been permanently disabled.
    • payment.sent → use pix.out.completed (includes method field and payment object)
    • payment.refunded → use pix.refund.completed (includes originalEndToEnd, refundEndToEnd and party details)
  • If your integration still subscribes to these events, migrate immediately to the replacements listed above.

v1.27.0 (2026-04-14) - PIX Out by bank account​

New Features​

  • PIX Out by bank account: New endpoints to send PIX transfers using the recipient's bank details (ISPB, branch, account number) instead of a PIX key:
    • POST /v1/accounts/{accountId}/pix/out/bank-account — Synchronous transfer by bank account.
    • POST /v1/accounts/{accountId}/pix/out/bank-account/async — Asynchronous (queued) transfer.
    • POST /v1/accounts/{accountId}/pix/out/bank-account/bigpix — Large transfer with automatic chunking.
  • Required fields: bankIspb (bank ISPB code), accountNumber, accountBranch, documentNumber (recipient CPF/CNPJ), and name.
  • The accountType field accepts CHECKING_ACCOUNT, SAVINGS_ACCOUNT, or PAYMENT (default: CHECKING_ACCOUNT).

Notes​

  • Webhooks, fees, and reconciliation are the same as PIX Out by key — transactions appear as PIX_OUT in the statement.
  • The async endpoint uses the same FIFO queue as PIX Out by key — same ordering and idempotency guarantees.
  • BigPix works the same: splits into R$ 15,000 chunks (configurable via policy), fee charged once per operation.

v1.26.1 (2026-04-13) - Stability fixes​

Bug Fixes​

  • Static QR Code: Fixed an issue where the amount encoded in the static QR code could differ from the requested value in some scenarios.
  • Webhook pix.in.completed: Fixed a scenario where the identifier field was missing from the webhook payload for QR code payments, even when the identifier was available.

v1.26.0 (2026-04-09) - Boleto payment​

New Features​

  • Boleto payment: New endpoints to look up and pay bank slips, utility bills, and taxes:
    • POST /v1/accounts/{accountId}/boleto/preview — Look up boleto data by barcode or "linha digitável". Returns beneficiary, bank, original amount, interest, fine, discount, and total updated amount.
    • POST /v1/accounts/{accountId}/boleto/pay — Submit boleto payment. Returns paymentId with status PROCESSING.
    • GET /v1/accounts/{accountId}/boleto/payments/{paymentId} — Check boleto payment status. Status progresses from PROCESSING to COMPLETED or FAILED.
  • New transaction type BOLETO_PAYMENT: Boleto payments appear in the statement as outgoing transactions (direction: OUT, transactionType: BOLETO_PAYMENT).
  • Feature flag boleto_payment: The functionality is controlled by a feature flag in tenant_configs. Must be enabled by admin for each tenant that wants to use it.

Notes​

  • Bank slips (47 digits), utility bills (48 digits), and taxes are automatically classified by type (boleto, utility, tax).
  • Payment is asynchronous — after POST /boleto/pay, the integrator should poll GET /boleto/payments/{paymentId} to track status.
  • Boleto cancellation and scheduled payments will be implemented in a future version.

v1.25.1 (2026-04-02) - Origin transaction reference in fee.charged and refund improvements​

Improvements​

  • Enriched fee.charged webhook: The payload now includes originTransactionType (type of the transaction that triggered the fee, e.g. PIX_IN, PIX_OUT) and originTransactionRef (E2E ID of the original transaction). Also includes the full description with calculation details.
  • pix.in.completed webhook with identifier for dynamic QR codes: Fixed a scenario where the QR code identifier was not included in the webhook when the payment confirmation arrived before the charge notification.
  • More resilient refunds: Fixed a scenario where the refund was successfully processed by the banking partner but the API returned a temporary error. The API now detects the confirmation via webhook and returns the D-code correctly.

v1.25.0 (2026-03-26) - payerDescription field, fee webhooks, and refund fixes​

New Features​

  • payerDescription field in statement and webhooks: The GET /v1/accounts/{accountId}/statement endpoint and the pix.in.completed, pix.out.completed, qrcode.paid, and transfer.internal.* webhooks now return an optional payerDescription field. It contains the message the payer typed when sending the PIX (when available). The description field continues with the standardized descriptive format ("PIX Received - Payer Name").
  • fee.charged and fee.refunded webhooks: Banking fees now generate fee.charged (when charged) and fee.refunded (when reversed) webhooks. To receive them, add these event types to your webhook subscription.

Improvements​

  • Richer PIX IN webhooks: pix.in.completed webhooks now always contain complete data: reconciliationId, payerDescription, payer details, and PIX key info. Previously, in some scenarios the webhook could arrive with partial data.

Bug Fixes​

  • Refund webhooks (PIX refund): Fixed a scenario where the pix.refund.completed webhook was not delivered to the integrator when the refund confirmation arrived shortly after creation.
  • PIX webhooks for internal transfers (CORPX-CORPX): Fixed the event type for transfers between CORPX accounts. Previously, the recipient could receive pix.out.completed instead of pix.in.completed.
  • reconciliationId in static QR codes: Fixed a scenario where reconciliationId was not included in the pix.in.completed webhook for static QR code payments.
  • Statement status filter: Fixed the status filter on the statement endpoint that in some scenarios did not return results correctly.

v1.24.1 (2026-03-18) - Error semantics improvements (generic 502 reduction)​

Improvements​

  • We standardized partner-originated errors to semantic HTTP statuses across pix/keys, pix/key/{pixKey} (DICT), pix/limits, pix/out/qr-code, pix/out/qr-code/decode, pix/med, transfers/internal, accreditations, and accounts/{accountId}/balance.
  • Error payload format remains stable: { "errorCode": "...", "message": "..." }.
  • OpenAPI and Postman were updated to reflect the new error formats/statuses.

Changed error mapping (from -> to)​

Error / scenarioBeforeNow
Sync Pix Out timeout (POST /pix/out)504 Gateway Timeout207 Multi-Status (partner_timeout)
pix_key_not_found in sync Pix Out (POST /pix/out)502 Bad Gateway422 Unprocessable Entity
Generic partner_error for business/validation failures (PIX/Transfers/MED/Accreditations)502 Bad Gateway422 Unprocessable Entity
pix_key_lookup_failed (classified DICT/partner failure)502 Bad Gateway422 Unprocessable Entity
partner_auth_failed / partner_signature_rejected502 Bad Gateway503 Service Unavailable
partner_internal_error / partner_recipient_unavailable502 Bad Gateway503 Service Unavailable
partner_timeout (upstream timeout endpoints)502 Bad Gateway504 Gateway Timeout
account_not_found from partner-integrated flows502 Bad Gateway404 Not Found
pix_key_not_found in DICT lookup (GET /pix/key/{pixKey})502 Bad Gateway404 Not Found
Unclassified fallback502 Bad Gateway502 Bad Gateway (kept as fallback)

v1.24.0 (2026-03-18) - Sync Pix Out: per-account rate limit and timeout 207​

Breaking Changes​

  • Sync Pix Out timeout status changed: POST /v1/accounts/{accountId}/pix/out now returns HTTP 207 (partner_timeout) on partner timeout, instead of HTTP 504.
  • Expected handling remains the same: the transfer may have been executed, so check statement/payment status before retrying.

Improvements​

  • Per-account rate limit for sync Pix Out: a per-account limit is now enforced (current default 100 req/min, customizable by policy).
  • Next days: the default for synchronous requests will be adjusted to 10 req/min.
  • When exceeded, API returns 429 rate_limit_exceeded with contextual fields (currentRateLimit, scope) and guidance to use async flow.
  • New async cashout endpoint: POST /v1/accounts/{accountId}/pix/out/async schedules payment processing and returns immediate 202 with a paymentId for tracking.
  • BigPix is now async-only: POST /v1/accounts/{accountId}/pix/out/bigpix now schedules processing through the async flow (same behavior as /async) and no longer executes synchronously.

v1.23.0 (2026-03-17) - PIX QR Code Decode​

New features​

  • PIX QR Code decode/consult: New endpoint POST /v1/accounts/{accountId}/pix/out/qr-code/decode decodes a PIX QR Code EMV string and returns the beneficiary details without executing payment. Returns: name, document, amount, PIX key, bank and account type of the recipient. Useful for displaying a confirmation screen to the user before paying.

v1.22.0 (2026-03-07) - Internal transfer by document and by bank account​

New features​

  • Internal transfer by document (CPF/CNPJ): New endpoint POST /v1/accounts/{accountId}/transfers/internal/by-document allows creating internal transfers by identifying the destination account via the holder's CPF or CNPJ. Works for any account in the banking ecosystem, not just accounts registered in the API. Required fields: document, value, description.

  • Internal transfer by bank account: New endpoint POST /v1/accounts/{accountId}/transfers/internal/by-bank-account allows creating internal transfers by identifying the destination account via branch and account number (branch + accountNumber). Only works for accounts registered in the API (same tenant). To transfer to external accounts, use the /by-document endpoint.

v1.20.0 (2026-03-01) - Account ownership validation​

Improvements​

  • Strengthened account ownership validation: The API now verifies that the accountId in the request belongs to the authenticated tenant. Integrators accessing only their own accounts are not affected. This improvement enhances security against unauthorized cross-account access.

v1.19.1 (2026-02-26) - BigPix improvement​

Improvements​

  • BigPix (POST /v1/accounts/{accountId}/pix/out/bigpix): improved chunk processing robustness for better consistency under high-volume scenarios.

v1.19.0 (2026-02-26) - Transaction timeline​

New features​

  • Transaction timeline: New endpoint GET /v1/accounts/{accountId}/transactions/timeline returns the timeline of events for a single transaction (by endToEndId or identifier). Includes: BACEN confirmations (short summary text), webhooks sent to the client (with full payload for "View full payload"), fees, refunds, and QR Code lifecycle when applicable. Exactly one query parameter is required: endToEndId or identifier. No changes to existing endpoints or response formats.

v1.18.0 (2026-02-24) - Performance optimizations and independent fee transactions​

Improvements​

  • Fees as independent transactions: Fees charged by the API now appear as separate lines in the statement, linked to the original transaction. QR Code and payment lookups now include fee details (fees, totalFees).
  • Performance optimizations: Parallel batch processing for reconciliation, support for higher transaction volumes.
  • Automatic fee retry: The self-healing process now includes retry of fees that failed on initial charge.

Bug Fixes​

  • Fixed MED dispute rate calculation that was double-counting transactions and disputes.
  • Fixed fee charging that could silently fail under high concurrency.

v1.17.0 (2026-02-22) - Automatic reconciliation and transaction status fix​

Improvements​

  • Automatic reconciliation (Self-Healing): Expired QR Codes are now automatically marked as expired. Paid QR Codes and pending payments are periodically reconciled with the statement, ensuring consistency even during transient communication failures.
  • Transaction status fix: PIX transactions that have reached a terminal status (SUCCESS, FAILED, REVERSED) can no longer be overwritten by delayed webhooks, eliminating rare cases where a completed transaction could temporarily appear as pending.

v1.16.2 (2026-02-21) - Enriched QR Code and Payment lookups​

Improvements​

  • QR Code lookup (GET /v1/accounts/{accountId}/pix/qr-code/lookup) and Payment lookup (GET /v1/accounts/{accountId}/pix/payments/lookup, GET /v1/accounts/{accountId}/pix/payments/{paymentId}) now return an enriched transaction object when the transaction is reconciled.
  • The transaction object includes: detailed status, full payer/payee info, balance after transaction, fee details, dispute (MED) info, policy violations, refund references, and error reason (when applicable).

v1.16.1 (2026-02-21) - Partner response fixes​

Bug Fixes​

  • Fixed HTTP 502 error when deleting a PIX key (DELETE /v1/accounts/{accountId}/pix/keys/{pixKey}). The operation completed successfully, but the API incorrectly returned an error response.
  • Fixed HTTP 502 error when requesting a refund (POST /v1/accounts/{accountId}/pix/refund). The refund was processed successfully, but the API incorrectly returned an error response.
  • General improvements to partner response handling for all PIX operations.

v1.16.0 (2026-02-20) - Lookup Endpoints and Payment Pagination​

New Features​

  • New GET /v1/accounts/{accountId}/pix/qr-code/lookup for QR Code search by ?identifier=X, ?qrcodeId=X, or ?endToEndId=X.
  • New GET /v1/accounts/{accountId}/pix/payments/lookup for Payment search by ?paymentId=X, ?identifier=X, or ?endToEndId=X.
  • Only one parameter allowed at a time.

Payment List Pagination​

  • GET /v1/accounts/{accountId}/payments now supports ?page=0&size=50.
  • Response includes: totalElements, totalPages, page, size, hasNext, hasPrevious.

QR Code List Pagination​

  • GET /v1/accounts/{accountId}/pix/qr-codes now supports ?page=0&size=50&status=PAID.
  • Response includes: totalElements, totalPages, page, size, hasNext, hasPrevious.

Route Standardization​

  • New alias POST /v1/accounts/{accountId}/pix/out/qr-code (hyphenated, recommended).

Deprecated​

  • GET /v1/accounts/{accountId}/payments → use /v1/accounts/{accountId}/pix/payments
  • GET /v1/accounts/{accountId}/payments/{paymentId} → use /v1/accounts/{accountId}/pix/payments/{paymentId}
  • POST /v1/accounts/{accountId}/pix/out/qrcode (no hyphen) → use /pix/out/qr-code
  • Old routes still work but will be removed in a future version.

v1.15.0 (2026-02-20) - Webhook method field and refund reconciliation​

New Features​

method field in PIX webhooks​

  • pix.in.completed, pix.out.completed and pix.out.failed webhooks now include a method field indicating how the transfer was made.
  • PIX IN: PIX_KEY, QR_CODE_STATIC, QR_CODE_DYNAMIC, REFUND_RECEIVED
  • PIX OUT: PAYMENT, REFUND_PIX_KEY, REFUND_QR_STATIC, REFUND_QR_DYNAMIC

Contextual objects in webhooks​

  • PIX IN via QR Code includes qrCode object with txid, identifier, type, value.
  • PIX OUT via API includes payment object with paymentId, identifier, reconciled.

Refund reconciliation with QR Codes​

  • Refunds of PIX received via QR Code now update the QR Code record with refund details.
  • QR Code query endpoint returns full refund history in refunds[].

Deprecated​

  • qrcode.paid: use pix.in.completed with method: QR_CODE_* instead.
  • payment.sent: use pix.out.completed with method: PAYMENT instead.
  • payment.refunded: use pix.out.completed with method: REFUND_* instead.

v1.14.0 (2026-01-16) - BigPix: High-value transfers​

New Features​

BigPix Endpoint (POST /v1/accounts/{accountId}/pix/out/bigpix)​

  • New endpoint for PIX transfers above the individual limit (R$15,000 by default).
  • Automatically splits the amount into multiple smaller transfers, executed in parallel.
  • Each chunk includes identification in the format PIX X/Y - Total R$... - message [id].
  • If identifier is provided, each chunk receives identifier__X/Y.
  • Consolidated response with status FULL (all ok), PARTIAL (some failed) or FAILED (none executed).
  • Includes retry count per chunk and individual details (E2E ID, status, error).
  • Chunk size configurable per tenant via pixOut.chunkSize policy.

v1.13.2 (2026-01-16) - Webhook delivery improvements​

Improvements​

  • New webhook subscriptions now have redundant headers removed before delivery to the recipient.

v1.13.1 (2026-02-19) - Remove qrCodeFormat and Payment Approval Flow​

Breaking Changes​

qrCodeFormat field removed from QR Code endpoints​

  • The qrCodeFormat field has been removed from dynamic and static QR Code creation endpoints.
  • The API now always returns QR Codes in EMV format (copy-and-paste). IMAGE format is no longer supported.
  • Requests that still send qrCodeFormat will not receive an error, but the field will be ignored.

New Features​

Payment Approval Flow​

  • When the requireApprovalAbove policy is configured, PIX Out payments above the threshold now create a payment intent with status PENDING_APPROVAL.
  • Administrators can approve or reject pending payments from the admin panel.
  • On approval, the payment is automatically executed. On rejection, the reason is recorded.

v1.13.0 (2026-02-18) - Disputes (MED), Policy Enforcement and Contestation​

New Features​

Dispute Management (MED)​

  • New MED dispute management system with automatic reconciliation of MEDs with transactions via E2E ID.
  • MED data (status, deadline, claimant, reason) now appears linked to the transaction in the statement.
  • MED rate monitoring: daily statistics of MED/PIX-In ratio per tenant.
  • New endpoints:
    • GET /v1/backoffice/tenants/{tenantId}/med-stats - Daily MED statistics.
    • POST /v1/accounts/{accountId}/pix/med/{medId}/answer - MED contestation with response and evidence.
    • POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/upload-url - Evidence file upload.

PIX In Policy Enforcement​

  • PIX In rules are now enforced in real-time (previously only logged violations).
  • AUTO_REFUND action now initiates automatic refund of the violating transaction.
  • Policy violations appear in the statement with rule details, action, and message.

New Policy Rules​

  • PIX In: Bank code blacklist, same ownership restriction.
  • PIX Out: Whitelist is now evaluated before blacklist (whitelist overrides all other rules).
  • MED: Auto-block balance for MEDs above a threshold, MED/PIX-In rate limit with configurable actions.

Improvements​

  • Documentation: new Policies and Rules guide with all rules and evaluation order.
  • Documentation: new Disputes (MED) guide with lifecycle, contestation, and monitoring.

v1.12.1 (2026-02-18) - Required Refund Reason and Pagination Fix​

New Features​

  • New endpoint GET /v1/accounts/{accountId}/pix/key/{pixKey} for DICT key lookup with 24h cache and configurable rate limiting.

Breaking Changes​

reason field now required on refund endpoint​

  • The POST /v1/accounts/{accountId}/pix/out/refund endpoint now requires the reason field with one of: USER_REQUESTED, FRAUD, BANK_ERROR, CASHIER_ERROR, CUSTOMER_REQUEST.
  • Requests without reason or with invalid values will return HTTP 400.

Improvements​

  • X-API-Version header included in all API responses for version debugging.

Fixes​

  • Fixed: statement pagination returned blank pages after page 10 (more than 1000 transactions).

v1.12.0 (2026-02-18) - Policy Engine​

New Features​

Policy Engine​

  • New configurable policy system per tenant and per account, with hierarchy (default -> tenant -> account).
  • Available rules:
    • PIX Out: per-transaction limits, night limits, allowed person types (PF/PJ), CPF/CNPJ whitelist/blacklist, operating hours.
    • PIX In: amount limits, auto-quarantine, configurable violation actions.
    • QR Code: type-specific permissions (dynamic/static), amount limits.
    • PIX Keys: max keys per account.
    • Refund: enable/disable and amount limits.
    • Operating Hours: time window restrictions with overnight support.

v1.11.1 (2026-02-15) - Statement Fixes​

Fixes​

  • Fixed: statement pagination (GET /v1/accounts/{accountId}/statement) was not working correctly. page and size parameters now return the requested page.
  • Fixed: standardized statement descriptions (e.g., "Transferência Pix", "Devolução Pix", "Tarifa Bancária", "Pagamento de QR Code").
  • Fixed: statement ordering when fees and transactions occurred at the same time.

v1.11.0 (2026-02-15) - Banking Fees in Statement and fee.charged Webhook​

New Features​

Fees in Statement​

  • Banking fees charged per transaction now appear in the statement (GET /v1/accounts/{accountId}/statement) with type FEE.
  • Each fee entry includes a feeServiceType field indicating which operation triggered the charge (e.g., PIX_OUT, PIX_IN).

fee.charged Webhook Event​

  • New event type available for subscription: fee.charged.
  • Sent in real-time when a banking fee is charged to the account.
  • Payload includes: amount, currency, feeServiceType, description, chargedAt.

v1.10.0 (2026-02-13) - Reconciliation ID, PIX Reversal Support​

New Features​

Reconciliation ID​

  • All webhooks sent to integrators (qrcode.paid, pix.in.completed, pix.out.completed, pix.out.failed, pix.refund.completed, pix.refund.failed) now include a reconciliationId field when available.
  • The reconciliationId field is also returned in the statement endpoint (GET /v1/accounts/{accountId}/statement), enabling cross-referencing with bank statements.

PIX Reversal Support​

  • The API now processes PIX reversals initiated by the recipient. When a PIX Out recipient returns the funds, the transaction is automatically recorded in the statement and linked to the original payment.
  • The original payment status is updated to REFUNDED when the full amount is returned.

Fixes​

  • Fixed: qrcode.paid webhook now includes complete payer and payee data (name, document, bank, branch, account), matching pix.in.completed.
  • Fixed: monetary values in synced statement entries were incorrect (duplicate division).

v1.9.0 (2026-02-13) - Payment Lifecycle, QR Code & Webhook Fixes​

New Features​

Complete Payment Lifecycle (PIX Out)​

  • Payments (PIX Out) now have a complete lifecycle with reconciliation tracking.
  • The GET /v1/accounts/{accountId}/payments response now includes:
    • reconciled: whether the payment was confirmed by the banking partner.
    • reconciledAt: confirmation timestamp.
    • transactionId: links the payment to its confirmed transaction in the statement.
  • Payment status flow: CREATED → PENDING → COMPLETED (or FAILED).

Full Payer/Payee Data in Webhooks​

  • pix.in.completed and qrcode.paid webhooks now include complete payer and payee details (name, document, bank, branch, account, PIX key).

Event Type Validation​

  • When creating or updating a webhook subscription, event types are validated against the official list. Invalid or legacy event types are rejected with HTTP 400.

Bug Fixes​

  • Fixed: PIX Out response was missing endToEndId and currency fields.
  • Fixed: Static QR Code creation failed due to partner API format change.
  • Fixed: removed unused clientId field from static QR Code request.

v1.8.0 (2026-02-11) - Enriched Statement & Webhook Signature Fix​

New Features​

Statement with Full Transaction Details​

  • The statement endpoint (GET /v1/accounts/{accountId}/statement) now returns complete transaction information:
    • transactionType: Transaction type (PIX_IN, PIX_OUT, QR_CODE_PAYMENT, PIX_REFUND).
    • method: Payment method (KEY, STATIC_QR_CODE, DYNAMIC_QR_CODE, MANUAL).
    • status: Current status (SUCCESS, FAILED, PENDING, REFUNDED).
    • direction: Direction (IN or OUT).
    • identifier: Integrator-provided identifier.
    • payer / payee: Full payer and payee details (name, document, bank, branch, account, PIX key).
    • originalEndToEnd / refundEndToEndIds: Linking between refunds and original transactions.
    • qrcodeId / qrcodeIdentifier: QR Code reconciliation data.

Bug Fixes​

  • Fixed: webhook HMAC signature was not applied correctly in some subscription update scenarios.

v1.7.0 (2026-02-11) - Webhook Format, Configurable Authentication & HMAC Signing​

Breaking Changes​

Webhook Payload Format​

  • The webhook body now follows the documented envelope format directly: { id, type, occurredAt, schemaVersion, environment, accountId, data }.
  • Redundant fields have been removed. The payload now contains only the documented data.
  • Added tenantId and eventType at root level for easier routing.

Webhook Signature​

  • The signature is now sent in the X-Signature header as base64(HMAC_SHA256(secret, raw_body)).
  • The previous format (hex(HMAC_SHA256(secret, timestamp + "." + body)) with X-Timestamp header) has been deprecated.
  • The X-Timestamp, X-Webhook-Event, and X-Webhook-ID headers are no longer sent.

New Features​

Configurable Authentication per Subscription​

  • Integrators can now choose the authentication method for each webhook subscription:
    • HMAC (recommended): HMAC-SHA256 signature in the X-Signature header.
    • API_KEY: Static key in a configurable header (default: X-API-Key).
    • BASIC: HTTP Basic authentication (Authorization: Basic ...).
    • BEARER: Bearer token (Authorization: Bearer ...).
    • NONE: No authentication (not recommended for production).
  • Configured via the Integrator Portal under Webhooks > Edit Subscription.

Improvements​

  • Webhook documentation fully rewritten with signature verification examples in Node.js, Python, and Go.
  • Portuguese documentation locale fully translated.

Bug Fixes​

  • Fixed: webhook authentication configuration was not being applied correctly to deliveries in some cases.

v1.6.0 (2026-02-06) - Currency Standardization, Statement Sync & Amount Validation​

New Features​

Improvements​

Currency Standardization​

  • All monetary values in the API are now clearly documented as BRL (REAIS) with at most 2 decimal places (centavos precision).
  • Example: 150.75 represents R$150,75.
  • Values with more than 2 decimal places are now rejected with HTTP 400 and a clear error message.
  • Updated all OpenAPI field descriptions with the BRL standard.
  • Fixed QR Code Static creation to accept values in REAIS (previously required centavos).

Enhanced Transaction Details​

  • Added transactionType field to transaction responses (PIX_IN, PIX_OUT, QR_CODE_PAYMENT, PIX_REFUND).
  • Added pixKey field to payer/payee details.
  • Fixed QR Code Static/Dynamic classification in statement.

v1.5.0 (2026-02-05) - URL Standardization, Payments API & QR Code Fix​

Breaking Changes​

URL Standardization​

All endpoints that previously used accountId as a query parameter now use it as a path parameter under /v1/accounts/{accountId}/.... This provides consistent, RESTful URL patterns across the entire API.

Migration guide:

Old URLNew URL
GET /v1/pix/transactions?accountId=XGET /v1/accounts/{accountId}/pix/transactions
GET /v1/payments?accountId=XGET /v1/accounts/{accountId}/payments
GET /v1/payments/{id}?accountId=XGET /v1/accounts/{accountId}/payments/{id}
GET /v1/pix/qr-codes?accountId=XGET /v1/accounts/{accountId}/pix/qr-codes
GET /v1/pix/qr-codes/stats?accountId=XGET /v1/accounts/{accountId}/pix/qr-codes/stats
POST /v1/pix/qr-code/accounts/{id}/dynamicPOST /v1/accounts/{accountId}/pix/qr-code/dynamic
POST /v1/pix/qr-code/accounts/{id}/staticPOST /v1/accounts/{accountId}/pix/qr-code/static
GET /v1/pix/qr-code/accounts/{id}GET /v1/accounts/{accountId}/pix/qr-code
DELETE /v1/pix/qr-code/accounts/{id}DELETE /v1/accounts/{accountId}/pix/qr-code
GET /v1/pix/keys/accounts/{id}GET /v1/accounts/{accountId}/pix/keys
POST /v1/pix/keys/accounts/{id}POST /v1/accounts/{accountId}/pix/keys
DELETE /v1/pix/keys/{key}/accounts/{id}DELETE /v1/accounts/{accountId}/pix/keys/{key}
GET /v1/pix/medGET /v1/accounts/{accountId}/pix/med
POST /v1/pix/med/{id}/responsePOST /v1/accounts/{accountId}/pix/med/{id}/response

Note: Legacy URLs continue to work for backward compatibility but are deprecated and will be removed in a future version.

New Features​

Payments API​

  • GET /v1/accounts/{accountId}/payments: List all PIX Out payment intents.
  • GET /v1/accounts/{accountId}/payments/{paymentId}: Retrieve payment details.

Bug Fixes​

QR Code Reconciliation​

  • Fixed a race condition where QR code payments were not linked to their transactions when the charge webhook arrived before the PIX webhook.

v1.4.0 (2026-01-16) - Webhook Event Type Standardization & Documentation​

New Features​

Webhook Event Type Improvements​

  • New event pix.med.updated: Notification when a MED/infraction status is updated.
  • Improved PIX IN/OUT differentiation: Clearer distinction between incoming and outgoing PIX events.

Standardized Event Types​

The following event types are now consistent across all systems:

  • pix.in.completed - Incoming PIX completed
  • pix.out.completed - Outgoing PIX completed
  • pix.out.failed - Outgoing PIX failed
  • qrcode.paid - QR Code was paid
  • pix.refund.completed - Refund completed
  • pix.refund.failed - Refund failed
  • pix.med.opened - MED/Infraction opened
  • pix.med.updated - MED/Infraction updated

Documentation​

  • Full English translation: OpenAPI specification and Postman collection are now fully in English.
  • Updated event type documentation: All webhook documentation updated with standardized event types.
  • Consistency improvements: Event types are now consistent across frontend, API handlers, and documentation.

Breaking Changes​

  • Legacy event types (pix.received, pix.cash_in, pix.cash_out) are deprecated in favor of the new standardized types.
  • Existing webhook subscriptions using old event types will continue to work but should be migrated.

v1.3.0 (2026-01-29) - QR Code Statistics and Charge Webhooks​

New Features​

QR Code Statistics​

  • New endpoint GET /v1/pix/qr-codes/stats: Returns aggregated QR Code statistics for the last 24 hours.
    • Number of QR Codes generated, paid, and refunded
    • Total values (generated, paid, refunded)
    • Conversion rate (paid/generated)
    • Hourly aggregated data for trend analysis

Charge Webhooks (COB)​

  • QR Code payment notifications: When a dynamic QR Code is paid, the system automatically updates the QR Code status to PAID and notifies via webhook.
  • qrcode.paid event: Webhook sent when a QR Code is confirmed as paid by BACEN.
  • Automatic webhook registration: When creating a PIX key, the charge webhook is automatically registered to receive payment notifications.

Bug Fixes​

  • Fixed balance display values.
  • Fixed transaction values in the statement.

Documentation​

  • Added QR Code statistics endpoint to OpenAPI specification.
  • Updated Postman collection with new statistics endpoint.

v1.2.0 (2026-01-27) - Integrator Portal and Webhooks​

New Features​

  • Integrator Portal: Documentation added with portal link and capabilities.

Changes​

  • Webhooks via Portal: Webhook configuration now occurs exclusively through the Integrator Portal.
  • Adjusted documentation: Removed references to public webhook management endpoints; only POST /webhooks/replay and GET /v1/webhooks/events retained.

v1.1.0 (2026-01-27) - Webhook Management via API​

New Features​

Self-Service Webhooks​

  • Webhook CRUD via API: You can now create, list, update, and delete webhook configurations directly via API without contacting support.
  • Multiple Authentication Types: Support for HMAC, API_KEY, BASIC, BEARER, and IP_WHITELIST for webhook authentication.
  • Event Type Filter: Configure which event types each webhook should receive.
  • Available Events Endpoint: New GET /v1/webhooks/events endpoint to list all supported event types.

New Webhook Events​

  • pix.pending: New event sent when a Pix is pending confirmation (useful for real-time payment tracking).
  • pix.qrcode.cash_in: Specific event for QR Code payments via charge.

Security​

  • IP Restriction for Webhooks: Webhook endpoints now support source IP restriction.

Bug Fixes​

  • Improved webhook documentation with more detailed examples.
  • Fixed payload examples in webhook events.

v1.0.0 (2025-12-29) - Initial Release (CorpX API)​

This is the first official version of the unified public documentation for the CorpX API, focused on external integrators and banking partners.

Main Features​

Pix and Payments​

  • Pix Out: Instant transfers using Pix keys in a single step.
  • QR Codes: Dynamic and static QR Code generation, with support for capture, status query, and cancellation.
  • Refunds: Refund flow for received Pix.
  • Pix MED: Full support for the Special Return Mechanism for infraction and dispute management.

Account Management​

  • Balance Query: Detailed view of total, available, and locked balance.
  • Statement: Paginated transaction and account movement history.
  • Internal Transfers: P2P resource movement between accounts on the same platform.

Webhooks and Notifications​

  • Outbound Notifications: Automatic event reception (Pix received, Pix sent, MED updates).
  • Security: HMAC-SHA256 signature on all notifications for origin guarantee.
  • Retries: Automatic retry system with exponential backoff.
  • Replay Self-Service: Endpoints to request notification resend (Individual or Batch) via API.

Security and Idempotency​

  • Authentication: OAuth2 via Identity Provider (client_credentials and authorization_code flows).
  • Idempotency: Single execution guarantee for mutable operations via Idempotency-Key header.
  • Transaction Signing: All Pix transfer operations are protected by RSA-SHA512 signatures.

Multi-language Support​

  • Documentation available in Portuguese, English, and Simplified Chinese.

Developer Experience​

  • OpenAPI 3.0: Complete specification available for download and interactive Swagger UI.
  • Postman Collection: Ready-to-use collection for testing in Sandbox environment.
  • Integrator Guide: Detailed documentation on headers, errors, and best practices.