API para iniciador de pagamentos: como funciona?

Principais lições deste artigo

• Um Iniciador de Pagamentos autorizado pelo Banco Central permite iniciar transferências via Pix diretamente da conta do usuário, sem uso de QR Codes ou chaves.

• O fluxo operacional segue cinco etapas obrigatórias: consentimento, redirecionamento, callback, ordem de pagamento e confirmação por webhook.

• O cumprimento de requisitos técnicos é obrigatório, como licença de IP, mTLS, OAuth 2.0 com PKCE e certificados BRSEAL e BRCAC.

• Boas práticas incluem submeter o pagamento logo após a aprovação, priorizar webhooks e manter certificados atualizados para reduzir falhas.

• Com a Celcoin, empresas aceleram a entrada no mercado sem licença própria. Descubra essa solução completa para fintechs, bancos digitais, gestoras de fundos, varejistas e ERPs.

Passo 1: visão geral do fluxo operacional

Uma iniciação de pagamento no Open Finance Brasil segue cinco etapas sequenciais obrigatórias.

1. Criação do consentimento: a aplicação do iniciador solicita ao usuário autorização para acessar a conta e iniciar o pagamento. Essa etapa gera um objeto de consentimento com escopo, valor e recebedor definidos.

2. Redirecionamento do usuário: o usuário é redirecionado para o ambiente da instituição detentora da conta, banco ou IP, para autenticar e aprovar o consentimento.

3. Callback e captura do código: após a aprovação, a instituição detentora redireciona o usuário de volta à aplicação do iniciador com um código de autorização.

4. Criação da ordem de pagamento: com o consentimento aprovado, o iniciador submete a ordem de pagamento via Pix à instituição detentora.

5. Confirmação e notificação: a instituição processa o pagamento e notifica o iniciador por webhook ou resposta síncrona com o status final da transação.

Veja como a Celcoin simplifica cada etapa desse fluxo com infraestrutura regulatória completa.

Passo 2: pré-requisitos técnicos e regulatórios

Uma operação de iniciação de pagamentos começa pelo atendimento a requisitos técnicos e regulatórios definidos pelo Open Finance Brasil.

• Licença de Iniciador de Pagamentos (IP): a empresa precisa obter autorização junto ao Banco Central como Instituição de Pagamento na modalidade iniciador ou operar sob a licença de um parceiro habilitado.

• mTLS (Mutual TLS): toda comunicação entre o iniciador e a instituição detentora exige autenticação mútua por certificado digital. Os certificados precisam ser emitidos por autoridades certificadoras homologadas no diretório do Open Finance Brasil.

• OAuth 2.0 com PKCE: o fluxo de autorização utiliza OAuth 2.0 Authorization Code Flow com Proof Key for Code Exchange, o que garante que apenas a aplicação legítima consiga trocar o código de autorização por tokens de acesso.

• Certificados BRSEAL e BRCAC: o certificado BRSEAL assina os payloads de requisição em JWS, enquanto o BRCAC autentica o cliente no mTLS.

• Registro no Diretório de Participantes: a aplicação precisa estar registrada no diretório oficial, com software statement válido e redirect URIs declaradas.

A Resolução Conjunta CMN BCB nº 16/2025, disponível no guia de tendências em fintech, exclui os serviços de iniciação de pagamentos do escopo do novo marco regulatório de Banking as a Service. Essa exclusão reforça a necessidade de manter uma estrutura própria ou contar com um parceiro que ofereça infraestrutura regulatória dedicada para essa modalidade.

Passo 3: passo a passo detalhado com exemplos de JSON

3.1 Criação do consentimento

A primeira chamada cria o objeto de consentimento na instituição detentora.

POST /open-banking/payments/v3/consents Authorization: Bearer {access_token} Content-Type: application/json { "data": { "loggedUser": { "document": { "identification": "11111111111", "rel": "CPF" } }, "creditor": { "personType": "PESSOA_NATURAL", "cpfCnpj": "22222222222", "name": "Recebedor Exemplo" }, "payment": { "type": "Pix", "date": "2026-06-02", "currency": "BRL", "amount": "150.00", "details": { "localInstrument": "DICT", "proxy": "chave@recebedor.com" } } } }

3.2 Redirecionamento para aprovação

Com o consentId retornado, a aplicação redireciona o usuário para a URL de autorização da instituição detentora, com os parâmetros de OAuth 2.0.

GET https://auth.instituicao.com.br/auth? response_type=code &client_id={client_id} &redirect_uri=https://suaapp.com.br/callback &scope=payments &consent_id={consentId} &code_challenge={code_challenge} &code_challenge_method=S256

3.3 Callback e criação do pagamento

Após o retorno do usuário com o código de autorização, a aplicação troca esse código por um token e submete a ordem de pagamento.

POST /open-banking/payments/v3/pix/payments Authorization: Bearer {payment_access_token} { "data": { "consentId": "urn:bancoexemplo:C1DD33123", "proxy": "chave@recebedor.com", "payment": { "amount": "150.00", "currency": "BRL" }, "creditorAccount": { "ispb": "12345678", "number": "1234567890", "accountType": "CACC" } } }

Passo 4: webhooks e polling de status

O monitoramento do resultado de um pagamento ocorre por dois mecanismos complementares.

Webhooks: a instituição detentora envia notificações HTTP POST para a URL registrada pelo iniciador sempre que o status do pagamento ou do consentimento muda. Os eventos mais comuns são PAYMENT_COMPLETED, PAYMENT_REJECTED e CONSENT_REVOKED. O payload inclui o paymentId, o novo status e o timestamp do evento. A URL de webhook precisa estar declarada no software statement e protegida por mTLS.

Polling: em cenários em que o webhook não é entregue, o iniciador pode consultar o status diretamente.

GET /open-banking/payments/v3/pix/payments/{paymentId} Authorization: Bearer {access_token}

A resposta retorna o campo status com valores possíveis PDNG (pendente), PART (parcialmente aceito), ACSC (liquidado) ou RJCT (rejeitado). O uso de polling com intervalo mínimo de 2 segundos e timeout de 2 minutos reduz sobrecarga nas APIs das instituições detentoras.

Passo 5: segurança, LGPD e compliance com o Guia UX do Bacen

Uma operação de iniciação de pagamentos segura depende de requisitos de mTLS e OAuth 2.0 e também de cuidados adicionais em privacidade, experiência do usuário e integridade das mensagens.

• LGPD: o consentimento coletado para o pagamento precisa ser granular, com finalidade, prazo e dados tratados informados de forma explícita ao usuário. O iniciador não pode reutilizar o consentimento de pagamento para outras finalidades, o que exige políticas claras de retenção e descarte de dados.

• Guia UX do Banco Central: a jornada de redirecionamento e retorno precisa seguir os padrões visuais e de fluxo definidos pelo Bacen. Isso inclui telas de confirmação com detalhes do pagamento, identidade do recebedor e valor antes da aprovação final, o que reduz erros e aumenta a confiança do usuário.

• Assinatura de payloads em JWS: todas as requisições de criação de consentimento e pagamento precisam ser assinadas com o certificado BRSEAL. As respostas da instituição detentora devem ter a assinatura validada antes do processamento, o que evita adulteração de dados em trânsito.

Conheça a solução da Celcoin que já atende a esses requisitos de segurança, à LGPD e ao UX.

Erros comuns e boas práticas

• Consentimento expirado antes do pagamento: o objeto de consentimento tem validade curta, geralmente entre 5 e 15 minutos, o que aumenta o risco de expiração se houver atraso entre a aprovação do usuário e a submissão da ordem. Para evitar rejeições, submeta a ordem de pagamento imediatamente após receber o callback de aprovação.

• Redirect URI não registrada: qualquer URI não declarada no diretório de participantes resulta em erro de autorização. Mantenha o registro atualizado para todos os ambientes, sandbox e produção, e valide as URIs antes de cada release.

• Ignorar renovação de certificados: certificados BRCAC e BRSEAL têm prazo de validade definido. A criação de alertas automáticos de expiração evita interrupções operacionais por falha de autenticação ou assinatura.

• Polling excessivo: chamadas em intervalos inferiores a 2 segundos podem gerar bloqueio por rate limiting nas instituições detentoras. Priorize webhooks como canal principal e use polling apenas como fallback controlado.

• Falta de idempotência: o uso do header x-idempotency-key em todas as requisições de criação de pagamento evita duplicações em cenários de retentativa por falha de rede ou timeout.

Ferramentas e validação

Uma validação completa da integração passa por três ambientes: sandbox do Open Finance Brasil, ambiente de homologação da instituição detentora parceira e produção com monitoramento ativo. O uso de Postman com coleções mTLS configuradas, validadores de JWS e logs estruturados de webhook acelera a identificação de falhas antes do go-live.

A Celcoin atua como participante direta no Pix e Iniciadora de Pagamentos no Open Finance. A empresa oferece infraestrutura regulatória completa, APIs bem documentadas, sandbox dedicado e suporte técnico especializado. Empresas que operam sob a licença da Celcoin eliminam a necessidade de obter autorização própria junto ao Banco Central para iniciar pagamentos, o que reduz o tempo de entrada no mercado de meses para semanas.

Funcionalidade da Celcoin	Benefício para sua empresa
APIs modulares	Integrações mais rápidas reduzem custos e prazos de desenvolvimento.
Experiência e suporte ao desenvolvedor	Documentação, SDKs e sandboxes reduzem ciclos de integração e custos de engenharia.
Capacidade de lançamento rápido	Módulos pré-construídos e entrega via SaaS aceleram lançamentos e melhoram o tempo para geração de receita.
Distribuição white-label e embutida	Suporte a produtos financeiros com marca própria amplia o controle sobre a experiência do cliente.
Escalabilidade com confiabilidade	Uma solução com alta disponibilidade e escalável na nuvem mantém serviços estáveis mesmo em altos volumes e protege a receita.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	A oferta de pagamentos e emissão de crédito aumenta conversão, ARPU e fidelização.
Acesso a dados e personalização	Dados e análises via Open Finance permitem ofertas personalizadas e melhoram conversão e retenção.
Compliance e conformidade como princípio	KYC, AML e relatórios integrados reduzem risco regulatório e aceleram ciclos de vendas.
Prevenção de fraude e controles de risco	Monitoramento baseado em IA e autenticação robusta reduzem estornos, perdas e exposição regulatória.
Força do ecossistema de parceiros da Celcoin	Parcerias e integrações com bancos, redes e fintechs ampliam cobertura, recursos e velocidade de entrada no mercado.

Critérios de sucesso e próximos passos

Uma integração bem-sucedida de API para Pix via Iniciador de Pagamentos apresenta alguns indicadores claros. Entre eles estão taxa de aprovação de consentimentos acima de 85%, latência de resposta da ordem de pagamento inferior a 3 segundos em P95, entrega de webhooks com reentrega automática em caso de falha e zero erros de certificado em produção.

Após a validação técnica, o próximo passo natural é a expansão para pagamentos recorrentes, com consentimentos de longa duração, e a integração com fluxos de Open Finance para enriquecimento de dados do pagador.

Acelere sua integração com as APIs da Celcoin e comece a operar com Pix iniciado via Open Finance.

FAQ

O que diferencia um iniciador de pagamentos de uma instituição financeira tradicional no Open Finance?

Um Iniciador de Pagamentos não detém os recursos do usuário em nenhum momento. Essa instituição apenas instrui o banco ou a instituição de pagamento onde o pagador mantém a conta a executar a transferência via Pix, mediante consentimento explícito. Esse modelo dispensa licença de banco e conta de pagamento própria para movimentar valores, mas exige autorização específica do Banco Central como Instituição de Pagamento na modalidade iniciador ou operação sob a licença de um parceiro habilitado como a Celcoin.

Quanto tempo leva para integrar a API de iniciador de pagamentos da Celcoin?

O prazo de integração varia conforme a complexidade da estrutura existente na empresa. Alguns clientes concluem a integração e entram em produção em cerca de uma semana. Operações mais complexas podem levar até três meses. A Celcoin disponibiliza documentação completa, sandbox dedicado, SDKs e uma equipe de suporte técnico especializado que acompanha todo o processo e reduz o tempo de desenvolvimento em comparação com uma implementação do zero.

É necessário obter licença própria de Iniciador de Pagamentos junto ao Banco Central para usar a API?

Não necessariamente. Empresas sem licença própria podem operar sob a infraestrutura da Celcoin, o que elimina a necessidade de passar pelo processo de autorização junto ao Banco Central antes de lançar o produto. Quando a empresa decidir obter licença própria, a migração ocorre sobre a mesma base tecnológica, sem necessidade de trocar de infraestrutura.

Como a LGPD impacta o fluxo de consentimento para pagamentos via Pix no Open Finance?

O consentimento coletado para iniciar um pagamento precisa ser específico para aquela transação, com finalidade, valor, recebedor e prazo informados de forma clara ao usuário antes da aprovação. O iniciador não pode reutilizar esse consentimento para outras finalidades, como análise de comportamento ou oferta de crédito. Toda coleta, armazenamento e uso dos dados do pagador precisa seguir os princípios da LGPD, incluindo minimização de dados e direito de revogação a qualquer momento. A Celcoin oferece infraestrutura com conformidade integrada à LGPD, com gestão de consentimentos e relatórios regulatórios automatizados.

Quais são os principais motivos de rejeição de pagamentos via API de iniciador e como evitá-los?

Os motivos mais comuns de rejeição incluem consentimento expirado antes da submissão da ordem de pagamento, dados do recebedor inconsistentes com o cadastro na instituição detentora, saldo insuficiente na conta do pagador, certificados mTLS inválidos ou expirados e ausência do header de idempotência em retentativas. Para reduzir essas falhas, recomenda-se submeter a ordem imediatamente após a aprovação do consentimento, validar os dados do recebedor antes de criar o objeto de consentimento, implementar alertas de expiração de certificados e usar sempre o campo x-idempotency-key em todas as requisições de pagamento.