₱

API PIX

Plataforma de Pagamento

Plataforma Brasileira de Pagamento PIX

API da Plataforma
de Pagamento PIX

Comerciantes, contas bancárias, chaves PIX, cobranças, geração de BR Code/QR Code e confirmação de pagamento via webhook. Utiliza um MockPixProvider para desenvolvimento local; um PSP real pode ser conectado depois pela mesma interface PixProvider.

37
Endpoints REST
14
Domínios
3
Esquemas Auth
mTLS
Webhooks seguros
🏪

Comerciantes

Cadastro, consulta e gerenciamento de chaves de API para comerciantes (CPF/CNPJ).

🏦

Contas Bancárias

Registro e validação de contas (CHECKING, SAVINGS, PAYMENT) junto ao provedor PIX.

🔑

Chaves PIX

Cadastro de chaves CPF, CNPJ, EMAIL, PHONE e EVP com integração ao DICT/BCB.

💰

Cobranças PIX

Modos STATIC, DYNAMIC e LEGACY com geração de TXID, BR Code e QR Code PNG.

🔄

Pix Automático

Recorrências com 5 jornadas (JOURNEY_1-4 + OPEN_FINANCE) e 5 frequências.

↩️

Devoluções

Solicitação idempotente de devoluções e conciliação com o provedor PIX.

ARQUITETURA

🏗️Arquitetura do Sistema

Visão em camadas da plataforma, mostrando os domínios, padrões arquiteturais (Outbox, Idempotência, mTLS) e integrações externas com PSP, BCB/DICT e sistemas de pagadores.

Camada 1 · Clientes HTTPS + JSON
🏪
App do Comerciante
X-Merchant-API-Key
🛠️
Admin da Plataforma
X-API-Key
⚙️
Serviços Internos
Bearer JWT (RS256)
📱
Pagador Final
Via app bancário
API Gateway · Validação de Auth · Rate Limiting
Camada 2 · Domínios da Plataforma Spring Boot · Java 21
👤
Comerciantes
merchantCode, apiKey
🏦
Contas Bancárias
CHECKING/SAVINGS/PAYMENT
🔑
Chaves PIX
CPF/CNPJ/EMAIL/PHONE/EVP
💰
Cobranças
STATIC/DYNAMIC/LEGACY
💳
Pagamentos
PENDING/PAID/FAILED
↩️
Devoluções
idempotente + reconcile
🔄
Pix Automático
recorrências + jornadas
🛡️
Risco
avaliação consultiva
Transactional Outbox · Domain Events · Idempotency Store
Camada 3 · Infraestrutura & Integração Provider Pattern
🗄️
Persistence
PostgreSQL + Outbox Table
🔌
PixProvider (interface)
abstração do PSP
📨
Outbox Worker
retry + backoff exponencial
mTLS · REST · Webhooks · DICT API
Camada 4 · Sistemas Externos mTLS · Webhooks
🏛️
PSP Real
produção via mTLS
🧪
MockPixProvider
dev/test local
🇧🇷
BCB / DICT
registro de chaves
📲
Apps Bancários
pagador final
📬

Transactional Outbox

Persistência atômica de dados + eventos; worker assíncrono com retry e backoff exponencial.

🔁

Idempotência

Cabeçalho Idempotency-Key em cobranças e devoluções para evitar duplicatas.

🔐

mTLS nos Webhooks

Webhooks do PSP autenticados por mutual TLS, garantindo origem confiável das notificações.

🔌

Provider Pattern

Interface PixProvider abstrai PSP; MockPixProvider em dev, PSP real em produção.

FUNDAMENTOS

💡Conceitos-chave

Termos e padrões essenciais para entender a API.

🔑

TXID

Identificador único de 25-35 caracteres gerado pela plataforma para cada cobrança PIX. É o identificador usado pelo PSP e no BR Code.

📊

BR Code / EMV

String padronizada (padrão EMV) que contém todos os dados do PIX. Pode ser transformada em QR Code PNG ou copiada como "Pix Copia e Cola".

🔁

Idempotency-Key

Cabeçalho HTTP que garante que requisições repetidas com o mesmo payload retornem o mesmo resultado, sem criar duplicatas.

📬

Outbox Pattern

Eventos são persistidos atomicamente com a transação de negócio e processados assincronamente, garantindo entrega eventual consistente.

🔐

mTLS (Mutual TLS)

Autenticação bilateral por certificado digital. Usado nos webhooks do PSP para garantir que apenas o provedor autorizado envia notificações.

🧪

MockPixProvider

Implementação local do PixProvider para desenvolvimento. Simula PSP real sem movimentação financeira. Disponível apenas em perfis local/dev/test.

⚖️

Conciliação

Comparação entre expectedAmount e receivedAmount para identificar MATCHED, UNDERPAID, OVERPAID ou UNPAID.

🔄

Pix Automático

Mecanismo de recorrência oficial do BCB. Suporta 5 jornadas (JOURNEY_1-4 + OPEN_FINANCE) e políticas de retry (NAO_PERMITE / PERMITE_3R_7D).

SEGURANÇA

🔐Autenticação e Segurança

A plataforma suporta três esquemas de autenticação para diferentes cenários de uso.

Fluxo de Autenticação

📥 Requisição API
🔑 Identificar tipo de autenticação
X-API-Key → Administração
X-Merchant-API-Key → Comerciante
Bearer JWT → Serviços internos
✅ Acesso concedido / ❌ 401 Unauthorized
🔑
X-API-Key Header: X-API-Key

Chave da plataforma configurada em PIX_API_KEY. Usada nas operações administrativas e no cadastro de comerciantes fora dos perfis local/dev/test.

Admin Criação de comerciantes Risk assessments
🏪
X-Merchant-API-Key Header: X-Merchant-API-Key

Chave retornada no cadastro ou rotação da chave do comerciante. Use nas operações dos seus recursos e no Pix Automático. Informe somente o valor da chave, sem prefixo Bearer.

Operações do comerciante Pix Automático Cobranças/Pagamentos
⚙️
Bearer JWT Header: Authorization: Bearer <token>

Access token RS256 do emissor configurado. Exige identidade de serviço habilitada, serviço permitido e scope da operação. Devoluções e cobranças recorrentes exigem delegação. Não combine com chaves de API.

Serviços internos RS256 Service Identity
COMECE AGORA

⚡Quick Start

Fluxo mínimo para receber seu primeiro pagamento PIX em 4 passos.

1

Criar comerciante

POST /api/v1/merchants
Headers: X-API-Key: <platform-key>

{
  "documentType": "CNPJ",
  "documentNumber": "12345678000195",
  "legalName": "Loja Exemplo LTDA",
  "tradeName": "Loja Exemplo",
  "email": "contato@loja.com.br"
}

→ Retorna: merchantCode + apiKey
2

Registrar conta bancária e chave PIX

POST /api/v1/merchants/{merchantCode}/accounts
Headers: X-Merchant-API-Key: <merchant-key>

{
  "bankCode": "001",
  "branch": "1234",
  "accountNumber": "12345-6",
  "accountType": "CHECKING",
  "cpf": "12345678901"
}
→ Retorna: accountId

POST /api/v1/accounts/{accountId}/pix-keys
{ "type": "EVP", "value": "random-key" }
→ Retorna: pixKeyId
3

Criar cobrança PIX

POST /api/v1/pix/charges
Headers:
  X-Merchant-API-Key: <merchant-key>
  Idempotency-Key: pedido-12345

{
  "accountId": "<accountId>",
  "pixKeyId": "<pixKeyId>",
  "amount": 150.00,
  "description": "Pedido 12345",
  "expirationSeconds": 3600,
  "mode": "DYNAMIC"
}

→ Retorna: chargeId, txid, brCode, expiresAt
4

Receber pagamento via webhook

A plataforma recebe automaticamente via mTLS:

POST /api/v1/webhooks/pix/provider (mTLS)
{
  "pix": [{
    "endToEndId": "E...",
    "txid": "ABC123DEF456",
    "valor": 150.00,
    "horario": "2024-01-15T14:30:00Z"
  }]
}

→ Pagamento confirmado! Status: PAID ✅

# Em dev/test, simule com:
POST /api/v1/dev/pix/charges/{chargeId}/simulate-payment

🚀Fluxo de Onboarding

Como um comerciante é cadastrado na plataforma, registra sua conta bancária e a valida junto ao PSP.

Sequência de Onboarding

Comerciante
Plataforma
PSP
→
Comerciante → Plataforma : POST /merchants (criar)
←
Plataforma → Comerciante : merchantCode + apiKey
→
Comerciante → Plataforma : POST /accounts (registrar conta)
→
Plataforma → PSP : Validar dados bancários
←
PSP → Plataforma : Confirmação
←
Plataforma → Comerciante : Conta registrada
→
Comerciante → Plataforma : POST /accounts/{id}/validate
→
Plataforma → PSP : Validar conta no PSP
←
PSP → Plataforma : Conta validada ✓
←
Plataforma → Comerciante : Status: ACTIVE
POST/api/v1/merchants
POST/api/v1/merchants/{merchantCode}/accounts
POST/api/v1/accounts/{accountId}/validate
GET/api/v1/merchants/{merchantCode}

🔑Chaves PIX

Cadastro, listagem e desativação de chaves PIX. Suporta CPF, CNPJ, e-mail, telefone e chave aleatória (EVP).

Fluxo de Chaves PIX

Comerciante
Plataforma
BCB
→
Comerciante → Plataforma : POST /accounts/{id}/pix-keys
←
Plataforma → Comerciante : PixKeyResponse (PENDING)
→
Plataforma → BCB : Registrar chave PIX
←
BCB → Plataforma : Chave registrada
→
BCB → Plataforma : Webhook: chave ativada
←
Plataforma → Comerciante : Status: ACTIVE
→
Comerciante → Plataforma : DELETE /pix-keys/{id}
←
Plataforma → Comerciante : Soft delete (histórico preservado)
POST/api/v1/accounts/{accountId}/pix-keys
GET/api/v1/accounts/{accountId}/pix-keys
GET/api/v1/pix-keys/{pixKeyId}
DELETE/api/v1/pix-keys/{pixKeyId}

💰Cobranças PIX

Criação de cobranças com geração de TXID, consulta ao provedor para obter código de barras, e persistência. Operação idempotente via cabeçalho Idempotency-Key.

Fluxo de Criação de Cobrança

Comerciante
Plataforma
PSP
Pagador
→
Comerciante → Plataforma : POST /pix/charges (Idempotency-Key)
↻
Plataforma : Valida conta e chave PIX
↻
Plataforma : Gera TXID único
→
Plataforma → PSP : Solicita código de barras
←
PSP → Plataforma : EMV / BR Code
←
Plataforma → Comerciante : PixChargeResponse (brCode, txid)
→
Pagador → PSP : Escaneia QR Code e paga
→
PSP → Plataforma : Webhook de pagamento
←
Plataforma → Comerciante : Status: PAID ✅

💡 Idempotência: Ao repetir o mesmo Idempotency-Key com o mesmo payload, a cobrança original é retornada em vez de criar uma duplicata.

POST/api/v1/pix/charges
GET/api/v1/pix/charges/{chargeId}
GET/api/v1/pix/charges/{chargeId}/qr-code
GET/api/v1/pix/charges/{chargeId}/br-code

💳Pagamentos PIX

Fluxo de recebimento de notificações de pagamento do PSP via webhook autenticado por mTLS, processamento e confirmação.

Fluxo de Pagamento via Webhook

PSP (mTLS)
Plataforma
Banco
Outbox
→
PSP → Plataforma : POST /webhooks/pix/provider
↻
Plataforma : Valida assinatura mTLS
→
Plataforma → Banco : Busca cobrança pelo TXID
←
Banco → Plataforma : Cobrança encontrada
→
Plataforma → Banco : Registra pagamento (PAID)
→
Plataforma → Outbox : Publica evento PaymentConfirmed
←
Plataforma → PSP : 200 OK + PixPaymentResponse
→
Outbox → Plataforma : Processa e notifica comerciante

🔒 Segurança: O webhook do provedor PIX é autenticado por mTLS (mutual TLS), garantindo que apenas o PSP configurado pode enviar notificações.

POST/api/v1/webhooks/pix/provider
POST/api/v1/webhooks/pix/mock
GET/api/v1/pix/payments/by-charge/{chargeId}
GET/api/v1/pix/payments/by-charge/{chargeId}/receipts

↩️Devoluções PIX

Solicitação idempotente de devoluções de pagamentos e conciliação do estado com o provedor PIX.

Fluxo de Devolução

Comerciante
Plataforma
PSP
→
Comerciante → Plataforma : POST /payments/{id}/refunds
↻
Plataforma : Valida valor e pagamento original
→
Plataforma → PSP : Solicita devolução
←
PSP → Plataforma : refundReference
←
Plataforma → Comerciante : PixRefundResponse (PENDING)
→
PSP → Plataforma : Confirmação de devolução
↻
Plataforma : Atualiza status: COMPLETED
→
Comerciante → Plataforma : POST /refunds/{id}/reconcile
←
Plataforma → Comerciante : PixRefundResponse atualizado
POST/api/v1/pix/payments/{paymentId}/refunds
GET/api/v1/pix/payments/{paymentId}/refunds
GET/api/v1/pix/payments/{paymentId}/refunds/{refundId}
POST/api/v1/pix/payments/{paymentId}/refunds/{refundId}/reconcile

🔄Pix Automático

Fundação de recorrências, solicitações de autorização, geração de QR Codes compostos e agendamento de cobranças periódicas.

Fluxo do Pix Automático

Comerciante
Plataforma
BCB
Pagador
→
Comerciante → Plataforma : POST /pix/automatic/locations
←
Plataforma → Comerciante : locationId + location URL
→
Comerciante → Plataforma : POST /pix/automatic/recurrences
←
Plataforma → Comerciante : idRec (status: CREATED)
→
Comerciante → Plataforma : POST /recurrences/{id}/qr-code
←
Plataforma → Comerciante : QR Code composto (PNG)
→
Pagador → BCB : Escaneia QR Code
→
BCB → Plataforma : Solicitação de autorização
→
Pagador → BCB : Aprova recorrência
←
BCB → Plataforma : Autorização confirmada
←
Plataforma → Comerciante : Status: APPROVED ✅
→
Comerciante → Plataforma : POST /recurrences/{id}/charges/schedule
←
Plataforma → Comerciante : Cobranças agendadas

Frequências Suportadas

SEMANAL MENSAL TRIMESTRAL SEMESTRAL ANUAL

Jornadas

JOURNEY_1 JOURNEY_2 JOURNEY_3 JOURNEY_4 OPEN_FINANCE
POST/api/v1/pix/automatic/locations
POST/api/v1/pix/automatic/recurrences
GET/api/v1/pix/automatic/recurrences/{idRec}
GET/api/v1/pix/automatic/recurrences/{idRec}/schedule
POST/api/v1/pix/automatic/recurrences/{idRec}/qr-code
POST/api/v1/pix/automatic/recurrences/{idRec}/br-code
POST/api/v1/pix/automatic/recurrences/{idRec}/charges
POST/api/v1/pix/automatic/recurrences/{idRec}/charges/schedule
POST/api/v1/pix/automatic/recurrences/{idRec}/authorization-requests
GET/api/v1/pix/automatic/rec/{accessToken}
GET/api/v1/pix/automatic/charges/{txid}

🔔Webhooks

Notificações de pagamento recebidas do PSP (via mTLS) e do provedor mock (para desenvolvimento).

Estrutura do Webhook do Provedor (mTLS)

{
  "pix": [
    {
      "endToEndId": "E12345678901234567890123456789012",
      "txid": "ABC123DEF456",
      "valor": 150.00,
      "horario": "2024-01-15T14:30:00Z",
      "pagador": {
        "cpf": "12345678901",
        "nome": "João Silva"
      }
    }
  ]
}

Estrutura do Webhook Mock (Dev)

{
  "eventId": "evt-unique-id-123",
  "eventType": "PAYMENT_CONFIRMED",
  "txid": "ABC123DEF456",
  "amount": 150.00,
  "status": "PAID",
  "paidAt": "2024-01-15T14:30:00Z",
  "payerName": "João Silva",
  "payerDocument": "12345678901",
  "receiptId": "rcp-456"
}

Idempotência: O webhook mock é idempotente por eventId: repetir o mesmo evento nunca cria um pagamento duplicado.

📬Transactional Outbox Pattern

Padrão de outbox transacional para garantir consistência entre persistência de dados e notificações externas.

Fluxo do Transactional Outbox

Service
Database
Outbox
Worker
Webhook
→
Service → Database : BEGIN TRANSACTION
→
Service → Database : INSERT pagamento (PAID)
→
Service → Outbox : INSERT evento (PENDING)
→
Service → Database : COMMIT
→
Worker → Outbox : SELECT eventos PENDING
←
Outbox → Worker : Lista de eventos
→
Worker → Webhook : POST notificação
←
Webhook → Worker : 200 OK / 500 Error
→
Worker → Outbox : UPDATE status: SENT

Reprocessamento Manual

Eventos que falharam após todas as tentativas podem ser reprocessados manualmente:

POST /api/v1/admin/outbox/{eventId}/retry
SCHEMAS

📋Modelos de Dados

Principais schemas da API com seus campos e tipos.

PixChargeResponse
uuididrequired
stringmerchantCode
uuidaccountIdrequired
uuidpixKeyIdrequired
stringtxid
enummodeSTATIC|DYNAMIC|LEGACY
numberamountrequired
stringdescription
enumstatusACTIVE|PAID|EXPIRED|CANCELLED
stringbrCode
datetimeexpiresAt, createdAt
PixPaymentResponse
uuididrequired
uuidchargeId
stringtxid
stringreceiptId
numberamount
enumstatusPENDING|PAID|FAILED
stringpayerName
stringpayerDocument
datetimepaidAt
PixRecurrenceResponse
stringidRecrequired
int64locationId
stringreceiverCnpj, receiverName
stringcontractrequired
stringdebtorNamerequired
enumfrequencySEMANAL..ANUAL
numberrecurringAmount, minimumAmount
enumretryPolicyNAO_PERMITE|PERMITE_3R_7D
enumstatusCREATED|APPROVED|REJECTED|EXPIRED|CANCELLED
enumjourneyAWAITING|JOURNEY_1-4|OPEN_FINANCE
PixChargeReconciliationResponse
uuidchargeIdrequired
stringtxid
numberexpectedAmount
numberreceivedAmount
numberoutstandingAmount
enumchargeStatusACTIVE|PAID|EXPIRED|CANCELLED
enumreconciliationStatusUNPAID|UNDERPAID|MATCHED|OVERPAID
int64receiptCount
booleanchargeStatusConflict
MerchantResponse
stringmerchantCoderequired
enumdocumentTypeCPF|CNPJ
stringdocumentNumber
stringlegalName, tradeName
emailemail
enumstatusACTIVE|INACTIVE
stringapiKey
BankAccountResponse
uuididrequired
stringmerchantCode
stringbankCode3 dígitos
stringbranch, accountNumber
enumaccountTypeCHECKING|SAVINGS|PAYMENT
enumstatusPENDING|ACTIVE|INACTIVE|FAILED
✅
MATCHED
Valores iguais
⚠️
UNDERPAID
Recebido menor
⚠️
OVERPAID
Recebido maior
❌
UNPAID
Sem recebimento
REFERÊNCIA

📡Todos os Endpoints

Lista completa de endpoints da API organizados por grupo funcional.