Detentora de Contas - Ambiente Sandbox

O que é a Detentora de Contas

No Open Finance Brasil, a detentora de contas (ou ASPSP — Account Servicing Payment Service Provider) é a instituição financeira onde o usuário pagador mantém sua conta. É ela que autentica o usuário, exibe os termos do consentimento e dá a aprovação final para que os pagamentos sejam realizados.

Durante a jornada de pagamento, após a ITP criar o consentimento, o usuário é obrigatoriamente redirecionado para o ambiente da detentora para autenticação e aprovação. Somente após essa etapa o consentimento passa para o status AUTHORISED e os pagamentos podem ser executados.

flowchart LR
    A["🏢 ITP (Celcoin)"] -->|"Cria consentimento POST /payment-initiation"| B["🔐 Detentora (ASPSP)"]
    B -->|"Usuário aprova → callback com code"| A
    A -->|"Executa pagamentos POST /payments"| B

    style A fill:#c6e2f5,stroke:#2980b9,color:#333
    style B fill:#d5f5d5,stroke:#27ae60,color:#333

Ambiente Sandbox — Bricks Demo

Para testes e homologação, a Celcoin disponibiliza o ambiente Bricks Demo, uma detentora de contas simulada e completa que permite realizar todo o fluxo de autorização de consentimentos sem nenhuma integração bancária real.

O brandId 66f4d9e296f18bc4606e1618 deve ser usado no campo brandId ao criar qualquer consentimento em ambiente sandbox — seja Sweeping Accounts, Pix Automático ou Pix ITP.

Credenciais de Homologação

Usuário: user01
Senha:   12345678

Essas credenciais representam o usuário pagador de CPF 12345678909 na detentora Bricks Demo. Use-as em ambas as formas de aprovação: via navegador e via API.

Formas de Aprovação

Existem duas formas de completar a jornada de autorização no ambiente sandbox:

Forma 1 — Aprovação via Navegador

Passo a passo

1. Gere o consentimento chamando o endpoint de criação (POST /payment-initiation) com o brandId do Bricks Demo.

2. Copie a authorizationUrl retornada no response. Ela terá um formato parecido com:

https://api-openfinance.opb.bricks.demo.fsapps.io/orgs/bricks/auth?client_id=CSYrcp9dzeRdUWbuXLFiF&request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A82A3zcrbiqhoh15jCL78A

3. Abra a URL no navegador. A página da detentora Bricks Demo será exibida com os detalhes do consentimento.

4. Clique em "Simular login e aprovação". O ambiente Bricks Demo realiza automaticamente o login com o usuário de teste e exibe a tela de aprovação do consentimento.

5. Confirme a aprovação. O usuário é redirecionado para a redirectUrl cadastrada na criação do consentimento, com os parâmetros code, id_token e state na query string:

http://localhost:8080/callback?code=AUTH_CODE&id_token=ID_TOKEN&state=STATE

6. Chame o endpoint de callback com os parâmetros recebidos para finalizar a autorização. Consulte a documentação de callback para os detalhes.

Forma 2 — Aprovação via API (Postman)

Esta forma é utilizada para automação e integração. O fluxo simula programaticamente as mesmas etapas que ocorrem no navegador, por meio de três chamadas sequenciais à API da detentora Bricks Demo.

Variáveis necessárias na Collection

Os scripts de teste da collection do Postman preenchem essas variáveis automaticamente a cada chamada.

Etapa API 1 — URL Autorização

GET {{authorization_url}}

Acessa a authorizationUrl do consentimento. O servidor da detentora responde com 302 Found e um interactionId no header Location.

Configuração no Postman:

• Desabilite Follow Redirects nas configurações da requisição para capturar o header Location.

GET {{authorization_url}}

Response — HTTP 302

HTTP/1.1 302 Found
Location: https://webconsentflow.opb.bricks.demo.fsapps.io?interactionId=n2voaWPj6V8rBu59dOqy6&...

O script de teste extrai e salva o interactionId automaticamente:

var interactionId = /interactionId=(.*?)(?:&|$)/.exec(
  pm.response.headers.get("location")
)[1];
pm.collectionVariables.set("login_interaction_id", interactionId);

Etapa API 2 — Login

POST /api/bricks/consents/v1/interactions/:interactionId/login

Autentica o usuário na detentora Bricks Demo com as credenciais de sandbox.

POST https://api-openfinance.opb.bricks.demo.fsapps.io/api/bricks/consents/v1/interactions/{{login_interaction_id}}/login
Content-Type: application/json

Request Body

{
  "username": "user01",
  "password": "12345678"
}

Response — HTTP 200

{
  "url": "https://webconsentflow.opb.bricks.demo.fsapps.io?interactionId=def456uvwXYZ&session=abc..."
}

O script de teste extrai o consent_interaction_id da URL retornada:

var jsonData = JSON.parse(responseBody);
var interactionId = /interactionId=(.*?)&/.exec(jsonData.url)[1];
pm.collectionVariables.set("consent_interaction_id", interactionId);

Atenção: O interactionId retornado aqui é diferente do login_interaction_id. É o identificador da sessão de aprovação do consentimento.

Etapa API 3 — Approve

POST /api/bricks/consents/v1/interactions/:interactionId/consent

Aprova o consentimento na detentora, completando a jornada de autorização.

POST https://api-openfinance.opb.bricks.demo.fsapps.io/api/bricks/consents/v1/interactions/{{consent_interaction_id}}/consent
Content-Type: application/json

Request Body

{}

Response — Aprovação bem-sucedida

{
  "url": "http://localhost:8080/callback?code=AUTH_CODE_AQUI&id_token=ID_TOKEN_AQUI&state=STATE_AQUI"
}

Response — Rejeição pelo usuário

{
  "url": "http://localhost:8080/callback?error=access_denied&state=STATE_AQUI"
}

O script de teste extrai e salva todos os parâmetros do callback automaticamente:

var jsonData = JSON.parse(responseBody);
var callbackParams = jsonData.url.split(
  jsonData.url.includes("?") ? "?" : "#", 2
)[1];
var params = callbackParams.split("&");
for (var index in params) {
  var param = params[index].split("=");
  pm.collectionVariables.set("callback_" + param[0], param[1]);
}

As variáveis callback_code, callback_id_token e callback_state ficam disponíveis para uso na chamada de Callback da Payment Initiation.

Diagrama Completo da Jornada de Autorização

sequenceDiagram
    participant Postman as Postman / App
    participant Celcoin as API Celcoin (ITP)
    participant Bricks as Detentora Bricks Demo

    Postman->>Celcoin: POST /payment-initiation
    Celcoin-->>Postman: { authorizationUrl, id }
    Note over Postman: Salva authorization_url<br/>e paymentInitiationId

    Postman->>Bricks: GET {{authorization_url}}<br/>(Follow Redirects: OFF)
    Bricks-->>Postman: 302 Location: ?interactionId=login_id
    Note over Postman: Salva login_interaction_id

    Postman->>Bricks: POST /interactions/login_id/login<br/>{ username, password }
    Bricks-->>Postman: { url: ?interactionId=consent_id }
    Note over Postman: Salva consent_interaction_id

    Postman->>Bricks: POST /interactions/consent_id/consent<br/>{}
    Bricks-->>Postman: { url: callback?code&id_token&state }
    Note over Postman: Salva callback_code,<br/>callback_id_token, callback_state

    Postman->>Celcoin: POST /payment-initiation/callback<br/>{ code, id_token, state }
    Celcoin-->>Postman: { status: AUTHORISED, consentId }

Exemplo de Uso — Sweeping Accounts

A collection de exemplo do Sweeping Accounts usa as seguintes URLs de sandbox:

Pontos de Atenção