Pular para o conteúdo principal

Changelog

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

v2.1.0 (2026-05-04) - Endpoints novos, polling proativo e status TIMEOUT​

Esta versão da documentação reflete a API verde (tenant.api.corpx.com). A API azul (api.corpxapi.com / api2.brxbank.com.br) e sua doc correspondente (docs.corpxapi.com) continuam live e inalteradas.

Novos endpoints públicos​

URL
API basehttps://tenant.api.corpx.com
OAuth token endpoint (M2M client_credentials)https://auth.api.corpx.com/oauth2/token
Documentaçãohttps://docs.api.corpx.com

A autenticação para integrações server-to-server agora usa o flow OAuth 2.0 client_credentials padrão. Sua aplicação troca client_id/client_secret por um access token de 1 hora:

curl -s -X POST "https://auth.api.corpx.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=api2/read+api2/write"

Esse token é apresentado no header Authorization: Bearer <token> em todas as chamadas. O header X-Tenant-Id continua obrigatório.

amount aceita number ou string​

O campo amount em POST /pix/out, POST /pix/out/async, POST /pix/out/bigpix, POST /locked-balance/lock, POST /pix-out e similares passa a aceitar ambos os formatos no JSON:

{ "amount": 0.01 }
{ "amount": "0.01" }

A representação interna preserva precisão (não há conversão para float64 intermediário). Recomendamos string para valores acima de R$ 9.999,99 para evitar arredondamento IEEE-754 do lado do cliente.

POST /pix/out: novo status TIMEOUT​

O comportamento de espera por confirmação ficou mais robusto. Quando o parceiro bancário aceita a chamada mas não confirma o status final em até 5 minutos (combinando webhook + polling ativo a cada 5s), em vez de marcar como FAILED (o que enganaria — o dinheiro pode ter saído) o status agora é TIMEOUT:

HTTP/1.1 202 Accepted
{
  "paymentId": "pay_...",
  "status": "TIMEOUT",
  "errorCode": "confirmation_timeout",
  "errorReason": "tempo de resposta do parceiro estourou. A chamada para enviar o dinheiro foi enviada com sucesso, mas a confirmação final do status ainda não chegou. Verifique o extrato da conta antes de tentar novamente — uma reemissão com a MESMA idempotency-key é segura (idempotente); reemissão com nova idempotency-key pode resultar em pagamento em duplicidade.",
  "warning": "...",
  "completedAt": "2026-05-04T22:07:13Z"
}
StatusHTTPSignificado
COMPLETED200Confirmado pelo partner
FAILED422Partner rejeitou (saldo, validação, etc) — dinheiro não saiu
TIMEOUT202Indeterminado — verifique o extrato. Reemita com a mesma Idempotency-Key para garantir não-duplicação
PENDING202Em processamento (raro; PIX BACEN tipicamente confirma em segundos)

Como tratar TIMEOUT no seu lado:

  1. Consulte GET /v1/accounts/{id}/payments/{paymentId} periodicamente até obter status final.
  2. Se quiser forçar uma reemissão, use a mesma Idempotency-Key original — a API garante o mesmo paymentId e nunca dispara o PIX duas vezes.
  3. Nunca reemita com nova Idempotency-Key sem antes confirmar pelo extrato — pode causar pagamento em duplicidade.

Resolução de status mais rápida e consistente​

A CorpX agora aplica um duplo caminho de resolução para PIX out: ouvimos o webhook do parceiro e, em paralelo, conciliamos o status diretamente com a rede a cada 5 segundos por até 5 minutos. O que chegar primeiro vence. Isso elimina os casos raros em que o webhook atrasava demais e o pagamento ficava "em PENDING" por horas.

Para QR Codes dinâmicos, a mesma conciliação proativa ocorre em janela de ~250 segundos após a criação do QR. Mesmo se um webhook do parceiro falhar, detectamos a liquidação e disparamos o seu webhook pontualmente.

Você não precisa fazer nada — seus callbacks chegam mais rápido e com status final confiável.

Mais endpoints disponíveis​

A v2.0 já trazia os endpoints de movimentação (PIX, QR, boleto, exports). A v2.1 expõe rotas adicionais que estavam só no backoffice:

EndpointMétodoDescrição
/v1/accounts/{id}/payments/{paymentId}GETDetalhes de um pagamento específico (substitui necessidade de listar e filtrar)
/v1/accounts/{id}/payments?periodHours=24&size=50GETListagem paginada de payments (payments, totalPages, hasNext, hasPrevious)
/v1/webhooks/eventsGETCatálogo de eventos suportados
/v1/security/ip-allowlistGET, PUTGerenciamento da allowlist de IPs (campo ips)

Compatibilidade​

  • Todas as rotas, payloads e webhooks da v2.0 permanecem inalterados.
  • Sua integração não precisa de mudanças para se beneficiar do polling proativo nem do tratamento de TIMEOUT (você apenas vai parar de ver PIX out marcado como FAILED indevidamente em janelas de degradação do partner).
  • Se você ainda usa a API azul (api.corpxapi.com), continua funcionando como antes — esta documentação descreve apenas o comportamento da API verde (tenant.api.corpx.com).

v2.0.0 (2026-05-03) - Nova plataforma CorpX​

A API CorpX foi reimplementada do zero sobre uma plataforma mais rápida e previsível. Nenhuma mudança é necessária do seu lado: paths, métodos HTTP, payloads de request e shapes de response permanecem os mesmos.

Ganhos visíveis para sua integração​

  • Performance de ponta: PIX out síncrono (POST /v1/accounts/{id}/pix/out) costuma responder em poucos segundos e liquidar em tempo real. Tempo médio de resposta reduziu significativamente frente ao stack anterior.
  • Alta taxa de conversão: menos rejeições transitórias — reemitimos automaticamente em degradações momentâneas da rede antes de devolver erro para você.
  • Callbacks mais rápidos: conciliamos status com a rede em paralelo aos webhooks do parceiro, então seus webhooks pix.out.*, pix.refund.* e qrcode.paid chegam com latência sub-segundo após a confirmação final.
  • Status consistentes: cada pagamento tem um único resultado final (COMPLETED, FAILED ou TIMEOUT) — sem "flapping" entre estados nem pagamentos presos em PENDING por horas.
  • Idempotência reforçada: replays do mesmo Idempotency-Key em /pix/out voltam sempre o mesmo paymentId, com garantia de não duplicação mesmo em falhas de rede agressivas.
  • Leituras mais rápidas nas rotas de listagem (/statement, /payments, /qr-codes).

Compatibilidade​

  • Mesmos paths HTTP, mesmos métodos.
  • Mesmas chaves JSON (camelCase) e mesmos formatos de data (RFC 3339 UTC).
  • Mesmas mensagens de erro ({ errorCode, message }).
  • Os mesmos webhooks (pix.in.completed, pix.out.completed, pix.out.failed, qrcode.paid, pix.refund.completed, pix.refund.failed) com a mesma assinatura HMAC SHA-256.

Status estendido em respostas​

Algumas respostas passaram a incluir um array opcional warnings:

{
  "accountId": "...",
  "total": 0,
  "locked": 0,
  "available": 0,
  "currency": "BRL",
  "warnings": ["partner_balance_unavailable"]
}

Quando presente, indica falhas parciais que não impedem a operação (graceful degradation). Em caso de uso comum, o array é omitido. Você pode tratar warnings como informativo sem alterar lógica existente.

Cutover​

A migração foi feita por tenant, sem downtime. Se você está lendo isto, seu tenant já está rodando na nova plataforma. O endpoint api.corpxapi.com continua atendendo durante a janela de transição.

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.