Jornada PIX

Diagrama do Fluxo

Representações documentais do domínio Pix. O primeiro diagrama resume as capacidades descritas na jornada; o segundo detalha uma transferência com assinatura digital RSA (autenticação descrita na seção "Autenticação e Assinatura Digital"). As demais transferências (QR Code, conta bancária) e o estorno seguem o mesmo padrão de assinatura. [INFERÊNCIA]

A jornada PIX no Finway oferece uma experiência completa de pagamentos instantâneos, desde o gerenciamento de chaves até a realização de transferências. Este guia apresenta os principais fluxos e funcionalidades disponíveis.

Visão Geral

O PIX é o sistema de pagamentos instantâneos do Banco Central do Brasil, permitindo transferências 24/7 com liquidação imediata. Nossa API oferece todas as funcionalidades necessárias para integrar PIX em sua aplicação.

Gerenciamento de Chaves

Criação, consulta e exclusão de chaves PIX

Transferências PIX

Transferências por chave, QR Code e conta bancária

QR Codes

Geração e validação de QR codes PIX

Limites PIX

Configuração e gerenciamento de limites

Autenticação e Assinatura Digital

Headers de Autenticação

Todas as operações PIX requerem os seguintes headers básicos:

X-buildersbank-Authorization: {token}
client_id: XXX

Processo de Assinatura Digital

Para operações que envolvem movimentação financeira, é necessário implementar assinatura digital usando criptografia RSA:

1. Especificações da Chave RSA

O sistema utiliza criptografia RSA com as seguintes especificações:

Tamanho da chave: 2048 bits
Algoritmo: SHA512withRSA
Formato: PEM (Privacy-Enhanced Mail)
Encoding: Base64

A chave pública deve ser registrada durante o processo de onboarding.

2. Obter Challenge

Antes de realizar operações financeiras, obtenha um challenge do servidor, se a conta for PF deve ser enviado o CPF e se for PJ deve ser enviado o CNPJ no campo cpf:

POST /security/authentication/challenge
Content-Type: application/json
client_id: 050a51d5-9137-4f5f-bfc0-5a5e57338236

{
  "cpf": "12345678901",
  "deviceIdentification": "DDBCCDDDEEF#698.931.201"
}

Resposta:

{
  "challenge": "82444f34-5ca9-47f5-86a1-8bff3572ede5",
}

3. Gerar Assinatura

Use sua chave privada para gerar a assinatura digital:

Importante: A mensagem a ser assinada segue o formato: CPF + "&" + PIN + "&" + CHALLENGE

O algoritmo de assinatura deve usar SHA512withRSA e o resultado deve ser codificado em Base64.

4. Validar Autenticação

Valide a assinatura gerada:

POST /security/authentication/validate
{
  "cpf": "12345678901",
  "deviceIdentification": "DDBCCDDDEEF#698.931.200",
  "signature": "base64_signature_generated_above",
  "deviceData": {
    "platform": "ANDROID",
    "version": "1.0.0"
  }
}

Após a validação bem-sucedida, você receberá um token JWT para usar nas operações PIX.

Gerenciamento de Chaves

A gestão de chaves PIX permite criar, consultar e excluir chaves associadas à conta.

Tipos de Chaves Suportadas

CPF/CNPJ: Documento da pessoa física ou jurídica
EMAIL: Endereço de email válido
PHONE: Número de telefone no formato internacional
EVP: Chave aleatória (Endereço Virtual de Pagamento)

Listar Chaves Existentes

GET /pix/{document}/keys
X-buildersbank-Authorization: {token}
client_id: XXX

Exemplo de Resposta:

[
  {
    "id": "7df6ea85-1b06-441c-97a1-940cb89f09f1",
    "key": "12345678901",
    "keyType": "CPF",
    "status": "ACTIVE",
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

Criar Nova Chave

POST /pix/{document}/keys
X-buildersbank-Authorization: {token}
client_id: XXX
Content-Type: application/json

{
    "keyType": "CPF",
    "deviceIdentification": "DDBCCDDDEEF#698.931.200",
    "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."
}

Campos obrigatórios:

keyType: Tipo da chave (CPF, EMAIL, PHONE, EVP)
deviceIdentification: Identificação do dispositivo
signature: Assinatura digital da operação

Consultar Chave Específica

GET /pix/{document}/keys/{key}
X-buildersbank-Authorization: {token}
client_id: XXX

Exemplo: Consultar CPF como chave

GET /pix/60483453000148/keys/89619467817
X-buildersbank-Authorization: {token}
client_id: XXX

Excluir Chave PIX

DELETE /pix/{document}/keys/{keyId}
X-buildersbank-Authorization: {token}

Exemplo:

DELETE /pix/76297181527/keys/7df6ea85-1b06-441c-97a1-940cb89f09f1
X-buildersbank-Authorization: {token}

Validação OTP para Chaves

Para chaves de email e telefone, pode ser necessária validação OTP:

SMS:

POST /pix/{document}/keys/phone/otp/challenge
POST /pix/{document}/keys/phone/otp/validate

Email:

POST /pix/{document}/keys/mail/otp/challenge
POST /pix/{document}/keys/mail/otp/validate

Transferências PIX

Todas as transferências PIX requerem assinatura digital e suportam três modalidades principais.

Transferência por Chave PIX

POST /pix/{document}/transfers/keys
X-buildersbank-Authorization: {token}
client_id: XXX
Content-Type: application/json

{
    "amount": 1.00,
    "key": "89619467817",
    "description": "Teste Pix",
    "payee": {
        "ispb": "36741675",
        "bankAccountNumber": "100000003",
        "bankBranchNumber": "0001",
        "bankAccountType": "CC",
        "beneficiaryType": "F",
        "document": "56608410077",
        "fullName": "elder reis"
    },
    "deviceIdentification": "DDBCCDDDEEF#698.931.200",
    "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96...",
    "challenge": "104d808c-803e-45e1-9271-46e2ee6d4795",
    "externalId": "pix-out-1",
    "idEndToEnd": "E4397869720260207154802797629843"

}

Campos obrigatórios:

amount: Valor da transferência
key: Chave PIX do destinatário
payee: Dados do beneficiário
deviceIdentification: Identificação do dispositivo
signature: Assinatura digital da operação

Transferência por QR Code

1. Validar QR Code:

POST /pix/{document}/transfers/codes/validate
X-buildersbank-Authorization: {token}
Content-Type: application/json

{
  "qrCode": "00020126890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ac90368852e846d9a2bed116d1d814145204000053039865802BR5915Jamie Lannister6009Sao Paulo62070503***6304D0A3",
  	"deviceIdentification": "DDBCCDDDEEF#698.931.200",
  "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."
}

2. Realizar Transferência:

POST /pix/{document}/transfers/codes
X-buildersbank-Authorization: {token}
client_id: XXX
Content-Type: application/json

{
    "idEndToEnd": "E39157329202507151938voZFTZ69XlL",
    "amount": 503.86,
    "discount": 0.00,
    "allowChange": true,
    "ispb": "99999918",
    "bankAccountNumber": "94937",
    "bankBranchNumber": "0001",
    "bankAccountType": "CACC",
    "key": "f4c6089a-bfde-4c00-a2d9-9eaa584b0219",
    "beneficiaryType": "J",
    "document": "99.999.918/9999-24",
    "fullName": "Pix Tester 99999918",
    "cashAmount": 0.00,
    "cashierBankCode": "",
    "cashierType": "",
    "schedulingDate": "2025-07-15T19:38:27.433267Z",
    "reconciliationId": "9d96c9de272c41e6ae308401c2faa672",
    "deviceIdentification": "DDBCCDDDEEF#698.931.200",
    "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."
}

Transferência para Conta Bancária

POST /pix/{document}/transfers/bank
X-buildersbank-Authorization: {token}
Content-Type: application/json

{
    "amount": 1.00,
    "description": "Teste Pix",
    "payee": {
        "bankIspb": "36741675",
        "accountNumber": "100000003",
        "accountBranch": "0001",
        "accountType": "PAYMENT",
        "documentNumber": "56608410077",
        "name": "elder reis"
    },
    "deviceIdentification": "DDBCCDDDEEF#698.931.200",
     "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96...",
     "challenge": "104d808c-803e-45e1-9271-46e2ee6d4795",
     "externalId": "pix-out-1"

}

Tipos de Conta:

PAYMENT: Conta de pagamento
CHECKING: Conta corrente
SAVINGS: Conta poupança

Estorno/Devolução PIX

Para operações de estorno:

POST /pix/{document}/transfers/reversal
X-buildersbank-Authorization: {token}
Content-Type: application/json

{
    "id": "123",
    "amount": 1.00,
    "idEndToEnd": "E39157329202507151938voZFTZ69XlL",
    "deviceIdentification": "DDBCCDDDEEF#698.931.200",
    "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."
}

Campos obrigatórios:

id: ID da transação original
amount: Valor a ser estornado
idEndToEnd: ID End-to-End da transação original
deviceIdentification: Identificação do dispositivo
signature: Assinatura digital

QR Codes

Funcionalidades para criação e validação de códigos QR PIX.

Criar QR Code Estático

POST /pix/{document}/codes/static
X-buildersbank-Authorization: {token}
Content-Type: application/json

{
    "key": "88895721403",
    "amount": 100,
  	"deviceIdentification": "DDBCCDDDEEF#698.931.200",
  "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."

}

Resposta:

{
    "qrCode": "00020126580014BR.GOV.BCB.PIX...",
    "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Validar QR Code

POST /pix/{document}/transfers/codes/validate
X-buildersbank-Authorization: {token}
Content-Type: application/json

{
    "qrCode": "00020126890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ac90368852e846d9a2bed116d1d814145204000053039865802BR5915Jamie Lannister6009Sao Paulo62070503***6304D0A3"
}

Resposta:

{
    "amount": 100.50,
    "beneficiary": {
        "name": "João Silva",
        "document": "12345678901"
    },
    "description": "Pagamento de serviços",
    "valid": true
}

Limites PIX

Configuração e consulta de limites para operações PIX.

Consultar Limites Atuais

GET /pix/{document}/limits
X-buildersbank-Authorization: {token}
client_id: XXX

Resposta:

{
"idAccount": "a397b65e-d788-4755-ae08-2deef2aa1f77",
"limits": [
  {
    "limitType": "PER_TRANSACTION",
    "defaultLimit": 1000,
    "accountLimit": 1500
  },
  {
    "limitType": "DAILY_LIMIT",
    "defaultLimit": 1000,
    "accountLimit": 1500
  },
  {
    "limitType": "MONTHLY_LIMIT",
    "defaultLimit": 5000,
    "accountLimit": 7000
  },
  {
    "limitType": "NIGHTLY_LIMIT",
    "defaultLimit": 2000,
    "accountLimit": 2500
  },
  {
    "limitType": "NIGHTLY_PER_TRANSACTION",
    "defaultLimit": 500,
    "accountLimit": 800
  },
  {
    "limitType": "PER_HOUR",
    "defaultLimit": 3000,
    "accountLimit": 4000
  },
  {
    "limitType": "UNDEFINED",
    "defaultLimit": 0,
    "accountLimit": 0
  },
  {
    "limitType": "WITHDRAW_DAILY_LIMIT",
    "defaultLimit": 1500,
    "accountLimit": 2000
  },
  {
    "limitType": "WITHDRAW_NIGHTLY_LIMIT",
    "defaultLimit": 1000,
    "accountLimit": 1200
  },
  {
    "limitType": "SCHEDULE_DAILY_LIMIT",
    "defaultLimit": 800,
    "accountLimit": 1000
  },
  {
    "limitType": "SCHEDULE_NIGHTLY_LIMIT",
    "defaultLimit": 600,
    "accountLimit": 700
  },
  {
    "limitType": "AUTOMATIC_DAILY_LIMIT",
    "defaultLimit": 1200,
    "accountLimit": 1500
  },
  {
    "limitType": "AUTOMATIC_NIGHTLY_LIMIT",
    "defaultLimit": 900,
    "accountLimit": 1100
  },
  {
    "limitType": "PERSON_DAILY_LIMIT",
    "defaultLimit": 2000 ,
    "accountLimit": 2500
  },
  {
    "limitType": "PERSON_NIGHTLY_LIMIT",
    "defaultLimit": 1500,
    "accountLimit": 1800
  },
  {
    "limitType": "COMPANY_DAILY_LIMIT",
    "defaultLimit": 5000,
    "accountLimit": 6000
  },
  {
    "limitType": "COMPANY_NIGHTLY_LIMIT",
    "defaultLimit": 3000,
    "accountLimit": 3500
  }
]
}

Configurar Período Noturno

Configure o horário considerado "noturno" para aplicação de limites específicos:

POST /pix/{document}/limits/nightTime
X-buildersbank-Authorization: {token}
client_id: XXX

{
 	"nightStart": "18:00:00"; // Horário no formato "HH:mm:ss"
  "deviceIdentification": "DDBCCDDDEEF#698.931.200",
  "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."
}

Solicitar Alteração de Limite

POST /pix/{document}/limits
X-buildersbank-Authorization: {token}
client_id: XXX

{
  "limit": 1000;        // Novo valor do limite
	"type": "MONTHLY_LIMIT"; // Tipos de limites listados acima
  "deviceIdentification": "DDBCCDDDEEF#698.931.200",
  "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."
}

Extrato e Comprovantes

Consultar Extrato de Transações

GET /holders/{document}/accounts/main/transactions?page=0&size=20&startDate=2020-07-01&endDate=2020-08-15
X-buildersbank-Authorization: {token}

Parâmetros de filtro:

page: Número da página (padrão: 0)
size: Itens por página (padrão: 20, máx: 100)
startDate: Data inicial (YYYY-MM-DD)
endDate: Data final (YYYY-MM-DD)

Obter Comprovante de Transação

GET /holders/{document}/accounts/main/transactions/{transactionId}
X-buildersbank-Authorization: {token}

Exemplo:

GET /holders/60483453000148/accounts/main/transactions/1234
X-buildersbank-Authorization: {token}

Funcionalidades Avançadas

Reivindicação de Chaves

Para reivindicar uma chave PIX de outra instituição:

POST /pix/{document}/keys/claims
X-buildersbank-Authorization: {token}
client_id: XXX

{
  "key": "minha-chave@email.com",
  "keyType": "EMAIL",
  "reason": "Migração para nova instituição",
  	"deviceIdentification": "DDBCCDDDEEF#698.931.200",
  "signature": "RJQ39YQomvtJKajqcO3jyBXbYu4iGegQu+rEcUD+ySgsdR8KFKUQEE5FHpx4Tq96..."
}

Verificar Saldo da Conta

Importante: Deve ser chamado ANTES e DEPOIS de ativar a conta no Backoffice

GET /holders/{document}/accounts
X-buildersbank-Authorization: {token}
client_id: XXX

Exemplo:

GET /holders/60483453000148/accounts
X-buildersbank-Authorization: {token}
client_id: XXX

Tratamento de Erros

Códigos de Status

Status	Descrição
200	Operação realizada com sucesso
400	Requisição inválida
401	Não autorizado - Token ou assinatura inválida
403	Operação não permitida
404	Recurso não encontrado
422	Dados inválidos
500	Erro interno do servidor

Padrão de Resposta de Erro

Todas as respostas de erro seguem o padrão:

{
  "error": "INVALID_REQUEST",
  "message": "A solicitação contém parâmetros inválidos",
  "details": "Campo 'amount' deve ser maior que zero",
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/pix/me/transfers/keys"
}

Erros de Autenticação

{
  "error": "UNAUTHORIZED",
  "message": "Assinatura digital inválida",
  "details": "Verifique se a chave privada corresponde à chave pública registrada",
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/security/authentication/validate"
}

Próximos Passos

API Reference

Documentação completa da API PIX

Segurança

Guia de implementação de segurança

Suporte

Canal de suporte técnico

Diagrama do Fluxo​

Visão Geral​

Gerenciamento de Chaves​

Transferências PIX​

QR Codes​

Limites PIX​

Autenticação e Assinatura Digital​

Headers de Autenticação​

Processo de Assinatura Digital​

Gerenciamento de Chaves​

Transferências PIX​

QR Codes​

Limites PIX​

Extrato e Comprovantes​

Funcionalidades Avançadas​

Tratamento de Erros​

Erros de Autenticação​

Próximos Passos​

API Reference​

Segurança​

Suporte​

Diagrama do Fluxo

Visão Geral

Gerenciamento de Chaves

Transferências PIX

QR Codes

Limites PIX

Autenticação e Assinatura Digital

Headers de Autenticação

Processo de Assinatura Digital

Gerenciamento de Chaves

Transferências PIX

QR Codes

Limites PIX

Extrato e Comprovantes

Funcionalidades Avançadas

Tratamento de Erros

Erros de Autenticação

Próximos Passos

API Reference

Segurança

Suporte