Criar consentimento

Sweeping Accounts V2 - Payment Initiation API

Visão Geral

A API de Sweeping Accounts permite a criação de consentimentos para transferências automáticas de fundos (sweeping accounts). Este tipo de consentimento permite que uma instituição iniciadora de pagamento realize múltiplas transferências automáticas de uma conta do usuário pagador para outras contas do mesmo, respeitando limites configurados pelo próprio usuário.

Características Principais

Consentimento Recorrente: Permite múltiplas transações automáticas dentro de um período determinado
Limites Configuráveis: Suporta limites por transação, totais e periódicos (diário, semanal, mensal e anual)
Múltiplos Creditors: Permite configurar um ou mais recebedores para as transferências
Controle de Validade: Define data de início e expiração do consentimento

Endpoint

POST /open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation

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

{
    "brandId": "6894f1db86d49fedbec6cd13",
    "redirectUrl": "http://localhost:8080/callback",
    "data": {
        "creditors": [
            {
                "name": "João Silva",
                "cpfCnpj": "12345678909",
                "personType": "PESSOA_NATURAL"
            }
        ],
        "loggedUser": {
            "document": {
                "identification": "12345678909",
                "rel": "CPF"
            }
        },
        "recurringConfiguration": {
            "sweeping": {
                "totalAllowedAmount": "10000.00",
                "transactionLimit": "150.00",
                "periodicLimits": {
                    "day": {
                        "quantityLimit": 5,
                        "transactionLimit": "25.00"
                    },
                    "week": {
                        "quantityLimit": 5,
                        "transactionLimit": "100.00"
                    },
                    "month": {
                        "quantityLimit": 5,
                        "transactionLimit": "300.00"
                    },
                    "year": {
                        "quantityLimit": 5,
                        "transactionLimit": "10000.00"
                    }
                },
                "startDateTime": "2025-11-19T16:00:00Z"
            },
            "expirationDateTime": "2026-11-25T16:00:00Z"
        }
    }
}

Campos da Requisição

Nível Raiz

Campo	Tipo	Obrigatório	Descrição
`brandId`	String	Sim	Identificador único da brand (máximo 36 caracteres)
`redirectUrl`	URL	Sim	URL de redirecionamento autorizada pela aplicação
`data`	Object	Sim	Objeto contendo os dados do consentimento

Objeto `data`

Campo	Tipo	Obrigatório	Descrição
`loggedUser`	Object	Sim	Dados do usuário logado na instituição iniciadora
`creditors`	Array	Sim	Lista de recebedores (mínimo 1)
`recurringConfiguration`	Object	Sim	Configuração de recorrência

Objeto `loggedUser`

Campo	Tipo	Obrigatório	Descrição
`document`	Object	Sim	Documento de identificação do usuário

Objeto `document`

Campo	Tipo	Obrigatório	Descrição
`identification`	String	Sim	Número do documento (CPF: 11 dígitos)
`rel`	String	Sim	Tipo do documento (ex: "CPF")

Array `creditors`

Cada item do array deve conter:

Campo	Tipo	Obrigatório	Descrição
`name`	String	Sim	Nome completo (pessoa natural) ou razão social/fantasia (pessoa jurídica)
`cpfCnpj`	String	Sim	CPF (11 dígitos) ou CNPJ (14 dígitos) sem formatação
`personType`	Enum	Sim	Tipo de pessoa: `PESSOA_NATURAL` ou `PESSOA_JURIDICA`

Objeto `recurringConfiguration`

Campo	Tipo	Obrigatório	Descrição
`sweeping`	Object	Sim	Configuração de sweeping accounts
`expirationDateTime`	String	Não	Data de expiração do consentimento (padrão: 1 ano)

Objeto `sweeping`

Campo	Tipo	Obrigatório	Descrição
`totalAllowedAmount`	String	Não	Valor máximo total permitido para todas as transações (formato: "XXXXX.XX")
`transactionLimit`	String	Não	Valor máximo por transação (formato: "XXXXX.XX")
`periodicLimits`	Object	Não	Limites periódicos (ao menos um período deve ser configurado)
`startDateTime`	String	Sim	Data e hora de início do consentimento (RFC-3339 UTC)

Objeto `periodicLimits`

Permite configurar limites por período. Ao menos um período deve ser configurado:

Campo	Tipo	Obrigatório	Descrição
`day`	Object	Não	Limites diários
`week`	Object	Não	Limites semanais
`month`	Object	Não	Limites mensais
`year`	Object	Não	Limites anuais

Cada período (day, week, month, year) pode conter:

Campo	Tipo	Obrigatório	Descrição
`quantityLimit`	Number	Não*	Quantidade máxima de transações no período
`transactionLimit`	String	Não*	Valor máximo transacionado no período (formato: "XXXXX.XX")

Restrição: Ao menos um dos campos (quantityLimit ou transactionLimit) deve ser preenchido quando o período for informado.

Campo `expirationDateTime`

Campo	Tipo	Obrigatório	Descrição
`expirationDateTime`	String	Não	Data e hora de expiração (RFC-3339 UTC). Padrão: 1 ano a partir da criação

Formato de Valores Monetários

Todos os valores monetários devem seguir o formato:

Padrão: ^((\d{1,16}.\d{2}))$
Exemplo: "10000.00", "150.50", "25.00"
Mínimo: 4 caracteres (ex: "0.01")
Máximo: 19 caracteres

Formato de Datas

As datas devem seguir o padrão RFC-3339 com timezone UTC:

Formato: YYYY-MM-DDTHH:mm:ssZ
Exemplo: "2025-11-19T16:00:00Z"
Timezone: Sempre UTC (sufixo Z)

Validações Importantes

Creditors: Deve conter ao menos 1 recebedor
Periodic Limits: Ao menos um período (day, week, month ou year) deve ser configurado
Períodos Individuais: Quando um período é informado, ao menos um dos campos (quantityLimit ou transactionLimit) deve ser preenchido
Redirect URL: Deve estar cadastrada e autorizada para a aplicação
Brand ID: Deve existir no sistema

Implementação

Fluxo de Criação de Consentimento

A criação de consentimento pode ocorrer de duas formas, dependendo do escopo de autenticação:

1. Fluxo com `journey` (Redirecionamento)

Quando o token possui o escopo journey:

O sistema cria uma sessão de jornada (journey-session)
Cria o registro de payment initiation
Cria o consentimento na detentora de conta
Retorna a URL de autorização para redirecionamento

Uso: Quando o usuário precisa ser redirecionado para autorizar o consentimento na detentora de conta.

2. Fluxo com `app` (API Direta)

Quando o token possui o escopo app:

O sistema valida o redirectUrl da aplicação
Cria uma sessão de jornada automaticamente
Cria o registro de payment initiation
Cria o consentimento na detentora de conta
Retorna a URL de autorização

Uso: Para integrações diretas via API sem necessidade de redirecionamento imediato.

Exemplo de Requisição (cURL)

curl -X POST \
  https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "6894f1db86d49fedbec6cd13",
    "redirectUrl": "http://localhost:8080/callback",
    "data": {
        "creditors": [
            {
                "name": "João Silva",
                "cpfCnpj": "12345678909",
                "personType": "PESSOA_NATURAL"
            }
        ],
        "loggedUser": {
            "document": {
                "identification": "12345678909",
                "rel": "CPF"
            }
        },
        "recurringConfiguration": {
            "sweeping": {
                "totalAllowedAmount": "10000.00",
                "transactionLimit": "150.00",
                "periodicLimits": {
                    "day": {
                        "quantityLimit": 5,
                        "transactionLimit": "25.00"
                    },
                    "week": {
                        "quantityLimit": 5,
                        "transactionLimit": "100.00"
                    },
                    "month": {
                        "quantityLimit": 5,
                        "transactionLimit": "300.00"
                    },
                    "year": {
                        "quantityLimit": 5,
                        "transactionLimit": "10000.00"
                    }
                },
                "startDateTime": "2025-11-19T16:00:00Z"
            }
        }
    }
}'

Exemplo de Requisição (JavaScript/Node.js)

const axios = require("axios");

const createSweepingAccountsConsent = async () => {
    try {
        const response = await axios.post(
            "https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation",
            {
                brandId: "6894f1db86d49fedbec6cd13",
                redirectUrl: "http://localhost:8080/callback",
                data: {
                    creditors: [
                        {
                            name: "João Silva",
                            cpfCnpj: "12345678909",
                            personType: "PESSOA_NATURAL",
                        },
                    ],
                    loggedUser: {
                        document: {
                            identification: "12345678909",
                            rel: "CPF",
                        },
                    },
                    recurringConfiguration: {
                        sweeping: {
                            totalAllowedAmount: "10000.00",
                            transactionLimit: "150.00",
                            periodicLimits: {
                                day: {
                                    quantityLimit: 5,
                                    transactionLimit: "25.00",
                                },
                                week: {
                                    quantityLimit: 5,
                                    transactionLimit: "100.00",
                                },
                                month: {
                                    quantityLimit: 5,
                                    transactionLimit: "300.00",
                                },
                                year: {
                                    quantityLimit: 5,
                                    transactionLimit: "10000.00",
                                },
                            },
                            startDateTime: "2025-11-19T16:00:00Z",
                        },
                    },
                },
            },
            {
                headers: {
                    Authorization: "Bearer YOUR_ACCESS_TOKEN",
                    "Content-Type": "application/json",
                },
            },
        );

        console.log("Consentimento criado:", response.data);
        return response.data;
    } catch (error) {
        console.error(
            "Erro ao criar consentimento:",
            error.response?.data || error.message,
        );
        throw error;
    }
};

createSweepingAccountsConsent();

Exemplo de Requisição (Python)

import requests

def create_sweeping_accounts_consent():
    url = "https://api.exemplo.com/open-keys/itp/api/v2/sweeping-accounts/v2/payment-initiation"

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

    payload = {
        "brandId": "6894f1db86d49fedbec6cd13",
        "redirectUrl": "http://localhost:8080/callback",
        "data": {
            "creditors": [
                {
                    "name": "João Silva",
                    "cpfCnpj": "12345678909",
                    "personType": "PESSOA_NATURAL"
                }
            ],
            "loggedUser": {
                "document": {
                    "identification": "12345678909",
                    "rel": "CPF"
                }
            },
            "recurringConfiguration": {
                "sweeping": {
                    "totalAllowedAmount": "10000.00",
                    "transactionLimit": "150.00",
                    "periodicLimits": {
                        "day": {
                            "quantityLimit": 5,
                            "transactionLimit": "25.00"
                        },
                        "week": {
                            "quantityLimit": 5,
                            "transactionLimit": "100.00"
                        },
                        "month": {
                            "quantityLimit": 5,
                            "transactionLimit": "300.00"
                        },
                        "year": {
                            "quantityLimit": 5,
                            "transactionLimit": "10000.00"
                        }
                    },
                    "startDateTime": "2025-11-19T16:00:00Z"
                }
            }
        }
    }

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

    return response.json()

result = create_sweeping_accounts_consent()
print("Consentimento criado:", result)

Resposta da API

Sucesso (200 OK)

A API retorna um objeto contendo:

{
    "id": "uuid-do-payment-initiation",
    "brandId": "6894f1db86d49fedbec6cd13",
    "redirectUrl": "http://localhost:8080/callback",
    "data": {
        // ... dados enviados na requisição
    },
    "journeySessionId": "uuid-da-journey-session",
    "applicationId": "uuid-da-aplicacao",
    "paymentInitiationApi": "SWEEPING_ACCOUNTS_V2",
    "ofConsentId": "id-do-consentimento-na-detentora",
    "authorizationUrl": "https://detentora.com/authorize?consent_id=...",
    "status": "AWAITING_AUTHORISATION",
    "createdAt": 1234567890,
    "updatedAt": 1234567890
}

Campos Importantes da Resposta

Campo	Tipo	Descrição
`id`	String	Identificador único do payment initiation
`journeySessionId`	String	ID da sessão de jornada criada
`ofConsentId`	String	ID do consentimento na detentora de conta
`authorizationUrl`	String	URL para redirecionamento do usuário para autorização
`status`	String	Status atual do consentimento

Erros Comuns

400 Bad Request

{
    "error": "Validation Error",
    "message": "Campo 'startDateTime' é obrigatório"
}

Causas comuns:

Campos obrigatórios ausentes
Formato de dados inválido (datas, valores monetários)
Validação de schema falhou

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": "this redirectUrl is not allowed for this application"
}

Solução: Certifique-se de que o redirectUrl está cadastrado e autorizado para a aplicação.

404 Not Found

{
    "error": "Not Found",
    "message": "Brand não encontrada"
}

Solução: Verifique se o brandId informado existe no sistema.

Boas Práticas

Validação de Dados: Valide todos os dados antes de enviar a requisição
Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
Segurança: Nunca exponha tokens de acesso no frontend ou logs
URLs de Redirecionamento: Use HTTPS em produção para redirectUrl
Limites: Configure limites apropriados para proteger o usuário
Datas: Sempre use UTC para datas e horários
Valores Monetários: Valide o formato antes de enviar (mínimo 4 caracteres, máximo 19)

Limites e Restrições

Creditors: Mínimo de 1 recebedor
Periodic Limits: Ao menos um período deve ser configurado
Valores Monetários: Formato XXXXX.XX (mínimo 4, máximo 19 caracteres)
Datas: Formato RFC-3339 UTC obrigatório
Redirect URL: Deve estar autorizada para a aplicação

Notas Adicionais

O consentimento criado precisa ser autorizado pelo usuário na detentora de conta através da authorizationUrl retornada
Após a autorização, o status do consentimento será atualizado
O campo expirationDateTime é opcional e, quando não informado, o padrão é 1 ano a partir da criação
A API suporta múltiplos creditors, permitindo configurar vários recebedores em um único consentimento

Updated about 5 hours ago