Skip to content

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:

EscopoAbre
ofb:receiver:consentsConexões de consentimento e jornadas otimizadas da receptora
ofb:receiver:customersRecursos e dados cadastrais obtidos por uma conexão ativa
ofb:receiver:accountsContas, saldos, transações e limites de cheque especial de uma conexão ativa
ofb:receiver:credit-cardsCartões de crédito, limites, transações e faturas de uma conexão ativa
ofb:initiator:paymentsConsentimentos de pagamento, Pix e vínculos de dispositivo
ofb:initiator:recurring-paymentsConsentimentos 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.

  1. Abrir a conexão de consentimento com a instituição transmissora escolhida no Diretório.

    bash
    curl -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 o redirectUrl da transmissora.

  2. 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.

  3. Acompanhar a conexão até o status active:

    bash
    curl -sS https://api.<domínio>/banking-receiver/consents/v1/consents/<connectionId> \
      -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"
  4. Coletar os dados autorizados e lê-los depois. A coleta e a leitura trazem só as famílias cujo escopo o token tem:

    bash
    curl -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.

  1. Criar o consentimento de pagamento na detentora escolhida no Diretório:

    bash
    curl -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 o redirectUrl da detentora.

  2. Levar o cliente final ao redirectUrl. Ele autoriza o pagamento na detentora, que o devolve ao callback público da plataforma.

  3. Acompanhar o consentimento até AUTHORISED. ?refresh=true relê o estado na detentora:

    bash
    curl -sS "https://api.<domínio>/banking-initiator/payments/v1/consents/<consentId>?refresh=true" \
      -H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"
  4. Iniciar o Pix com o consentimento autorizado. O endToEndId segue o formato do Pix (E + ISPB + data e hora UTC aaaaMMddHHmm + 11 caracteres):

    bash
    curl -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"
        }
      }'
  5. Acompanhar o Pix até um estado final: ACSC (liquidado), RJCT (rejeitado) ou CANC (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:

    bash
    curl -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:ofb grava dados de demonstração e roda só num banco local: ele recusa um DATABASE_URL cujo host não seja de loopback (localhost, 127.0.0.1 ou ::1). Nunca o rode contra uma instalação, nem por um túnel ou port-forward que a faça aparecer em localhost.
  • A telemetria redige pelo nome do campo cpf, cnpj, o cpfCnpj do recebedor, os dados da conta (number, branchCode e checkDigit), o cabeçalho Authorization e 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; um issuer de 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.

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br