Pular para o conteúdo principal

Changelog

Este documento registra todas as alterações notáveis na API CorpX.

v2.20.1 (2026-06-15) - fee.charged e fee.refunded para tarifas externas​

Webhooks de tarifa agora também são enviados quando a cobrança é emitida fora da API (pelo serviço de cobrança ou pelo próprio liquidante). Antes, esses casos chegavam ao integrador como transfer.internal.out (cobrança) ou transfer.internal.in (estorno), o que contradizia o contrato — agora seguem a tipagem oficial:

  • fee.charged — emitido quando uma tarifa é debitada da conta do cliente para a contraparte de tarifas (ex.: Corp X Brasil LTDA ou MT Instituição de Pagamento SA). Inclui feeServiceType (PIX / TED / BOLETO / INTERNAL_TRANSFER / MONTHLY / OTHER) e originalRef / transactionRef referenciando a operação que motivou a cobrança.
  • fee.refunded — emitido quando o liquidante estorna uma tarifa cobrada anteriormente.

Tarifas iniciadas via API (raras hoje) continuam não disparando esses eventos; eles são exclusivos para movimentações originadas externamente.

A estrutura segue o contrato documentado em Webhooks → 9. fee.charged / 9.1. fee.refunded.

v2.20.0 (2026-06-12) - Limites de DICT lookup e cache de 24h​

A consulta DICT (GET /v1/accounts/{accountId}/pix/key/{pixKey}) agora respeita os limites configurados na policy do tenant ou da conta:

  • maxLookupsPerDay — teto absoluto de consultas por dia (calendário em horário de Brasília). 0 ou ausente = ilimitado.
  • maxLookupRatio — teto relativo: ratio × pix_outs_24h. Exemplo: ratio 3.0 com 100 PIX out nas últimas 24h permite 300 consultas na mesma janela.

Quando ambos estão configurados vale o mais restritivo. Estourar qualquer um deles devolve 429 dict_lookup_limit_exceeded com o contador atual em message.

Além disso, o cache de 24h foi ativado de fato: respostas de uma consulta anterior à mesma chave (até 24h depois) retornam imediatamente com cached: true e não consomem o limite — o objetivo da policy é proteger o DICT contra abuso. Use noCache=true na query para forçar uma consulta fresca.

Os limites podem ser configurados no Backoffice (Policies → DICT Lookup). Tenants sem policy configurada continuam sem limite (comportamento inalterado).

v2.19.1 (2026-06-11) - Correção: webhook pix.refund.received indevido em devoluções emitidas​

Corrigido: ao emitir uma devolução (POST /v1/accounts/{accountId}/pix/out/refund), o seu endpoint de webhooks podia receber um evento pix.refund.received indevido — como se você tivesse recebido uma devolução de terceiros, quando na verdade foi você quem a emitiu.

Comportamento corrigido:

  • Devolução emitida por você via API: você recebe apenas a confirmação normal do fluxo de devolução (pix.refund.completed / pix.refund.failed). Nenhum pix.refund.received é gerado.
  • Devolução emitida fora da API (ex.: canais do liquidante): você recebe pix.refund.completed / pix.refund.failed com external: true.
  • Devolução recebida de terceiros (contraparte devolveu um PIX que você enviou): pix.refund.received continua sendo enviado normalmente.

v2.19.0 (2026-06-10) - Fim do limite de R$ 15.000 por transação PIX; BigPix descontinuado​

O limite de R$ 15.000 por transação PIX foi removido pelo liquidante. POST /v1/accounts/{accountId}/pix/out (e as variantes /async, /bank-account, /qr-code) agora aceitam qualquer valor em uma única transação — sem necessidade de dividir em múltiplos PIX.

Com isso, o BigPix está descontinuado:

  • POST /v1/accounts/{accountId}/pix/out/bigpix
  • POST /v1/accounts/{accountId}/pix/out/bank-account/bigpix
  • GET /v1/accounts/{accountId}/pix/out/bigpix/{batchId}

Esses endpoints continuam funcionais por retrocompatibilidade, mas as respostas agora incluem o header Deprecation: true. Recomendamos migrar para POST /pix/out (ou /pix/out/bank-account), que tem o mesmo shape de request — basta enviar o valor total no campo amount. A data de remoção definitiva será anunciada neste changelog com antecedência.

Os limites operacionais da sua conta (diário, noturno, por contraparte) continuam valendo normalmente — consulte GET /v1/accounts/{accountId}/limits.

v2.18.3 (2026-06-09) - Webhooks para transferências internas externas​

Transferências internas entre contas do mesmo banco (MT Bank) originadas fora da API — como pelo aplicativo móvel ou console do parceiro — agora disparam webhooks transfer.internal.in (para a conta que recebeu) ou transfer.internal.out (para a conta que enviou).

Isso complementa o comportamento existente: transferências internas iniciadas via POST /v1/accounts/{accountId}/transfers/internal já disparavam webhooks para ambas as pontas. Agora, movimentações que você não iniciou via API também notificam seu endpoint de webhooks, com o campo external: true no payload indicando que a origem foi externa.

v2.18.2 (2026-06-07) - Erro de devolução (refund) mais preciso​

Devolução de PIX (POST /v1/accounts/{accountId}/pix/out/refund): quando a transação original não permite devolução (não está Confirmado — já devolvida/revertida, rejeitada ou ainda processando), a recusa agora volta com errorCode: conflict e o motivo do liquidante em errorReason/message (ex.: Transação com status diferente de 'Confirmado'.).

Antes esse caso voltava errorCode: invalid_payload com o errorReason contendo o JSON bruto do parceiro. Agora o código reflete corretamente um conflito de estado (não um payload inválido) e o motivo vem limpo.

Além disso, a consulta exata do extrato (por endToEndId/identifier em GET /v1/accounts/{accountId}/statement) passou a consultar o liquidante diretamente e pode incluir os campos opcionais initiation, errorMessage e fee no item, além de payer/payee/counterParty completos.

v2.18.1 (2026-06-07) - Saldo é somente leitura (sem bloqueio do nosso lado)​

Esclarecimento de contrato: a API não trata bloqueio de saldo. O GET /v1/accounts/{accountId}/balance apenas exibe o valor bloqueado pelo liquidante no campo locked (espelho do bloqueio da MT). Não existe endpoint de lock/unlock de saldo nem "hold local".

A resposta de saldo não inclui o campo locks (lista de bloqueios locais) — esse campo nunca foi populado e foi removido da especificação. Os campos total, locked, available, currency e updatedAt permanecem inalterados.

v2.18.0 (2026-06-06) - Saldos diários, contraparte enriquecida e novos filtros no extrato​

Novo endpoint GET /v1/accounts/{accountId}/daily-balance: retorna a série de saldos diários da conta — saldos de abertura (total / bloqueado / disponível no início de cada dia) e os fluxos consolidados do dia (PIX entrada/saída, TED entrada/saída, transferências internas, pagamentos de boleto, mint/burn de stablecoin e tarifas). As datas são dias-calendário em horário de Brasília (BRT). Janela máxima de 30 dias. Só são retornados fechamentos a partir de 04/06/2026 (dados do liquidante anteriores a essa data eram inconsistentes e ficam omitidos) — a resposta inclui cutoffDate e timezone.

Extrato (GET /v1/accounts/{accountId}/statement) — campos novos (aditivos, retrocompatíveis):

  • transactionType: código C (crédito/entrada) ou D (débito/saída), espelhando direction.
  • counterParty agora inclui os dados bancários da contraparte quando o liquidante informa: bankName, bankIspb, bankCode, branch, account, accountType, pixKey (antes só name e document).

Extrato — filtragem agora é 100% server-side:

  • O filtro operation (PIX, TED, BOLETO, INTERNAL_TRANSFER) é aplicado no liquidante, com totalElements/totalPages exatos. Combine com order (asc/desc) e startDate/endDate.
  • Os filtros status e operation=FEE foram removidos: eram aplicados apenas sobre a página corrente (pós-paginação), o que gerava contagens inconsistentes. O campo filteredCount da resposta também foi removido. Para filtrar por status ou tarifa, processe os items retornados no seu lado.

v2.17.0 (2026-06-05) - Limite do identifier ampliado para 38 caracteres​

O campo identifier enviado pelo integrador em PIX out, QR codes (estático/dinâmico) e transferências internas passa a aceitar até 38 caracteres (antes: 32). O charset ([A-Za-z0-9._-]) e o prefixo reservado fee- permanecem iguais.

Mudança 100% retrocompatível: identifiers existentes com até 32 caracteres continuam válidos sem nenhuma alteração no código do integrador. Apenas o teto foi relaxado.

Motivação: alinhar o limite de PIX individual com o do BigPix (que já era 38 chars no identifier base do batch). Integradores que usam ambos os fluxos não precisam mais de schemes diferentes de geração de id entre eles.

v2.16.0 (2026-06-02) - Extrato legacy (pré-cutover)​

Novo endpoint GET /v1/accounts/{accountId}/statement/legacy para consultar o histórico importado do core anterior (Finaya/Stark), lido de legacy_transactions.

Contrato: mesmo shape de GET /v1/accounts/{accountId}/statement (page, size, startDate, endDate, status, operation). Resposta com source: legacy, header X-Source: legacy. Cada item inclui ispb (30306294 Finaya, 20018183 Stark) e source: legacy.

Sem alteração no extrato live (GET .../statement) — continua só MT Bank real-time.

Visão unificada legacy + live em bulk: export CSV assíncrono (POST /v1/accounts/{accountId}/exports).

v2.15.0 (2026-05-30) - Export de extrato reativado​

Export CSV de extrato reativado no modelo live (MT Bank) + histórico legacy (legacy_transactions).

Endpoints:

  • POST /v1/accounts/{accountId}/exports — cria job assíncrono (202)
  • GET /v1/accounts/{accountId}/exports — lista jobs
  • GET /v1/accounts/{accountId}/exports/{exportId}/download — URL presigned

CSV: colunas alinhadas ao extrato, com ispb para distinguir Finaya/Stark (legacy) de MT Bank (live). Sem coluna de saldo após (balance). Períodos longos são fatiados em janelas de 31 dias na consulta live.

v2.14.0 (2026-05-30) - Consulta de dados bancários da conta​

Novo endpoint GET /v1/accounts/{accountId}/bank-account para consultar código do banco (COMPE), agência e número da conta credenciada.

Resposta (200):

  • bankCode, bankIspb, bankName, branch, accountNumber
  • holderDocument, holderName, accountId, status

Útil para exibir instruções de depósito ou reconciliar transferências sem depender de chaves PIX. Contas ainda em credenciamento retornam 422 com mensagem clara.

v2.13.0 (2026-05-25) - Decode de QR Code mais rico​

O endpoint POST /v1/accounts/{accountId}/pix/out/qr-code/decode agora expõe todos os dados que o liquidante já retornava no capture do QR — antes a maior parte ficava só nos logs internos. A mudança é 100% retrocompatível: todos os campos existentes continuam presentes; apenas novos campos foram adicionados.

Campos novos no response (opcionais; presentes quando o liquidante envia):

  • originalAmount — valor de face do QR antes de descontos/juros/multa (em dynamic-due-date pode diferir de amount).
  • qrCodeType (static | dynamic-immediate | dynamic-due-date) e qrCodeTypeId (numérico) — promovidos a nível top-level (antes só existiam embaixo de Extra).
  • allowChange — agora realmente populado com o valor do liquidante (AllowPayerChangeValue) em dynamic-immediate; antes estava documentado mas nunca era preenchido.
  • payeeTradeName — nome fantasia da PJ (típico em dynamic-due-date).
  • bankIspb / bankBranch / bankAccount / accountType — dados bancários do recebedor. accountType é canonicalizado para CHECKING | SAVINGS | PAYMENT | SALARY (ou upper snake-case para variantes ainda não vistas).
  • discount, deduction, interest, penalty — componentes do valor em dynamic-due-date. Relação: amount = originalAmount - discount - deduction + interest + penalty. Antes só discount constava na doc (sempre 0).
  • dueDate e paymentDeadline — promovidos a nível top-level (antes ficavam em Extra; permanecem em Extra por retrocompat).

Compatibilidade: key, amount, payeeName, payeeDocument, identifier, decodeId, description continuam com o mesmo nome e shape. Integrações antigas seguem funcionando sem mudança.

v2.12.1 (2026-05-24) - PIX status PENDING_APPROVAL​

Novo status canônico retornado pelos endpoints PIX (GET /v1/accounts/{accountId}/pix/payments/lookup, GET /v1/accounts/{accountId}/payments/{paymentId}, extrato e webhooks de envelope):

  • PENDING_APPROVAL — o liquidante aceitou o pedido de PIX OUT mas está retendo para aprovação interna (multi-alçada, 2FA, esteira anti-fraude). Ainda não existe endToEndId, e o dinheiro não saiu. Em algum momento o liquidante libera (vira PENDING → COMPLETED) ou recusa (vira FAILED).

Por que o status novo: antes, esse cenário era propagado como o valor cru do parceiro (AWAITING-AUTHORIZATION), que vazava pela API pública. A partir desta versão nunca propagamos valor cru de parceiro — todo status é canonicalizado. Status fora do vocabulário conhecido vira UNKNOWN + warning estruturado no nosso lado para que adicionemos o mapeamento na próxima release.

Sem impacto para integrações com PIX OUT comum (fluxo já passa por PROCESSING → COMPLETED/FAILED). Integrações que monitoram status intermediários devem aceitar PENDING_APPROVAL como não-terminal (continuar polling ou aguardar webhook subsequente).

Webhooks pix.out.completed / pix.out.failed continuam só disparando em estados terminais — PENDING_APPROVAL não emite webhook outbound.

v2.12.0 (2026-05-23) - TED disponível (envio + recebimento)​

Novidade major: TED (Transferência Eletrônica Disponível BACEN) agora é um produto público da API. Cobre envio interbancário, consulta de status assíncrona e webhooks de recebimento. Banco liquidante: MT Instituição de Pagamentos (Compe 681 / ISPB 50871921). Ver Guia TED.

Endpoints novos​

  • POST /v1/accounts/{accountId}/ted/out — envia TED (assíncrono, 202)
  • GET /v1/accounts/{accountId}/transfers/ted/{tedId} — consulta status (PROCESSING → COMPLETED | FAILED)

Webhooks novos​

  • ted.out.requested — TED registrada no liquidante (status inicial)
  • ted.out.confirmed — liquidação confirmada (terminal — sucesso)
  • ted.out.failed — rejeição/expiração/timeout 48h (terminal — falha)
  • ted.in.received — TED recebida na sua conta

Janela e tempos​

  • Dias úteis 06:30–17:00 → liquidação no mesmo dia útil (~30min após envio)
  • Fora da janela → agendada para D+1 útil; status fica PROCESSING até liquidar
  • Servidor faz polling defensivo a cada 1 minuto por até 48 horas — garantia de convergência mesmo se webhook do liquidante falhar

Deprecação​

ted.payment (catálogo legado v1) vira alias deprecated de ted.out.confirmed. Ambos são disparados juntos durante o ciclo de vida da v2.x; ted.payment será removido na v3.0 (data a ser anunciada).

  • Novos integradores: assinar apenas ted.out.confirmed
  • Integradores legados: podem manter ted.payment até v3.0; migração é desassinar + assinar ted.out.confirmed (payloads idênticos)

v2.11.1 (2026-05-22) - Correção: webhook duplicado em tenants com múltiplas subscriptions​

Bug fix de impacto direto para integradores que têm mais de uma subscription ativa para o mesmo eventType no mesmo tenant.

Em versões anteriores, cada subscription que casava o evento gerava um POST separado ao egress (Hookdeck). Como o filtro Hookdeck é por tenantId + type no corpo, todos esses POSTs entregavam a TODAS as destinations, multiplicando as entregas: tenant com N subscriptions ao mesmo evento recebia N² entregas ao invés de N.

A partir desta versão, cada evento gera 1 único POST ao egress; o Hookdeck faz o fanout para as N destinations (1 entrega por subscription, sem duplicação).

Não há mudança de payload ou contrato — apenas correção da quantidade de entregas. Se você implementou deduplicação client-side pelo id do envelope, pode mantê-la (ainda é boa prática).

v2.11.0 (2026-05-22) - Envelope de webhook alinhado ao formato v1​

O payload dos webhooks de egress (entregues à URL cadastrada por POST /v1/webhooks) volta a seguir o mesmo envelope documentado na v1. Quem migrou v1 → v2 sem mudar o parser do webhook agora recebe os campos exatamente onde esperava.

Envelope (todos os eventos):

CampoAntes (v2.10)Agora (v2.11)
schemaVersionausente"1.0"
environmentausente"production" | "sandbox"
accountId (raiz)apenas em data.accountIdadicionado na raiz (continua em data.accountId)
tenantId (raiz)já existiamantido

Campos no data por evento (ajustes para casar com a v1):

  • pix.in.completed: endToEndId renomeado para endToEnd; adicionado receivedAt.
  • pix.out.completed / pix.out.failed: status agora é "SUCCESS" / "FAILED" (antes vinha "COMPLETED"); adicionado key: { type, key } quando o PIX foi por chave; adicionado completedAt; adicionado alias error (= errorReason) em falhas.
  • pix.refund.received: refundEndToEndId → refundEndToEnd; originalEndToEndId → originalEndToEnd; adicionado receivedAt.
  • qrcode.paid: endToEndId → endToEnd; paidAmount → amount; payerName/payerDocument agrupados em payer: { name, document }; adicionado qrcodeId (= txid), type (static | dynamic), receivedAt, status: "SUCCESS".
  • qrcode.cancelled: adicionado status: "CANCELLED" e type.
  • qrcode.expired: adicionado status: "EXPIRED" e type.
  • pix.med.opened / pix.med.updated: nomes corrigidos para pix.med.* (antes o backend emitia med.opened / med.decided, que não existiam no catálogo público — efetivamente os integradores não recebiam estes eventos). originalEndToEndId → originalEndToEnd; adicionado status (OPEN | PENDING_DECISION | ACCEPTED | REJECTED | CANCELED).
  • transfer.internal.in / transfer.internal.out: endToEndId → endToEnd.
  • boleto.paid / boleto.failed: status agora é "SUCCESS" / "FAILED"; adicionado alias error em falhas.

Removido: o campo currency não é mais emitido nem documentado — todos os valores monetários são em BRL por contrato e usam ponto decimal (150.50). A coluna currency nunca chegou a entrar em produção da v2 para a maioria dos eventos; remoção fecha o último gap.

Compatibilidade​

Aliases mantidos (lidos e escritos): nenhum dos nomes antigos é mais emitido. Se você consumia data.endToEndId em PIX in ou data.paidAmount em QR pago, precisa renomear para data.endToEnd e data.amount. Verifique os exemplos em Webhooks.

v2.10.0 (2026-05-22) - Vocabulário de refund alinhado ao banco parceiro​

POST /v1/accounts/{accountId}/pix/out/refund (e POST /pix/out com mode=REFUND) agora aceita um conjunto fechado de slugs em kebab-case no campo reason. Os valores antigos (USER_REQUESTED, FRAUD, BANK_ERROR, CASHIER_ERROR, CUSTOMER_REQUEST) não são mais aceitos — payloads com esses valores recebem HTTP 400 com mensagem clara listando os slugs válidos.

Os slugs aceitos são repassados literalmente ao banco parceiro (MT Bank), sem tradução intermediária:

SlugQuando usar
user-requestedCliente final solicitou a devolução
transaction-errorErro genérico na transação
unauthorized-transactionTransação não autorizada
fraudFraude comprovada/em investigação
trade-disagreementDesacordo comercial
withdrawal-purchasePIX Saque/Troco
contractual-divergenceDivergência contratual
operational-errorErro operacional/processamento
duplicate-paymentPagamento duplicado

Motivo da mudança: o endpoint v2 estava devolvendo erro 422 em todos os refunds porque o vocabulário antigo não casava com o aceito pelo banco parceiro. Esta versão alinha API pública e parceiro 1:1, evitando mapeamentos opacos.

v2.9.0 (2026-05-21) - Documento da contraparte no extrato​

Os itens do extrato (GET /v1/accounts/{accountId}/statement) agora incluem o documento (CPF/CNPJ) da contraparte além do nome:

  • recipientName: nome da contraparte (já existente).
  • recipientDocument: novo campo — CPF (11 dígitos) ou CNPJ (14 dígitos) da contraparte, sem máscara (digits-only).
  • counterParty: novo objeto agregando { name, document }. Omitido quando ambos os campos estão vazios.

Para transações com direction: "IN", a contraparte é o pagador; para direction: "OUT", é o destinatário. Campos retrocompatíveis — integradores que não precisam do documento não precisam ajustar nada.

v2.0 (2026-05-21) - Nova plataforma CorpX​

A v2 é uma reescrita completa da plataforma sobre uma infraestrutura mais rápida e previsível, com integração direta ao novo liquidante. Em geral retrocompatível com a v1.

Guia de migração

Tudo o que você precisa para migrar está em um documento só:

Auth​

  • Nova base URL: https://tenant.api.corpx.com/v1 (era https://api.corpxapi.com/v1)
  • Novo Token URL: https://auth.api.corpx.com/oauth2/token
  • Novos client_id + client_secret por integrador (entregues por canal seguro)
  • Scopes: api/full → api2/read api2/write
  • Idempotency-Key virou opcional (auto-gerado se ausente)
  • X-Tenant-Id é obrigatório em todas as requisições /v1/* (exceto GET /v1/me e health); deve coincidir com o tenant da conta quando accountId está no path

Statement consolidado em um único endpoint​

  • GET /v1/accounts/{accountId}/statement é agora sempre live — consulta o liquidante em tempo real (sem cache local).
  • Os endpoints derivados que liam do mesmo cache (/pix/transactions, /pix/payments, /payments alias) também passam a ser live.
  • A API v1 e o backoffice anteriores continuam no ar em modo somente-leitura por 30 dias após o cutover para consulta histórica.
  • Endpoints /transactions/real-statement, /transactions/legacy-statement e /payments/{id}/legacy não existem na v2 — use /statement (atual) ou a v1 read-only (histórico).

Endpoints deprecated (ainda funcionam até 2026-11-21)​

4 paths que existiam na v1 e ficaram fora da versão canônica da v2 voltam como aliases deprecated. Continuam respondendo normalmente, mas anexam 3 headers de aviso na resposta:

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

Esses headers seguem RFC 8594 (Deprecation) e RFC 9745 (Sunset). Sunset previsto: 2026-11-21 — após essa data passam a retornar 410 Gone. Não aparecem mais no OpenAPI nem na Postman collection.

  • GET /v1/accounts/{id}/pix/payments/{paymentId} → use /pix/payments/lookup?identifier=
  • GET /v1/accounts/{id}/payments/{paymentId} (alias sem /pix/) → use /pix/payments/lookup?identifier=
  • GET /v1/accounts/{id}/pix/qr-code (sem /lookup) → use /pix/qr-code/lookup?identifier=
  • POST /v1/accounts/{id}/pix/out/qrcode (sem hífen) → use /pix/out/qr-code

Endpoints removidos (retornam 404 na v2)​

  • POST /v1/webhooks/replay → sem substituto
  • GET /v1/integrator/webhooks → use GET /v1/webhooks
  • GET /v1/integrator/webhooks/{id}/deliveries → sem substituto
  • POST /v1/integrator/events/replay + /batch → sem substituto
  • POST .../pix/med/{medId}/send + /response → use /decide + /answer

GET /v1/health continua existindo na v2 (ganhou alias adicional GET /health para health checks externos).

Endpoints novos​

  • GET /v1/me (debug do client_id autenticado)
  • GET /v1/transactions/{id}/timeline (sem accountId no path)
  • GET /v1/accounts/{id}/pix/out/bigpix/{batchId} (status agregado de lote BigPix)
  • GET /health (alias do /v1/health sem o prefixo)
  • Boleto family (POST .../boleto/preview|pay, GET .../boleto/payments/{id}) — era 503 na v1, agora ativo

Mudanças de comportamento (mesmo path, novo shape ou semântica)​

  • Statement e endpoints derivados: cache → live; sem tariff_ref derivado; header X-Source: live; janela máxima por consulta 31 dias.
  • Internal transfer by-bank-account: aceita holderDocument + holderName opcionais (não breaking).
  • Locked balance unlock: v2 só valida lockId; campos extras são ignorados (não breaking).
  • Campo fee no objeto de transação removido temporariamente — conciliação manual via identifier=fee-{slug}-{operationReferenceId} no extrato. Volta sem mudança de payload em release futura.

MED e webhooks temporariamente suspensos​

  • Endpoints /v1/accounts/{id}/pix/med/* retornam HTTP 503 durante a migração. Disputas em aberto seguem o ciclo natural do BACEN — apenas a integração via API está pausada.
  • Webhooks suspensos: fee.*, pix.med.*, edi.*. Subscriptions a esses eventos podem permanecer ativas — quando voltarem, retomam automaticamente. Tarifas seguem aparecendo no extrato como linhas independentes (com identifier=fee-{slug}-{ref}).

Compat (sem mudança no seu código)​

  • BigPix (POST .../pix/out/bigpix e .../bank-account/bigpix): body continua single ({amount, key, ...}); chunking permanece server-side, igual à v1.
  • PIX out variants (/pix/out/async, /bank-account/async, /bank-account/bigpix): preservados.
  • /v1/accounts/{accountId}/transfers/internal (todos os 3 modos): path e body preservados.
  • /v1/accounts/{id}/pix/qr-code/static body: value continua como na v1.
  • /v1/accounts/{id}/pix/out/qr-code/decode: path preservado.
  • /v1/accounts/{id}/pix/keys (GET + POST + DELETE): mantidos.
  • /v1/accounts/{id}/pix/key/{pixKey} (DICT lookup): mantido.

Suporte​

Contato: suporte-api@corpx.com durante o cutover do tenant — resposta em até 1h em horário comercial.

v1.30.3 (2026-04-30) - Eliminação de webhooks duplicados (pix.refund.completed, pix.out.failed, qrcode.paid)​

Correções​

  • Webhooks duplicados removidos: a infraestrutura emitia, em alguns cenários, dois webhooks para o mesmo evento — um seguindo o formato documentado e outro com um formato legado nunca descrito na documentação. O comportamento foi corrigido: agora cada evento gera exatamente uma notificação, sempre no formato documentado.

    Os eventos afetados eram:

    • pix.refund.completed (gerado quando uma devolução é concluída)
    • pix.out.failed (gerado quando um PIX OUT falha)
    • qrcode.paid (gerado quando um QR Code é pago)

    O formato legado nunca esteve presente em docs/webhooks — era uma emissão paralela de uma rotina interna que escapou da documentação. Integrações que dependiam apenas dos campos documentados não percebem nenhuma diferença além da ausência da duplicata.

  • Campo data.status em pix.refund.completed: agora retorna sempre SUCCESS (alinhado à tabela oficial de status). Antes, em alguns casos, vinha REFUNDED por contaminação com o status da transação original.

Diferenças que somem (apenas para integrações que estavam acopladas ao formato legado, não documentado)​

Campo / formato (legado)Substituído por (formato documentado)
id: refund_completed_{paymentId}_{ts}id em formato hash (sha256)
id: pix_out_failed_{paymentId}_{ts}id em formato hash (sha256)
id: qr_paid_{txid}_{ts}id em formato hash (sha256)
data.status: COMPLETED (em pix.refund.completed)data.status: SUCCESS
data.status: REFUNDED (em pix.refund.completed)data.status: SUCCESS
data.refundId (em pix.refund.completed)use data.transactionId (já documentado)
data.failedAt (em pix.out.failed)use occurredAt no envelope
data.paymentId (em pix.out.failed)use data.transactionId (já documentado)
payer.account / payee.accountpayer.accountNumber / payee.accountNumber

Se sua integração consumia algum desses campos exclusivos do formato legado, ajuste-a para usar os campos documentados antes de adotar essa versão.

Recomendação para deduplicação​

Use sempre uma chave forte do payload para deduplicar webhooks no seu lado:

  • Para pix.refund.completed: data.refundEndToEnd (D-code BACEN, único globalmente).
  • Para pix.out.failed: data.endToEnd (E-code BACEN) ou data.identifier.
  • Para qrcode.paid: data.endToEnd ou data.qrcodeId.

Esses campos são únicos por transação e estão presentes em todos os eventos.

v1.30.2 (2026-04-30) - Padronização de timestamps em UTC nos webhooks​

Correções​

  • Datas dentro de data agora vêm sempre em UTC com sufixo Z em todos os webhooks. Anteriormente, alguns campos (receivedAt, completedAt, initiatedAt, chargedAt, openedAt) eram repassados sem indicador de fuso horário, o que levava parsers ISO 8601 rigorosos a interpretarem como horário local da máquina e gerava diferenças de até 3 horas em ambientes BRT.
  • Padrão consolidado e documentado em Webhooks → Formato de datas e horários.
  • A documentação já indicava Z (UTC) nos exemplos; agora todos os payloads emitidos respeitam o padrão.

v1.30.1 (2026-04-29) - Webhook qrcode.paid mantido (não será descontinuado)​

Reversão de descontinuação​

  • qrcode.paid segue suportado oficialmente. Avisos de descontinuação que apareciam no Guia de Webhooks (em PT, EN e ZH) foram removidos. O evento continua válido e estável; nenhuma migração é necessária.
  • O evento equivalente pix.in.completed com method: QR_CODE_DYNAMIC ou QR_CODE_STATIC permanece disponível como alternativa (e continua sendo disparado em paralelo) — escolha a que melhor se encaixa na sua integração.

v1.30.0 (2026-04-23) - Correções em transferências internas (mapeamento de erro + identifier no webhook)​

Correções​

  • Mapeamento de erro account_disabled (TX00012) do parceiro bancário: quando a conta de origem está desabilitada no parceiro bancário, a API agora retorna HTTP 422 com errorCode: partner_account_disabled. Antes, esse caso era mapeado para HTTP 502 (Bad Gateway), o que enganava o integrador a tratar como falha de infraestrutura em vez de regra de negócio. A mudança afeta os três endpoints de transferência interna (/transfers/internal, /transfers/internal/by-document, /transfers/internal/by-bank-account).
  • Classificação unificada de erros do parceiro bancário: erros HTTP do core bancário (usado em transferências internas e leituras de conta) agora passam pelo mesmo classificador já usado nos demais endpoints. Códigos específicos como insufficient_balance, daily_limit_exceeded, account_disabled retornam 422 em vez de 502.

Melhorias​

  • identifier e description agora voltam no webhook transfer.internal.out: o identificador único e a descrição informados pelo integrador no POST /transfers/internal* passam a ser propagados para o webhook enviado à conta pagadora. Permite fechar a reconciliação de transferências internas sem consultar o extrato.
  • Descrição customizada do pagador substitui o texto padrão Transferência Interna no extrato (GET /statement) quando informada na requisição.
  • coreId agora vem em todos os webhooks de lançamento: o UUID da linha no core bancário (mesmo valor retornado no campo coreId do extrato) é propagado em pix.in.completed, pix.out.completed, pix.out.failed, pix.refund.*, qrcode.paid, transfer.internal.*, fee.charged e fee.refunded. Permite reconciliar webhook ↔ extrato ↔ exports do parceiro por uma chave única e estável.
  • status padronizado em todos os webhooks de lançamento: o campo data.status passa a ser garantido em todos os eventos de PIX, QR, transferência interna, refund e tarifa. Vocabulário padronizado: SUCCESS (operação concluída), FAILED (operação falhou, com data.error), REVERSED (lançamento previamente concluído foi revertido). Eventos de MED (pix.med.*) mantêm seu vocabulário próprio (OPEN, PENDING_DECISION, ACCEPTED, REJECTED, CANCELED). Ver tabela completa em docs/webhooks.

Novos errorCode retornados​

CódigoHTTPQuando acontece
partner_account_disabled422A conta de origem está desabilitada no parceiro bancário (precisa de reativação)

v1.29.0 (2026-04-18) - Consulta de destinatário de transferência interna por documento​

Novos recursos​

  • Consulta prévia de destinatário para transferência interna: Novo endpoint GET /v1/accounts/{accountId}/transfers/internal/lookup/{document} permite consultar o nome do titular antes de executar uma transferência interna por CPF/CNPJ. Útil para exibir uma confirmação ao usuário final.
  • O nome é retornado com máscara de privacidade: o primeiro nome é mantido integral, e cada sobrenome é reduzido à primeira letra seguida de ***. Conectores como "de", "da", "dos" são preservados.
    • Exemplo: "JOAO DA SILVA PEREIRA" → "JOAO da S*** P***"
  • O endpoint retorna também o accountStatus do destinatário no parceiro bancário.

Fluxo recomendado​

  1. Cliente informa o CPF/CNPJ do destinatário
  2. Integrador chama GET /transfers/internal/lookup/{document} e exibe o maskedName para confirmação
  3. Usuário confirma
  4. Integrador chama POST /transfers/internal/by-document para executar a transferência

v1.28.0 (2026-04-17) - Remoção de webhooks deprecated​

Breaking Changes​

  • Webhooks payment.sent e payment.refunded desativados: Estes eventos foram marcados como deprecated na v1.15.0 (2026-02-20) e agora foram permanentemente desativados.
    • payment.sent → use pix.out.completed (inclui campo method e objeto payment)
    • payment.refunded → use pix.refund.completed (inclui originalEndToEnd, refundEndToEnd e detalhes das partes)
  • Se sua integração ainda assina esses eventos, migre imediatamente para os substitutos listados acima.

v1.27.0 (2026-04-14) - PIX Out por dados bancários​

Novos recursos​

  • PIX Out por dados bancários: Novos endpoints para transferir PIX usando agência, conta e ISPB do destinatário (sem necessidade de chave PIX):
    • POST /v1/accounts/{accountId}/pix/out/bank-account — Transferência síncrona por dados bancários.
    • POST /v1/accounts/{accountId}/pix/out/bank-account/async — Transferência assíncrona (enfileirada).
    • POST /v1/accounts/{accountId}/pix/out/bank-account/bigpix — Transferência de valores grandes com split automático em chunks.
  • Os campos obrigatórios são: bankIspb (código ISPB do banco), accountNumber, accountBranch, documentNumber (CPF/CNPJ do beneficiário) e name.
  • O campo accountType aceita CHECKING_ACCOUNT, SAVINGS_ACCOUNT ou PAYMENT (padrão: CHECKING_ACCOUNT).

Observações​

  • Webhooks, tarifas e reconciliação são os mesmos do PIX Out por chave — as transações aparecem como PIX_OUT no extrato.
  • O endpoint async usa a mesma fila FIFO do PIX Out por chave — mesma garantia de ordenação e idempotência.
  • BigPix funciona igual ao existente: split em chunks de R$ 15.000 (configurável por política), tarifa cobrada uma vez por operação.

v1.26.1 (2026-04-13) - Correções de estabilidade​

Correções​

  • QR Code estático: Corrigido o valor gerado no QR code estático que, em alguns cenários, era diferente do valor solicitado.
  • Webhook pix.in.completed: Corrigido cenário em que o campo identifier não era incluído no payload do webhook para pagamentos via QR code, mesmo quando o identificador estava disponível.

v1.26.0 (2026-04-09) - Pagamento de boleto​

Novos recursos​

  • Pagamento de boleto: Novos endpoints para consultar e pagar boletos bancários, contas de serviço (concessionárias) e tributos:
    • POST /v1/accounts/{accountId}/boleto/preview — Consulta dados de um boleto pelo código de barras ou linha digitável. Retorna beneficiário, banco, valor original, juros, multa, desconto e valor total atualizado.
    • POST /v1/accounts/{accountId}/boleto/pay — Efetua o pagamento de um boleto. Retorna paymentId com status PROCESSING.
    • GET /v1/accounts/{accountId}/boleto/payments/{paymentId} — Consulta o status de um pagamento de boleto. O status evolui de PROCESSING para COMPLETED ou FAILED.
  • Novo tipo de transação BOLETO_PAYMENT: Pagamentos de boleto aparecem no extrato como transações de saída (direction: OUT, transactionType: BOLETO_PAYMENT).
  • Feature flag boleto_payment: A funcionalidade é controlada por feature flag no tenant_configs. Deve ser habilitada pelo admin para cada tenant que deseja utilizar.

Observações​

  • Boletos bancários (47 dígitos), contas de concessionárias (48 dígitos) e tributos são automaticamente classificados pelo tipo (boleto, utility, tax).
  • O pagamento é assíncrono — após o POST /boleto/pay, o integrador deve fazer polling no GET /boleto/payments/{paymentId} para acompanhar o status.
  • Cancelamento de boleto e agendamento para data futura serão implementados em versão futura.

v1.25.1 (2026-04-02) - Referência da transação original em fee.charged e melhorias de devoluções​

Melhorias​

  • Webhook fee.charged enriquecido: O payload agora inclui os campos originTransactionType (tipo da transação que originou a tarifa, ex: PIX_IN, PIX_OUT) e originTransactionRef (E2E ID da transação original). Também inclui a description completa com detalhes do cálculo.
  • Webhook pix.in.completed com identifier para QR codes dinâmicos: Corrigido cenário onde o identifier do QR code não era incluído no webhook quando a confirmação do pagamento chegava antes da notificação de cobrança.
  • Devoluções mais resilientes: Corrigido cenário onde a devolução era processada com sucesso pelo parceiro bancário mas a API retornava erro temporário. A API agora detecta a confirmação via webhook e retorna o D-code corretamente.

v1.25.0 (2026-03-26) - Campo payerDescription, webhooks de tarifas e correções de devoluções​

Novos recursos​

  • Campo payerDescription no extrato e webhooks: O endpoint GET /v1/accounts/{accountId}/statement e os webhooks pix.in.completed, pix.out.completed, qrcode.paid e transfer.internal.* agora retornam o campo opcional payerDescription. Ele contém a mensagem que o pagador digitou ao fazer o PIX (quando disponível). O campo description continua com o formato padronizado descritivo ("PIX Recebido - Nome do Pagador").
  • Webhooks fee.charged e fee.refunded: Tarifas bancárias agora geram webhooks fee.charged (ao serem cobradas) e fee.refunded (ao serem estornadas). Para receber, adicione esses tipos à sua assinatura de webhook.

Melhorias​

  • Webhooks PIX IN mais completos: Os webhooks pix.in.completed agora sempre contêm dados completos: reconciliationId, payerDescription, dados do pagador e chave PIX. Anteriormente, em alguns cenários o webhook podia chegar com dados parciais.

Correções​

  • Webhooks de devolução (PIX refund): Corrigido um cenário onde o webhook pix.refund.completed não era entregue ao integrador quando a confirmação da devolução era recebida logo após a criação.
  • Webhooks de PIX em transferências internas (CORPX-CORPX): Corrigido o tipo de evento para transferências entre contas CORPX. Antes, o destinatário podia receber pix.out.completed ao invés de pix.in.completed.
  • reconciliationId em QR codes estáticos: Corrigido cenário onde o reconciliationId não era incluído no webhook pix.in.completed para pagamentos de QR codes estáticos.
  • Filtro por status no extrato: Corrigido o filtro status no endpoint de extrato que em alguns cenários não retornava resultados corretamente.

v1.24.1 (2026-03-18) - Semântica de erros (redução de 502 genérico)​

Melhorias​

  • Padronizamos o retorno de erros originados no parceiro para códigos HTTP semânticos em endpoints de pix/keys, pix/key/{pixKey} (DICT), pix/limits, pix/out/qr-code, pix/out/qr-code/decode, pix/med, transfers/internal, accreditations e accounts/{accountId}/balance.
  • O formato de erro permanece estável: { "errorCode": "...", "message": "..." }.
  • OpenAPI e Postman foram atualizados para refletir os novos formatos/status de erro por endpoint.

Mapeamento de erros alterados (de -> para)​

Erro / cenárioAntesAgora
Timeout no Pix Out síncrono (POST /pix/out)504 Gateway Timeout207 Multi-Status (partner_timeout)
pix_key_not_found no Pix Out síncrono (POST /pix/out)502 Bad Gateway422 Unprocessable Entity
partner_error genérico em falhas de negócio/validação (PIX/Transfers/MED/Accreditations)502 Bad Gateway422 Unprocessable Entity
pix_key_lookup_failed (falha DICT/parceiro classificada)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 (endpoints com timeout upstream)502 Bad Gateway504 Gateway Timeout
account_not_found em fluxos integrados ao parceiro502 Bad Gateway404 Not Found
pix_key_not_found no DICT lookup (GET /pix/key/{pixKey})502 Bad Gateway404 Not Found
Fallback não classificado502 Bad Gateway502 Bad Gateway (mantido como fallback)

v1.24.0 (2026-03-18) - Pix Out síncrono: rate limit por conta e timeout 207​

Breaking Changes​

  • Mudança de status em timeout no Pix Out síncrono: o endpoint POST /v1/accounts/{accountId}/pix/out agora retorna HTTP 207 (partner_timeout) em timeouts do parceiro, em vez de HTTP 504.
  • O comportamento esperado permanece: o PIX pode ter sido enviado; confirme no extrato/status do pagamento antes de reenviar.

Melhorias​

  • Rate limit por conta no Pix Out síncrono: aplicado limite por conta (default atual 100 req/min, com possibilidade de customização por policy).
  • Próximos dias: o default das requisições síncronas será ajustado para 10 req/min.
  • Quando o limite é excedido, a API retorna 429 rate_limit_exceeded com campos de contexto (currentRateLimit, scope) e orientação para fluxo assíncrono.
  • Novo endpoint assíncrono de cashout: POST /v1/accounts/{accountId}/pix/out/async agenda o pagamento e retorna 202 imediato com paymentId para rastreio.
  • BigPix sempre assíncrono: POST /v1/accounts/{accountId}/pix/out/bigpix agora agenda no fluxo assíncrono (mesmo comportamento do endpoint /async), sem execução síncrona.

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

Novas funcionalidades​

  • Consulta/decodificação de QR Code PIX: Novo endpoint POST /v1/accounts/{accountId}/pix/out/qr-code/decode permite decodificar um QR Code PIX (string EMV) e visualizar os dados do beneficiário antes de efetuar o pagamento. Retorna: nome, documento, valor, chave PIX, banco e tipo de conta do destinatário. Útil para exibir uma tela de confirmação ao usuário antes de pagar.

v1.22.0 (2026-03-07) - Transferência interna por documento e por agência/conta​

Novas funcionalidades​

  • Transferência interna por documento (CPF/CNPJ): Novo endpoint POST /v1/accounts/{accountId}/transfers/internal/by-document permite criar transferências internas identificando a conta de destino pelo CPF ou CNPJ do titular. Funciona para qualquer conta no ecossistema bancário, não apenas contas registradas na API. Campos obrigatórios: document, value, description.

  • Transferência interna por agência e conta: Novo endpoint POST /v1/accounts/{accountId}/transfers/internal/by-bank-account permite criar transferências internas identificando a conta de destino por agência (branch) e número da conta (accountNumber). Funciona apenas para contas registradas na API (mesmo tenant). Para transferir para contas externas, use o endpoint /by-document.

v1.20.0 (2026-03-01) - Validação de propriedade de conta​

Melhorias​

  • Validação reforçada de propriedade de conta: A API agora verifica que o accountId presente na requisição pertence ao tenant autenticado. Integradores que acessam apenas suas próprias contas não são afetados. Essa melhoria reforça a segurança contra acessos indevidos entre contas.

v1.19.1 (2026-02-26) - Melhoria no BigPix​

Melhorias​

  • BigPix (POST /v1/accounts/{accountId}/pix/out/bigpix): aprimoramos a robustez do processamento das parcelas para maior consistência em cenários de alto volume.

v1.19.0 (2026-02-26) - Timeline de transação​

Novas funcionalidades​

  • Timeline de transação: Novo endpoint GET /v1/accounts/{accountId}/transactions/timeline retorna a linha do tempo de uma transação (por endToEndId ou identifier). Inclui: confirmações BACEN (texto resumido), webhooks enviados ao cliente (com payload completo para "Ver payload completo"), tarifas, estornos e ciclo de vida do QR Code quando aplicável. Exatamente um dos parâmetros de query é obrigatório: endToEndId ou identifier. Nenhuma alteração em endpoints ou formatos existentes.

v1.18.0 (2026-02-24) - Otimizações de performance e tarifas independentes​

Melhorias​

  • Tarifas como transações independentes: Tarifas cobradas pela API agora aparecem como linhas separadas no extrato, com link para a transação original. Consultas de QR Code e pagamentos agora incluem detalhes de tarifas (fees, totalFees).
  • Otimizações de performance: Processamento em lote paralelo para reconciliação, suporte a maior volume de transações simultâneas.
  • Retry automático de tarifas pendentes: O processo de self-healing agora inclui retry de tarifas que falharam na cobrança inicial.

Correções​

  • Corrigido cálculo de taxas de disputas (MED) que contava transações e disputas em dobro.
  • Corrigida cobrança de tarifas que podia falhar silenciosamente em cenários de alta concorrência.

v1.17.0 (2026-02-22) - Reconciliação automática e correção de status de transações​

Melhorias​

  • Reconciliação automática (Self-Healing): QR Codes expirados são agora marcados automaticamente. QR Codes pagos e pagamentos pendentes são reconciliados periodicamente com o extrato, garantindo consistência mesmo em caso de falhas pontuais de comunicação.
  • Correção de status de transações: Transações PIX que já atingiram um status final (SUCCESS, FAILED, REVERSED) não podem mais ser sobrescritas por webhooks atrasados, eliminando casos raros onde uma transação concluída poderia temporariamente aparecer como pendente.

v1.16.2 (2026-02-21) - Consultas enriquecidas de QR Code e Pagamentos​

Melhorias​

  • Os endpoints de consulta de QR Code (GET /v1/accounts/{accountId}/pix/qr-code/lookup) e pagamento (GET /v1/accounts/{accountId}/pix/payments/lookup, GET /v1/accounts/{accountId}/pix/payments/{paymentId}) agora retornam um objeto transaction enriquecido quando a transação está reconciliada.
  • O objeto transaction inclui: status detalhado, payer/payee completos, saldo após transação, informações de tarifa cobrada, disputas (MED), violações de política, referências de refund e motivo de erro (quando aplicável).

v1.16.1 (2026-02-21) - Correções de respostas de parceiro​

Correções​

  • Corrigido erro HTTP 502 ao deletar chave PIX (DELETE /v1/accounts/{accountId}/pix/keys/{pixKey}). A operação era concluída com sucesso, mas a resposta da API retornava erro incorretamente.
  • Corrigido erro HTTP 502 ao solicitar devolução/refund (POST /v1/accounts/{accountId}/pix/refund). A devolução era processada com sucesso, mas a resposta da API retornava erro incorretamente.
  • Melhorias gerais no tratamento de respostas do parceiro para todas as operações PIX.

v1.16.0 (2026-02-20) - Endpoints de Lookup e Paginação de Pagamentos​

Novas Funcionalidades​

Endpoints de Lookup (busca de item único)​

  • Novo endpoint GET /v1/accounts/{accountId}/pix/qr-code/lookup para busca de QR Code por:
    • ?identifier=X -- identificador fornecido na criação
    • ?qrcodeId=X -- ID interno do QR Code (txid)
    • ?endToEndId=X -- código E2E do BACEN (quando o QR foi pago)
  • Novo endpoint GET /v1/accounts/{accountId}/pix/payments/lookup para busca de pagamento por:
    • ?paymentId=X -- ID do pagamento
    • ?identifier=X -- identificador fornecido na criação
    • ?endToEndId=X -- código E2E do BACEN
  • Apenas um parâmetro pode ser enviado por vez em ambos os endpoints.

Paginação na listagem de Pagamentos​

  • O endpoint GET /v1/accounts/{accountId}/payments agora suporta paginação:
    • ?page=0&size=50 (padrão: page=0, size=50, máximo: 200)
    • Resposta inclui: totalElements, totalPages, page, size, hasNext, hasPrevious

Paginação na listagem de QR Codes​

  • O endpoint GET /v1/accounts/{accountId}/pix/qr-codes agora suporta paginação:
    • ?page=0&size=50&status=PAID (padrão: page=0, size=50, máximo: 200)
    • Resposta inclui: totalElements, totalPages, page, size, hasNext, hasPrevious

Padronização de rotas​

  • Novo alias POST /v1/accounts/{accountId}/pix/out/qr-code (com hífen, padrão recomendado).

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 (sem hífen) → use /pix/out/qr-code (com hífen)
  • Rotas antigas continuam funcionando mas serão removidas em versão futura.

v1.15.0 (2026-02-20) - Campo method nos webhooks e reconciliacao de refunds​

Novas Funcionalidades​

Campo method nos webhooks PIX​

  • Os webhooks pix.in.completed, pix.out.completed e pix.out.failed agora incluem o campo method no data, indicando a forma de pagamento/recebimento.
  • PIX IN: PIX_KEY, QR_CODE_STATIC, QR_CODE_DYNAMIC, REFUND_RECEIVED
  • PIX OUT: PAYMENT, REFUND_PIX_KEY, REFUND_QR_STATIC, REFUND_QR_DYNAMIC

Objetos contextuais nos webhooks​

  • Quando o PIX IN foi recebido via QR Code, o webhook inclui o objeto qrCode com txid, identifier, type e value.
  • Quando o PIX OUT foi criado via API, o webhook inclui o objeto payment com paymentId, identifier e reconciled.

Reconciliacao de refunds com QR Codes​

  • Refunds de PIX recebidos via QR Code agora atualizam automaticamente o registro do QR Code com os detalhes do refund.
  • O endpoint de consulta de QR Code (GET /v1/accounts/{accountId}/pix/qr-code) retorna a lista completa de refunds no campo refunds[].

Deprecated​

  • qrcode.paid: use pix.in.completed com method: QR_CODE_DYNAMIC ou QR_CODE_STATIC. Sera removido em versao futura.
  • payment.sent: use pix.out.completed com method: PAYMENT e objeto payment. Sera removido em versao futura.
  • payment.refunded: use pix.out.completed com method: REFUND_*. Sera removido em versao futura.

v1.14.0 (2026-01-16) - BigPix: Transferências de alto valor​

Novas Funcionalidades​

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

  • Novo endpoint para transferências PIX acima do limite individual (R$15.000 por padrão).
  • Divide automaticamente o valor em múltiplas transferências menores, executadas em paralelo.
  • Cada parcela inclui identificação no formato PIX X/Y - Total R$... - mensagem [id].
  • Se o campo identifier for fornecido, cada parcela recebe identifier__X/Y.
  • Resposta consolidada com status FULL (todas ok), PARTIAL (algumas falharam) ou FAILED (nenhuma executou).
  • Inclui contagem de retries por parcela e detalhes individuais (E2E ID, status, erro).
  • Tamanho do chunk configurável por tenant via política pixOut.chunkSize.

v1.13.2 (2026-01-16) - Melhorias na entrega de webhooks​

Melhorias​

  • Novas assinaturas de webhook passam a ter headers redundantes removidos antes do envio ao destinatário.

v1.13.1 (2026-02-19) - Remoção de qrCodeFormat e Fluxo de Aprovação​

Breaking Changes​

Campo qrCodeFormat removido dos endpoints de QR Code​

  • O campo qrCodeFormat foi removido dos endpoints de criação de QR Code dinâmico e estático.
  • A API agora sempre retorna o QR Code no formato EMV (copy-and-paste). O formato IMAGE não é mais suportado.
  • Requisições que ainda enviem qrCodeFormat no body não receberão erro, mas o campo será ignorado.

Novas Funcionalidades​

Fluxo de Aprovação de Pagamentos​

  • Quando a política requireApprovalAbove está configurada, pagamentos PIX Out acima do limite agora criam uma intenção de pagamento com status PENDING_APPROVAL em vez de serem rejeitados.
  • Administradores podem aprovar ou rejeitar pagamentos pendentes via painel de administração.
  • Ao aprovar, o pagamento é executado automaticamente. Ao rejeitar, o motivo é registrado.

v1.13.0 (2026-02-18) - Disputas (MED), Políticas com Enforcement e Contestação​

Novas Funcionalidades​

Gestão de Disputas (MED)​

  • Novo sistema de gestão de disputas MED com reconciliação automática de MEDs com transações via E2E ID.
  • Dados da MED (status, prazo, reclamante, motivo) agora aparecem vinculados à transação no extrato.
  • Monitoramento de taxa de MED: estatísticas diárias de proporção MED/PIX-In por tenant.
  • Novos endpoints:
    • GET /v1/backoffice/tenants/{tenantId}/med-stats - Estatísticas diárias de MED.
    • POST /v1/accounts/{accountId}/pix/med/{medId}/answer - Contestação de MED com resposta e evidências.
    • POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/upload-url - Upload de arquivos de evidência.

Enforcement de Políticas PIX In​

  • As regras de PIX In agora são aplicadas em tempo real (anteriormente apenas registravam violações).
  • Ação AUTO_REFUND agora inicia o estorno automático da transação que violou a política.
  • Violações de política aparecem no extrato com detalhes da regra, ação e mensagem.

Novas Regras de Política​

  • PIX In: Blacklist de códigos de banco, restrição de mesma titularidade.
  • PIX Out: Whitelist agora é avaliada antes de blacklist (whitelist anula todas as outras regras).
  • MED: Auto-bloqueio de saldo para MEDs acima de um valor, limite de taxa MED/PIX-In com ações configuráveis.

Melhorias​

  • Documentação: novo guia de Políticas e Regras com detalhes de todas as regras e ordem de avaliação.
  • Documentação: novo guia de Disputas (MED) com ciclo de vida, contestação e monitoramento.

v1.12.1 (2026-02-18) - Refund Reason Obrigatório e Correção de Paginação​

Novas Funcionalidades​

  • Novo endpoint GET /v1/accounts/{accountId}/pix/key/{pixKey} para consulta DICT com cache de 24h e rate limiting configurável.

Breaking Changes​

Campo reason agora obrigatório no endpoint de devolução​

  • O endpoint POST /v1/accounts/{accountId}/pix/out/refund agora exige o campo reason com um dos valores: USER_REQUESTED, FRAUD, BANK_ERROR, CASHIER_ERROR, CUSTOMER_REQUEST.
  • Requisições sem reason ou com valor inválido retornarão HTTP 400.

Melhorias​

  • Header X-API-Version incluído em todas as respostas da API para facilitar debug de versão.

Correções​

  • Corrigido: paginação do extrato ficava em branco a partir da página 11 (mais de 1000 transações).

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

Novas Funcionalidades​

Motor de Políticas​

  • Novo sistema de políticas configuráveis por tenant e por conta, com hierarquia (padrão -> tenant -> conta).
  • Regras disponíveis:
    • PIX Out: limite por transação, limite noturno, tipos de pessoa permitidos (PF/PJ), whitelist/blacklist de CPF/CNPJ, horário de operação.
    • PIX In: limite de valor, quarentena automática, ação configurável por violação (QUARANTINE, AUTO_REFUND, ALLOW_AND_NOTIFY).
    • QR Code: permissões por tipo (dinâmico/estático), limites de valor.
    • Chaves PIX: limite de número de chaves por conta.
    • Estorno: habilitação e limite de valor.
    • Horário de operação: janela de horário permitido com suporte a janelas noturnas.

v1.11.1 (2026-02-15) - Correções no Extrato​

Correções​

  • Corrigido: paginação do endpoint de extrato (GET /v1/accounts/{accountId}/statement) não funcionava corretamente. Parâmetros page e size agora retornam a página solicitada.
  • Corrigido: descrições padronizadas no extrato (ex: "Transferência Pix", "Devolução Pix", "Tarifa Bancária", "Pagamento de QR Code").
  • Corrigido: ordenação de transações no extrato quando tarifas e transações ocorriam no mesmo instante.

v1.11.0 (2026-02-15) - Tarifas Bancárias no Extrato e Webhook fee.charged​

Novas Funcionalidades​

Tarifas no Extrato​

  • Tarifas bancárias cobradas por transação agora aparecem no extrato (GET /v1/accounts/{accountId}/statement) com tipo FEE.
  • Cada tarifa inclui o campo feeServiceType indicando qual operação gerou a cobrança (ex: PIX_OUT, PIX_IN).

Evento de Webhook fee.charged​

  • Novo tipo de evento disponível para assinatura: fee.charged.
  • Enviado em tempo real quando uma tarifa bancária é cobrada na conta.
  • Payload inclui: amount, currency, feeServiceType, description, chargedAt.

v1.10.0 (2026-02-13) - Reconciliation ID, Suporte a Devoluções via Reversal​

Novas Funcionalidades​

Reconciliation ID​

  • Todos os webhooks enviados ao integrador (qrcode.paid, pix.in.completed, pix.out.completed, pix.out.failed, pix.refund.completed, pix.refund.failed) agora incluem o campo reconciliationId quando disponível.
  • O campo reconciliationId também é retornado no endpoint de extrato (GET /v1/accounts/{accountId}/statement), permitindo cruzamento com extratos bancários.

Suporte a Devoluções (PIX Reversal)​

  • A API agora processa devoluções PIX iniciadas pelo destinatário (PIX Reversal). Quando o destinatário de um PIX Out devolve o valor, a transação é registrada automaticamente no extrato e vinculada ao pagamento original.
  • O status do pagamento original é atualizado para REFUNDED quando o valor total é devolvido.

Correções​

  • Corrigido: webhook qrcode.paid agora inclui dados completos de payer e payee (nome, documento, banco, agência, conta), igual ao pix.in.completed.
  • Corrigido: valores monetários no extrato sincronizado estavam incorretos (divisão duplicada).

v1.9.0 (2026-02-13) - Lifecycle de Pagamentos, Correções de QR Code e Webhooks​

Novas Funcionalidades​

Lifecycle Completo de Pagamentos (PIX Out)​

  • Pagamentos (PIX Out) agora possuem ciclo de vida completo com rastreamento de reconciliação.
  • A resposta do endpoint GET /v1/accounts/{accountId}/payments agora inclui:
    • reconciled: indica se o pagamento foi confirmado pelo parceiro bancário.
    • reconciledAt: data/hora da confirmação.
    • transactionId: vincula o pagamento à transação confirmada no extrato.
  • Status do pagamento: CREATED → PENDING → COMPLETED (ou FAILED).

Dados Completos de Payer/Payee nos Webhooks​

  • Webhooks pix.in.completed e qrcode.paid agora incluem dados completos do pagador e recebedor (nome, documento, banco, agência, conta, chave PIX).

Validação de Tipos de Evento​

  • Ao criar ou atualizar uma subscription de webhook, os tipos de evento são validados contra a lista oficial. Tipos de evento inválidos ou legados são rejeitados com HTTP 400.

Correções​

  • Corrigido: PIX Out não retornava o campo endToEndId e currency na resposta.
  • Corrigido: QR Code estático falhava ao ser gerado devido a mudança no formato do parceiro bancário.
  • Corrigido: campo clientId removido do QR Code estático (não era utilizado).

v1.8.0 (2026-02-11) - Extrato Enriquecido e Correção de Assinatura de Webhook​

Novas Funcionalidades​

Extrato com Detalhes Completos da Transação​

  • O endpoint de extrato (GET /v1/accounts/{accountId}/statement) agora retorna informações completas de cada transação:
    • transactionType: Tipo da transação (PIX_IN, PIX_OUT, QR_CODE_PAYMENT, PIX_REFUND).
    • method: Método de pagamento (KEY, STATIC_QR_CODE, DYNAMIC_QR_CODE, MANUAL).
    • status: Status atual (SUCCESS, FAILED, PENDING, REFUNDED).
    • direction: Direção (IN ou OUT).
    • identifier: Identificador fornecido pelo integrador.
    • payer / payee: Dados completos do pagador e recebedor (nome, documento, banco, agência, conta, chave PIX).
    • originalEndToEnd / refundEndToEndIds: Vinculação entre devoluções e transações originais.
    • qrcodeId / qrcodeIdentifier: Reconciliação com QR Codes.

Correções​

  • Corrigido: assinatura HMAC de webhooks não era aplicada corretamente em alguns cenários de atualização de subscription.

v1.7.0 (2026-02-11) - Formato de Webhook, Autenticação Configurável e Assinatura HMAC​

Breaking Changes​

Formato do Payload de Webhook​

  • O body do webhook agora segue o formato envelope documentado diretamente: { id, type, occurredAt, schemaVersion, environment, accountId, data }.
  • Campos redundantes foram removidos. O payload agora contém apenas os dados documentados.
  • Adicionados campos tenantId e eventType no nível raiz para facilitar o roteamento.

Assinatura de Webhook​

  • A assinatura agora é enviada no header X-Signature como base64(HMAC_SHA256(secret, raw_body)).
  • O formato anterior (hex(HMAC_SHA256(secret, timestamp + "." + body)) com header X-Timestamp) foi descontinuado.
  • Os headers X-Timestamp, X-Webhook-Event e X-Webhook-ID não são mais enviados.

Novas Funcionalidades​

Autenticação Configurável por Subscription​

  • Agora o integrador pode escolher o método de autenticação para cada webhook subscription:
    • HMAC (recomendado): Assinatura HMAC-SHA256 no header X-Signature.
    • API_KEY: Chave estática em header configurável (padrão: X-API-Key).
    • BASIC: Autenticação HTTP Basic (Authorization: Basic ...).
    • BEARER: Token Bearer (Authorization: Bearer ...).
    • NONE: Sem autenticação (não recomendado para produção).
  • Configuração feita pelo Painel do Integrador em Webhooks > Editar Subscription.

Melhorias​

  • Documentação de webhooks completamente reescrita com exemplos de verificação de assinatura em Node.js, Python e Go.
  • Documentação traduzida para Português (locale principal).

Correções​

  • Corrigido: em alguns casos a autenticação configurada para webhooks não estava sendo aplicada corretamente na entrega.

v1.6.0 (2026-02-06) - Padronização de Moeda, Sincronização de Extrato e Validação de Valores​

Novas Funcionalidades​

Melhorias​

Padronização de Moeda​

  • Todos os valores monetários na API agora estão claramente documentados como BRL (REAIS) com no máximo 2 casas decimais (precisão de centavos).
  • Exemplo: 150.75 representa R$150,75.
  • Valores com mais de 2 casas decimais agora são rejeitados com HTTP 400 e uma mensagem de erro clara.
  • Atualizadas todas as descrições de campos OpenAPI com o padrão BRL.
  • Corrigida a criação de QR Code Estático para aceitar valores em REAIS (anteriormente exigia centavos).

Detalhes Aprimorados de Transação​

  • Adicionado campo transactionType nas respostas de transação (PIX_IN, PIX_OUT, QR_CODE_PAYMENT, PIX_REFUND).
  • Adicionado campo pixKey nos detalhes de pagador/recebedor.
  • Corrigida a classificação de QR Code Estático/Dinâmico no extrato.

v1.5.0 (2026-02-05) - Padronização de URLs, API de Pagamentos e Correção de QR Code​

Breaking Changes​

Padronização de URLs​

Todos os endpoints que anteriormente usavam accountId como parâmetro de query agora usam como parâmetro de path sob /v1/accounts/{accountId}/.... Isso fornece padrões de URL RESTful consistentes em toda a API.

Guia de migração:

URL AntigaURL Nova
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

Nota: As URLs legadas continuam funcionando para compatibilidade retroativa, mas estão depreciadas e serão removidas em uma versão futura.

Novas Funcionalidades​

API de Pagamentos​

  • GET /v1/accounts/{accountId}/payments: Lista todas as intenções de pagamento PIX Out.
  • GET /v1/accounts/{accountId}/payments/{paymentId}: Consulta detalhes de um pagamento.

Correções de Bugs​

Conciliação de QR Code​

  • Corrigida uma race condition onde pagamentos de QR code não eram vinculados às suas transações quando o webhook de cobrança chegava antes do webhook PIX.

v1.4.0 (2026-01-16) - Padronização de Tipos de Evento de Webhook e Documentação​

Novas Funcionalidades​

Melhorias nos Tipos de Evento de Webhook​

  • Novo evento pix.med.updated: Notificação quando o status de um MED/infração é atualizado.
  • Diferenciação aprimorada de PIX IN/OUT: Distinção mais clara entre eventos PIX de entrada e saída.

Tipos de Evento Padronizados​

Os seguintes tipos de evento agora são consistentes em todos os sistemas:

  • pix.in.completed - PIX de entrada concluído
  • pix.out.completed - PIX de saída concluído
  • pix.out.failed - PIX de saída falhou
  • qrcode.paid - QR Code foi pago
  • pix.refund.completed - Devolução concluída
  • pix.refund.failed - Devolução falhou
  • pix.med.opened - MED/Infração aberta
  • pix.med.updated - MED/Infração atualizada

Documentação​

  • Tradução completa para inglês: Especificação OpenAPI e coleção Postman agora estão totalmente em inglês.
  • Documentação de tipos de evento atualizada: Toda a documentação de webhooks atualizada com os tipos de evento padronizados.
  • Melhorias de consistência: Tipos de evento agora são consistentes entre frontend, handlers da API e documentação.

Breaking Changes​

  • Tipos de evento legados (pix.received, pix.cash_in, pix.cash_out) estão depreciados em favor dos novos tipos padronizados.
  • Assinaturas de webhook existentes usando tipos de evento antigos continuarão funcionando, mas devem ser migradas.

v1.3.0 (2026-01-29) - Estatísticas de QR Code e Webhooks de Cobrança​

Novas Funcionalidades​

Estatísticas de QR Code​

  • Novo endpoint GET /v1/pix/qr-codes/stats: Retorna estatísticas agregadas de QR Code das últimas 24 horas.
    • Número de QR Codes gerados, pagos e devolvidos
    • Valores totais (gerados, pagos, devolvidos)
    • Taxa de conversão (pagos/gerados)
    • Dados agregados por hora para análise de tendência

Webhooks de Cobrança (COB)​

  • Notificações de pagamento de QR Code: Quando um QR Code dinâmico é pago, o sistema atualiza automaticamente o status do QR Code para PAID e notifica via webhook.
  • Evento qrcode.paid: Webhook enviado quando um QR Code é confirmado como pago pelo BACEN.
  • Registro automático de webhook: Ao criar uma chave PIX, o webhook de cobrança é registrado automaticamente para receber notificações de pagamento.

Correções de Bugs​

  • Corrigida a exibição de valores de saldo.
  • Corrigidos valores de transações no extrato.

Documentação​

  • Adicionado endpoint de estatísticas de QR Code à especificação OpenAPI.
  • Atualizada a coleção Postman com o novo endpoint de estatísticas.

v1.2.0 (2026-01-27) - Portal do Integrador e Webhooks​

Novas Funcionalidades​

  • Portal do Integrador: Documentação adicionada com link do portal e funcionalidades.

Alterações​

  • Webhooks via Portal: A configuração de webhooks agora ocorre exclusivamente pelo Portal do Integrador.
  • Documentação ajustada: Removidas referências a endpoints públicos de gerenciamento de webhooks; apenas POST /webhooks/replay e GET /v1/webhooks/events mantidos.

v1.1.0 (2026-01-27) - Gerenciamento de Webhooks via API​

Novas Funcionalidades​

Webhooks Self-Service​

  • CRUD de Webhook via API: Agora você pode criar, listar, atualizar e excluir configurações de webhook diretamente via API sem precisar contatar o suporte.
  • Múltiplos Tipos de Autenticação: Suporte para HMAC, API_KEY, BASIC, BEARER e IP_WHITELIST para autenticação de webhooks.
  • Filtro por Tipo de Evento: Configure quais tipos de evento cada webhook deve receber.
  • Endpoint de Eventos Disponíveis: Novo endpoint GET /v1/webhooks/events para listar todos os tipos de evento suportados.

Novos Eventos de Webhook​

  • pix.pending: Novo evento enviado quando um Pix está pendente de confirmação (útil para rastreamento de pagamento em tempo real).
  • pix.qrcode.cash_in: Evento específico para pagamentos de QR Code via cobrança.

Segurança​

  • Restrição de IP para Webhooks: Endpoints de webhook agora suportam restrição de IP de origem.

Correções de Bugs​

  • Documentação de webhooks aprimorada com exemplos mais detalhados.
  • Corrigidos exemplos de payload em eventos de webhook.

v1.0.0 (2025-12-29) - Lançamento Inicial (API CorpX)​

Esta é a primeira versão oficial da documentação pública unificada da API CorpX, focada em integradores externos e parceiros bancários.

Principais Funcionalidades​

Pix e Pagamentos​

  • Pix Out: Transferências instantâneas usando chaves Pix em um único passo.
  • QR Codes: Geração de QR Code dinâmico e estático, com suporte para captura, consulta de status e cancelamento.
  • Devoluções: Fluxo de devolução para Pix recebidos.
  • Pix MED: Suporte completo ao Mecanismo Especial de Devolução para gestão de infrações e disputas.

Gestão de Conta​

  • Consulta de Saldo: Visualização detalhada de saldo total, disponível e bloqueado.
  • Extrato: Histórico paginado de transações e movimentações da conta.
  • Transferências Internas: Movimentação P2P de recursos entre contas na mesma plataforma.

Webhooks e Notificações​

  • Notificações de Saída: Recepção automática de eventos (Pix recebido, Pix enviado, atualizações de MED).
  • Segurança: Assinatura HMAC-SHA256 em todas as notificações para garantia de origem.
  • Retries: Sistema automático de retry com exponential backoff.
  • Replay Self-Service: Endpoints para solicitar reenvio de notificações (Individual ou em Lote) via API.

Segurança e Idempotência​

  • Autenticação: OAuth2 via Identity Provider (fluxos client_credentials e authorization_code).
  • Idempotência: Garantia de execução única para operações mutáveis via header Idempotency-Key.
  • Assinatura de Transação: Todas as operações de transferência Pix são protegidas por assinaturas RSA-SHA512.

Suporte Multi-idioma​

  • Documentação disponível em Português, Inglês e Chinês Simplificado.

Experiência do Desenvolvedor​

  • OpenAPI 3.0: Especificação completa disponível para download e Swagger UI interativo.
  • Coleção Postman: Coleção pronta para uso para testes no ambiente Sandbox.
  • Guia do Integrador: Documentação detalhada sobre headers, erros e boas práticas.