Pix Instantâneo - ITP (Jornada com Redirecionamento)

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link

Visão Geral

O Pix Instantâneo via ITP (Instituição de Pagamento Transmissora) permite que sua plataforma inicie pagamentos Pix em nome de clientes diretamente via Open Finance Brasil, sem a necessidade de manter contas ou saldos. A ITP atua como intermediadora que conecta o usuário pagador à sua instituição financeira (detentora de conta), obtendo um consentimento único por pagamento.

A Jornada com Redirecionamento é o fluxo padrão do Open Finance, baseado em OAuth 2.0 Authorization Code Flow (FAPI): o usuário é redirecionado para o ambiente da detentora para autenticação e aprovação, e retorna à ITP após a conclusão.

Casos de uso

• Checkout com Pix Open Finance em e-commerce
• Pagamentos B2B com rastreabilidade via Open Finance
• Transferências para terceiros a partir de qualquer conta bancária do usuário

Fluxo Resumido

sequenceDiagram
    participant ITP
    participant Detentora as Detentora (ASPSP)
    participant Usuario as Usuário

    ITP->>Detentora: POST /payment-initiation
    Detentora-->>ITP: { authorizationUrl, id }

    ITP->>Usuario: Redireciona para authorizationUrl
    Usuario->>Detentora: Login + Approve
    Detentora->>Usuario: callback?code&state

    Usuario->>ITP: Recebe callback (code, state, id_token)
    ITP->>Detentora: POST /callback
    Detentora-->>ITP: { ticket_url, id }

    ITP->>Detentora: GET /pix
    Detentora-->>ITP: { paymentId, status }

Etapas da Jornada

Pontos de Atenção

⚠️

Consentimento por pagamento: Diferente do Sweeping Accounts, a jornada com redirecionamento gera um consentimento por transação. Cada pagamento exige uma nova autorização do usuário.

⚠️

authorizationUrl é de uso único: A URL de autorização gerada na criação do consentimento expira em poucos minutos. Redirecione o usuário imediatamente após recebê-la.

⚠️

redirectUrl deve estar registrada: A URL de callback informada na criação deve ser pré-registrada. Em sandbox, http://localhost:8080/callback é aceita.

⚠️

code expira rapidamente: Após o redirect de volta à ITP com o code no callback, chame imediatamente o endpoint /callback para trocá-lo pelo ticket. Atrasos causam erros invalid_request_uri.

⚠️

Liquidação assíncrona: O endpoint de Pix retorna imediatamente com status PDNG. A liquidação final é confirmada via webhook ou polling.

Navegação

• ITP - Criar Consentimento (Payment Initiation)
• ITP - Callback do Consentimento
• ITP - Consultas
• ITP - Webhooks
• ITP - Máquina de Estados - Pix ITP
• ITP - Códigos de Resposta HTTP
• ITP - Possíveis Erros de Pagamento