Aparência
Acesso por aplicação: receptora e iniciadora do Open Finance
Para o caminho mais curto até a primeira leitura de transações, siga Primeiros passos.
As APIs de receptora (/banking-receiver) e de iniciadora (/banking-initiator) são as APIs que o backend do participante chama para consumir dados e iniciar pagamentos no Open Finance Brasil. Elas não são APIs reguladas entre instituições: ficam em api.<domínio> e aceitam o token de uma aplicação do participante, sem certificado de cliente nas chamadas.
As APIs reguladas (/open-banking/*, em matls-api.<domínio>) continuam exigindo o certificado ICP-Brasil e um token vinculado a ele. Um token de aplicação não abre nenhuma API regulada, e um token regulado não abre nenhuma rota de aplicação.
Credenciais da aplicação
Cada instalação traz a aplicação embutida finnest-power-ofb-application, um cliente do realm finnest-ofb do Keycloak com autenticação por segredo (client_secret). O Keycloak gera o segredo quando cria o cliente, e a atualização do realm nunca o troca. Quem opera a instalação abre o console de administração do Keycloak com finnest kc console, lê ou gira o segredo em Clients › finnest-power-ofb-application › Credentials e o entrega ao time que desenvolve o backend.
Os tokens da aplicação são assinados com PS256, valem para o público finnest-power-banking-application, não são vinculados a certificado e trazem todos os escopos de aplicação:
| Escopo | Abre |
|---|---|
ofb:receiver:consents | Conexões de consentimento e jornadas otimizadas da receptora |
ofb:receiver:customers | Recursos e dados cadastrais obtidos por uma conexão ativa |
ofb:receiver:accounts | Contas, saldos, transações e limites de cheque especial de uma conexão ativa |
ofb:receiver:credit-cards | Cartões de crédito, limites, transações e faturas de uma conexão ativa |
ofb:initiator:payments | Consentimentos de pagamento, Pix e vínculos de dispositivo |
ofb:initiator:recurring-payments | Consentimentos recorrentes, Pix recorrente e vínculos de dispositivo |
Só as aplicações declaradas no realm recebem o público finnest-power-banking-application. O registro dinâmico (DCR) de um participante nunca o emite: um token de cliente regulado, com o público finnest-power-banking, não abre nenhuma rota de aplicação, quaisquer que sejam os seus escopos.
Obter o token
O endereço do endpoint de token depende da instalação. O Admin mostra o endereço certo em Developer › Primeiros passos da API:
- Com a superfície mTLS regulada (a separação regulada ligada, com o OFB ou com o OPIN como transmissora): o endpoint só existe em
matls-auth.<domínio>, que exige certificado de cliente ICP-Brasil no TLS. O backend apresenta o certificado de transporte do próprio participante só nessa chamada. O token emitido continua sem vínculo, e as chamadas de API seguem sem certificado. Numa instalação que também é transmissora do OFB (registro dinâmico de clientes do OFB ligado), esse endpoint passa pelo gateway de registro, que admite a aplicação embutida sem vínculo de certificado; o token emitido é o mesmo. - Sem a superfície mTLS regulada: o endpoint fica em
auth.<domínio>, sem certificado de cliente. - Sem endpoint de token publicado: algumas instalações não publicam o endpoint. O Admin então pede que você fale com quem opera a instalação.
O exemplo abaixo usa matls-auth.<domínio>. Em auth.<domínio>, tire --cert e --key.
bash
curl -sS https://matls-auth.<domínio>/realms/finnest-ofb/protocol/openid-connect/token \
--cert transporte.crt --key transporte.key \
-d grant_type=client_credentials \
-d client_id=finnest-power-ofb-application \
-d client_secret="$CLIENT_SECRET"A resposta traz access_token, que vale pelo tempo de expires_in. Peça um novo token quando ele expirar; não há refresh token no fluxo client_credentials.
O gateway de registro admite sem vínculo de certificado só um cliente marcado pelo realm. A aplicação embutida já vem marcada. Um cliente de aplicação próprio do participante, criado no console, só recebe token numa instalação transmissora do OFB com o atributo finnest.unbound_application_token = "true"; sem ele, o gateway recusa o pedido com client certificate binding required. O roteiro de validação dá a forma completa do cliente e como gravar o atributo.
Chamar a receptora
Toda chamada leva o token no cabeçalho Authorization e um x-fapi-interaction-id (UUID) que a resposta devolve. Uma criação aceita x-idempotency-key: a mesma chave com o mesmo corpo devolve a conexão já criada, e a mesma chave com outro corpo é recusada. Nas jornadas otimizadas, a chave é obrigatória.
Abrir a conexão de consentimento com a instituição transmissora escolhida no Diretório.
bashcurl -sS https://api.<domínio>/banking-receiver/consents/v1/consents \ -H "Authorization: Bearer $TOKEN" \ -H "x-fapi-interaction-id: $(uuidgen)" \ -H "x-idempotency-key: $(uuidgen)" \ -H 'content-type: application/json' \ -d '{ "data": { "authorisationServerId": "<id do servidor de autorização no Diretório>", "redirectUri": "https://api.<domínio>/banking-receiver/consents/v1/callback/fragment", "loggedUser": { "document": { "identification": "<CPF>", "rel": "CPF" } }, "permissions": ["RESOURCES_READ", "CUSTOMERS_PERSONAL_IDENTIFICATIONS_READ"] } }'A resposta traz a conexão, com status
awaiting_authorisation, e oredirectUrlda transmissora.Levar o cliente final ao
redirectUrl. Ele se autentica e autoriza o compartilhamento na transmissora, que o devolve ao callback da plataforma. O callback é público e ativa a conexão.Acompanhar a conexão até o status
active:bashcurl -sS https://api.<domínio>/banking-receiver/consents/v1/consents/<connectionId> \ -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"Coletar os dados autorizados e lê-los depois. A coleta e a leitura trazem só as famílias cujo escopo o token tem:
bashcurl -sS -X POST \ https://api.<domínio>/banking-receiver/v1/connections/<connectionId>/sync \ -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)" curl -sS https://api.<domínio>/banking-receiver/v1/aggregations \ -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"
Cada aplicação só enxerga as conexões e os dados que ela mesma abriu.
Chamar a iniciadora
A iniciadora usa o mesmo token, com o escopo ofb:initiator:payments, e os mesmos cabeçalhos da receptora. Nas criações da iniciadora, x-idempotency-key é obrigatório: sem ele, a chamada é recusada. A plataforma fala com a detentora da conta pelo cliente FAPI registrado da instalação.
Criar o consentimento de pagamento na detentora escolhida no Diretório:
bashcurl -sS https://api.<domínio>/banking-initiator/payments/v1/consents \ -H "Authorization: Bearer $TOKEN" \ -H "x-fapi-interaction-id: $(uuidgen)" \ -H "x-idempotency-key: $(uuidgen)" \ -H 'content-type: application/json' \ -d '{ "data": { "authorisationServerId": "<id do servidor de autorização no Diretório>", "redirectUri": "https://api.<domínio>/banking-initiator/payments/v1/callback/fragment", "consent": { "loggedUser": { "document": { "identification": "<CPF>", "rel": "CPF" } }, "creditor": { "personType": "PESSOA_NATURAL", "cpfCnpj": "<CPF>", "name": "<nome>" }, "payment": { "type": "PIX", "purpose": "IMMEDIATE", "date": "<aaaa-mm-dd>", "currency": "BRL", "amount": "1.00", "details": { "localInstrument": "MANU", "creditorAccount": { "ispb": "<ISPB>", "issuer": "0001", "number": "<conta>", "accountType": "CACC" } } } } } }'A resposta traz o consentimento, com status
AWAITING_AUTHORISATION, e oredirectUrlda detentora.Levar o cliente final ao
redirectUrl. Ele autoriza o pagamento na detentora, que o devolve ao callback público da plataforma.Acompanhar o consentimento até
AUTHORISED.?refresh=truerelê o estado na detentora:bashcurl -sS "https://api.<domínio>/banking-initiator/payments/v1/consents/<consentId>?refresh=true" \ -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"Iniciar o Pix com o consentimento autorizado. O
endToEndIdsegue o formato do Pix (E+ ISPB + data e hora UTCaaaaMMddHHmm+ 11 caracteres):bashcurl -sS https://api.<domínio>/banking-initiator/payments/v1/pix/payments \ -H "Authorization: Bearer $TOKEN" \ -H "x-fapi-interaction-id: $(uuidgen)" \ -H "x-idempotency-key: $(uuidgen)" \ -H 'content-type: application/json' \ -d '{ "data": { "consentId": "<consentId>", "endToEndId": "<endToEndId>", "cnpjInitiator": "<CNPJ da iniciadora>", "remittanceInformation": "Pagamento de teste" } }'Acompanhar o Pix até um estado final:
ACSC(liquidado),RJCT(rejeitado) ouCANC(cancelado). A plataforma consulta a detentora periodicamente enquanto o pagamento não chega a um estado final, então a consulta abaixo reflete o estado mesmo sem webhook:bashcurl -sS https://api.<domínio>/banking-initiator/payments/v1/pix/payments/<paymentId> \ -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"
Webhook de pagamento
Receber webhook é opcional para a iniciadora. A detentora notifica cada mudança de estado do Pix com um POST na API de Webhook do Open Finance Brasil, e a plataforma o atende no caminho da especificação, no host regulado e com o certificado ICP-Brasil da detentora, sem token:
text
https://matls-api.<domínio>/open-banking/webhook/v1/payments/v5/pix/payments/<paymentId>Os Pix recorrentes chegam em …/automatic-payments/v2/pix/recurring-payments/<recurringPaymentId> e os vínculos de dispositivo em …/enrollments/v2/enrollments/<enrollmentId>, sob a mesma base; a notificação de vínculo traz o cabeçalho x-authorization-server-id, que a especificação exige. A detentora só envia para a URI de webhook cadastrada no software statement do participante, no Diretório. Cadastre a URI que faz a detentora chegar a esses caminhos. A plataforma responde 202 e relê o pagamento na detentora.
Dados de teste
No sandbox e numa prova de conceito, os consentimentos e pagamentos usam só os documentos dos usuários de teste do Mock Bank oficial do Diretório de sandbox do Open Finance Brasil. O Diretório de sandbox é descrito no Guia de Operação do Diretório Central do Open Finance Brasil. Os usuários de teste do Mock Bank vêm da documentação oficial do sandbox ou da estrutura do Open Finance Brasil; esta página não reproduz a lista, e quem opera a instalação a confirma lá antes da primeira jornada. Os servidores de autorização do Mock Bank estão no Guia OFB da participante.
- Nenhum CPF ou CNPJ real entra num corpo de consentimento, de pagamento ou de recebedor (
creditor). Nesta página, cada<CPF>é o documento de um usuário de teste do Mock Bank. - O
bun seed:ofbgrava dados de demonstração e roda só num banco local: ele recusa umDATABASE_URLcujo host não seja de loopback (localhost,127.0.0.1ou::1). Nunca o rode contra uma instalação, nem por um túnel ou port-forward que a faça aparecer emlocalhost. - A telemetria redige pelo nome do campo
cpf,cnpj, ocpfCnpjdo recebedor, os dados da conta (number,branchCodeecheckDigit), o cabeçalhoAuthorizatione os campos de token e de segredo, em logs e em atributos de span. A agência da conta (issuer, de 1 a 4 dígitos) também é redigida; umissuerde outra forma, como a URL do servidor de autorização, fica legível.
Quem opera a instalação comprova escopo, isolamento e dados de teste com o Roteiro de validação.
Contrato e coleção
O contrato da receptora, com os esquemas de requisição e resposta e os escopos de cada operação, está publicado na referência interativa, como APIs de aplicação (receptora OFB), e pode ser baixado em /api/specs/banking-receiver/openapi.json. O contrato completo, com a iniciadora, é o documento OpenAPI do serviço bancário, que a instalação serve em /banking/openapi.json, atrás da mesma proteção das APIs reguladas; quem opera a instalação o baixa e o entrega ao time do backend.
A forma mais curta de começar é a coleção Bruno, que já pede o token da aplicação e encadeia o consentimento, a coleta de dados e o Pix, nos ambientes local e sandbox. A plataforma a testa contra o serviço bancário a cada mudança. Para outra ferramenta, como o Postman ou o Insomnia, importe o documento OpenAPI: as operações de /banking-receiver e /banking-initiator vêm com o esquema oauth2 e os escopos de aplicação acima.