Integracao PIX

Guia completo para integrar com o sistema de pagamentos instantaneos PIX, incluindo protocolo SPI, criptografia RSFN e pipeline de processamento.

Arquitetura PIX no Axon

O Axon integra com o PIX via protocolo SPI (Sistema de Pagamentos Instantaneos) do BACEN. A comunicacao e feita via mTLS com certificados ICP-Brasil e as mensagens seguem o padrao ISO 20022.

Componente	Servico Axon	Funcao
Protocolo SPI	Synapse	Comunicacao com ICOM do BACEN, parsing ISO 20022
Tokenizacao	Vault	Chaves PIX, dados sensiveis
Notificacoes	Pulse	Webhooks e eventos real-time

Mensagens SPI

O Synapse suporta 27 tipos de mensagem SPI. Os mais comuns para pagamentos:

Tipo	Fluxo	Descricao
pacs.008	Pagamento	Transferencia PIX entre instituicoes
pacs.002	Confirmacao	Status do pagamento (aceito, rejeitado, liquidado)
pacs.004	Devolucao	Devolucao de um pagamento PIX
pain.013	Cobranca	Solicitacao de pagamento (PIX Cobranca)
pain.014	Resposta	Resposta a solicitacao de pagamento
camt.055	Cancelamento	Solicitacao de cancelamento de pagamento

Identificadores PIX

Cada transacao PIX possui identificadores unicos gerados pelo Synapse: EndToEndId (E + ISPB + datetime + random = 32 chars) e BizMsgIdr (M + ISPB + random = 32 chars).

Tokenizando chaves PIX

pix-tokenize.jsjavascript

async function tokenizePixKey(keyType, keyValue, holderName) {
  const response = await fetch('https://vault.axon.com/v1/pix/tokens', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AXON_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      key_type: keyType,
      key_value: keyValue,
      holder_name: holderName,
    }),
  });

  return response.json();
}

const token = await tokenizePixKey('cpf', '12345678900', 'JOAO SILVA');

Transformando mensagens ISO 20022

transform-pacs008.jsjavascript

async function transformPacs008(xmlMessage) {
  const response = await fetch('https://synapse.axon.com/v1/transform/pacs008', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AXON_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: xmlMessage,
    }),
  });

  return response.json();
}

// Resposta inclui end_to_end_id, amount, currency, debtor, creditor

Iniciando pagamento PIX

pix-payment.jsjavascript

async function initiatePixPayment(pixToken, amount, description) {
  const response = await fetch('https://api.axon.com/v1/pix/payments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AXON_API_KEY}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID(),
    },
    body: JSON.stringify({
      pix_token: pixToken,
      amount: amount,
      currency: 'BRL',
      description: description,
    }),
  });

  return response.json();
}

Tipos de chave PIX

Suportamos CPF, CNPJ, email, telefone e chave aleatoria (EVP).

Gerando QR Code

pix-qrcode.jsjavascript

async function generatePixQRCode(amount, description) {
  const response = await fetch('https://api.axon.com/v1/pix/qrcodes', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AXON_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: amount,
      description: description,
      expiration_minutes: 30,
    }),
  });

  return response.json();
}

// Resposta inclui qr_code_base64 e qr_code_text

Status de pagamento

Status	ISO 20022	Descricao
pending	ACCP	Aguardando processamento
processing	ACSP	Em processamento
completed	ACSC	Liquidado com sucesso
failed	RJCT	Rejeitado

Pipeline de processamento

O Synapse processa mensagens PIX em 3 estagios via Kafka, garantindo alta disponibilidade com dual-channel (PRIMARY/SECONDARY):

INBOUND_PULL - Recebe mensagens do ICOM do BACEN em ambos os canais
WORKER - Parseia XML, extrai metadados (EndToEndId, ISPBs) e despacha para handlers
OUTBOUND_SEND - Assina XML (XMLDSig), comprime (gzip) e envia ao BACEN via mTLS

Enviando mensagens SPI

O Synapse oferece o endpoint POST /v1/spi/send para construir e enfileirar mensagens SPI outbound. O MessageBuilder gera automaticamente o XML ISO 20022 com AppHdr (head.001) e Document body, incluindo BizMsgIdr e EndToEndId unicos.

send-pix.jsjavascript

// Enviar transferencia PIX (pacs.008)
const response = await fetch('https://synapse.axon.com/v1/spi/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AXON_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message_type: 'PACS008',
    channel: 'PRIMARY',
    params: {
      transactions: [{
        amount: 15000, // R$ 150,00 em centavos
        debtor: { ispb: '12345678', name: 'JOAO SILVA', document: '12345678900' },
        creditor: { ispb: '87654321', name: 'EMPRESA ABC', document: '12345678000199' },
      }],
      local_instrument: 'DICT',
    },
  }),
});

const result = await response.json();
// { id: "msg_abc", biz_msg_idr: "M12345678...", message_type: "PACS008", status: "queued" }

Tipos de mensagem suportados para envio:

Tipo	Uso	Descricao
PACS008	Pagamento	Transferencia PIX entre instituicoes
PACS002	Confirmacao	Status de pagamento (ACCC, ACSC, RJCT)
PACS004	Devolucao	Devolucao de um PIX recebido
PAIN013	Cobranca	Solicitacao de pagamento (PIX Cobranca)
PAIN014	Resposta	Resposta a solicitacao de pagamento
CAMT029	Investigacao	Resolucao de investigacao
CAMT054	Notificacao	Notificacao de debito/credito
CAMT055	Cancelamento	Solicitacao de cancelamento
ADMI002	Rejeicao	Notificacao de rejeicao de mensagem

Assinatura XMLDSig

Em producao, habilite a assinatura digital configurando SPI_SIGN_ENABLED=true. O Synapse suporta assinatura nativa in-process (configure SPI_SIGN_CERT_PATH e SPI_SIGN_KEY_PATH com certificado e chave RSA) ou via servico externo (configure SPI_SIGNATURE_SERVICE_URL). A assinatura nativa usa RSA-SHA256 com Exclusive C14N e 3 referencias (KeyInfo, AppHdr, Document). Sem assinatura, o BACEN rejeitara as mensagens.