Cancelamento de consentimento

Visão Geral

A API permite o cancelamento de consentimentos de sweeping accounts. O cancelamento pode ser realizado tanto para consentimentos que ainda estão aguardando autorização quanto para consentimentos já autorizados.

Endpoint

PATCH /open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation/{id}

Onde {id} é o identificador único do payment initiation retornado na criação do consentimento.

Autenticação

A API requer autenticação OAuth2 com uma das seguintes permissões:

• journey: Para fluxos que utilizam redirecionamento à detentora de conta
• app: Para integrações diretas via API

O token de acesso deve ser enviado no header:

Authorization: Bearer {access_token}

Estrutura da Requisição

Payload Completo

{
    "data": {
        "status": "CANC",
        "cancellation": {
            "cancelledBy": {
                "document": {
                    "identification": "12345678909",
                    "rel": "CPF"
                }
            }
        }
    }
}

Campos da Requisição

Nível Raiz

Objeto data

Objeto cancellation

Objeto cancelledBy

Objeto document

Validações Importantes

1. Status: O campo status deve ser exatamente "CANC"
2. Documento: O CPF informado em cancellation.cancelledBy.document.identification deve corresponder ao CPF do usuário logado (quando usando escopo journey)
3. Estado do Consentimento: O consentimento deve estar em um estado cancelável:
   • AWAITING_AUTHORISATION
   • AUTHORISED
   • PARTIALLY_ACCEPTED
4. Payment Initiation ID: O id informado na URL deve existir e pertencer à aplicação autenticada

Implementação

Fluxo de Cancelamento

O cancelamento pode ocorrer de duas formas, dependendo do escopo de autenticação:

1. Fluxo com journey (Redirecionamento)

Quando o token possui o escopo journey:

1. O sistema valida o opaqueTokenId do usuário
2. Busca o CPF do usuário na sessão de jornada
3. Valida que o CPF informado corresponde ao usuário logado
4. Verifica o estado atual do consentimento na detentora de conta
5. Se o consentimento estiver autorizado, cancela todos os pagamentos pendentes
6. Cancela o consentimento na detentora de conta
7. Atualiza o status da sessão de jornada
8. Retorna o payment initiation atualizado

Uso: Quando o cancelamento é realizado pelo usuário através do fluxo de jornada.

2. Fluxo com app (API Direta)

Quando o token possui o escopo app:

1. O sistema valida a aplicação autenticada
2. Verifica o estado atual do consentimento na detentora de conta
3. Se o consentimento estiver autorizado, cancela todos os pagamentos pendentes
4. Cancela o consentimento na detentora de conta
5. Atualiza o status da sessão de jornada
6. Retorna o payment initiation atualizado

Uso: Para cancelamentos realizados diretamente via API pela aplicação.

Comportamento do Cancelamento

Consentimentos Aguardando Autorização

Quando um consentimento está em AWAITING_AUTHORISATION ou PARTIALLY_ACCEPTED:

• O consentimento é cancelado diretamente na detentora de conta
• O status da sessão de jornada é atualizado para CANCELLED
• Nenhum pagamento precisa ser cancelado (pois ainda não foram criados)

Consentimentos Autorizados

Quando um consentimento está em AUTHORISED:

1. Cancelamento do Consentimento: Após cancelar os pagamentos, o consentimento é cancelado na detentora de conta
2. Atualização de Status: O status da sessão de jornada é atualizado para CANCELLED

Exemplo de Requisição (cURL)

curl -X PATCH \
  https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v1/payment-initiation/{id} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
        "status": "CANC",
        "cancellation": {
            "cancelledBy": {
                "document": {
                    "identification": "12345678909",
                    "rel": "CPF"
                }
            }
        }
    }
}'

import requests

def cancel_sweeping_accounts_consent(payment_initiation_id):
    url = f"https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v1/payment-initiation/{payment_initiation_id}"

    headers = {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    }

    payload = {
        "data": {
            "status": "CANC",
            "cancellation": {
                "cancelledBy": {
                    "document": {
                        "identification": "12345678909",
                        "rel": "CPF"
                    }
                }
            }
        }
    }

    response = requests.patch(url, json=payload, headers=headers)
    response.raise_for_status()

    return response.json()

result = cancel_sweeping_accounts_consent("uuid-do-payment-initiation")
print("Consentimento cancelado:", result)

Resposta da API

Sucesso (200 OK)

A API retorna um objeto contendo o payment initiation atualizado:

{
    "id": "uuid-do-payment-initiation",
    "brandId": "6894f1db86d49fedbec6cd13",
    "redirectUrl": "http://localhost:8080/callback",
    "data": {
        // ... dados originais do consentimento
    },
    "journeySessionId": "uuid-da-journey-session",
    "applicationId": "uuid-da-aplicacao",
    "paymentInitiationApi": "SWEEPING_ACCOUNTS_V2",
    "ofConsentId": "id-do-consentimento-na-detentora",
    "ofConsent": {
        "status": "REVOKED"
        // ... outros dados do consentimento
    },
    "ofPayments": [
        // ... lista de pagamentos (se houver)
    ],
    "status": "CANCELLED",
    "createdAt": 1234567890,
    "updatedAt": 1234567890
}

Campos Importantes da Resposta

Erros Comuns

400 Bad Request

{
    "error": "Validation Error",
    "message": "Campo 'status' deve ser 'CANC'"
}

Causas comuns:

• Campo status com valor diferente de "CANC"
• Campos obrigatórios ausentes
• Formato de documento inválido

401 Unauthorized

{
    "error": "Unauthorized",
    "message": "Token inválido ou expirado"
}

Solução: Verifique se o token de acesso é válido e possui as permissões necessárias (journey ou app).

403 Forbidden

{
    "error": "Forbidden",
    "message": "cpf not found"
}

Solução: Quando usando escopo journey, certifique-se de que o CPF informado corresponde ao usuário logado na sessão de jornada.

404 Not Found

{
    "error": "Not Found",
    "message": "Payment initiation não encontrado"
}

Solução: Verifique se o id informado na URL existe e pertence à aplicação autenticada.

422 Unprocessable Entity

{
    "error": "Unprocessable Entity",
    "message": "cannot cancel consent with status: CONSUMED"
}

Solução: O consentimento não pode ser cancelado porque já foi consumido ou está em um estado que não permite cancelamento.