ITP - Callback do Consentimento

Visão Geral

Após o usuário aprovar o consentimento na detentora, ele é redirecionado de volta para a redirectUrl da ITP com os parâmetros code, id_token e state na query string. A ITP deve então enviar esses parâmetros ao endpoint de callback para finalizar o consentimento e obter o ticket que habilita a execução do pagamento.

Para este produto, esta API de callback também já realiza a execução do Pagamento PIX.

Processar Callback

POST /baas/v1/open/itp/payment-initiation/callback

Troca o authorization code recebido pelo ticket de pagamento, validando o consentimento junto à detentora.

Autenticação: Bearer Token (application_token)

Request

POST {{base_url}}/baas/v1/open/itp/payment-initiation/callback
Authorization: Bearer {{application_token}}
Content-Type: application/json

{
  "code": "{{callback_code}}",
  "id_token": "{{callback_id_token}}",
  "state": "{{callback_state}}"
}

Response — HTTP 201 (Sucesso)

{
  "url": "https://localhost:8080?ticket=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&state=yfPdbpcWgHQo1VL5vrYzd0xIRuxEUJqPO5ufvEN2esA",
  "id": "yfPdbpcWgHQo1VL5vrYzd0xIRuxEUJqPO5ufvEN2esA"
}

Response — HTTP 201 (Rejeição pelo usuário)

Quando o usuário rejeitou o consentimento, o code recebido é inválido e o callback retorna erro na URL:

{
  "url": "https://localhost:8080?error=access_denied&state=B4n5M1_k2TZumVvIeGZApmijLZ4dTlwtbLJpg3PCfE0"
}

Verifique a presença do parâmetro error na url retornada para detectar rejeições.

Códigos de Retorno

Como Capturar os Parâmetros do Callback

Em uma aplicação web, os parâmetros chegam na query string da redirectUrl:

http://localhost:8080/callback?code=AUTH_CODE_AQUI&id_token=ID_TOKEN_AQUI&state=STATE_AQUI

Exemplo de extração em JavaScript:

const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const id_token = params.get('id_token');
const state = params.get('state');
const error = params.get('error');

if (error) {
  // Usuário rejeitou ou erro de autorização
  console.error('Autorização negada:', error);
  return;
}

// Enviar ao backend para chamar POST /callback
await fetch('/api/itp/callback', {
  method: 'POST',
  body: JSON.stringify({ code, id_token, state })
});

Ciclo de Vida do Pagamento

O pagamento percorre os seguintes status após a chamada ao endpoint:

stateDiagram-v2
    direction LR

    [*] --> PDNG : POST /pix

    PDNG --> ACSP : Enviado ao SPI
    PDNG --> RJCT : Falha na validação

    ACSP --> ACSC : Liquidado com sucesso
    ACSP --> RJCT : Falha na liquidação

    ACSC --> [*]
    RJCT --> [*]

    classDef terminal   fill:#f5c6c6,stroke:#c0392b,color:#333
    classDef success    fill:#d5f5d5,stroke:#27ae60,color:#333
    classDef inprogress fill:#fef9c3,stroke:#f39c12,color:#333
    classDef initial    fill:#c6e2f5,stroke:#2980b9,color:#333

    class RJCT terminal
    class ACSC success
    class ACSP inprogress
    class PDNG initial

Acompanhar o Status do Pagamento

Como o processamento é assíncrono, utilize uma das estratégias abaixo:

Opção 1 — Webhook (recomendado)

Configure um endpoint de webhook para receber notificações automáticas de mudança de status. Consulte Webhooks para detalhes.

Opção 2 — Polling

Consulte o status do pagamento periodicamente usando o endpoint de detalhamento da payment initiation:

GET {{base_url}}/baas/v1/open/itp/payment-initiation/{{itp_payment_id}}
Authorization: Bearer {{application_token}}

Intervalo recomendado: A cada 2-5 segundos, por no máximo 60 segundos. Após esse período, assuma timeout e notifique o usuário para verificar mais tarde.

Pontos de Atenção

⚠️

Chame o callback imediatamente: O code tem vida útil curtíssima. O endpoint /callback deve ser chamado de forma síncrona logo após o redirect. Qualquer atraso (processamento no front-end, navegação extra) pode causar falha por expiração.

⚠️

state como correlator: O state identifica a qual payment initiation o callback pertence. Nunca descarte ou modifique este valor. Em sistemas com múltiplos pagamentos simultâneos, use o state para roteamento correto.

⚠️

Trate o error na URL de retorno: Mesmo com HTTP 201, o campo url pode conter ?error=access_denied. Sempre verifique a ausência de error antes de considerar o callback como sucesso.

⚠️

id retornado = itp_payment_id: O id retornado neste endpoint é o mesmo da payment initiation e deve ser usado como path parameter no endpoint de Pix: POST /payment-initiation/:id/pix.