Sweeping Accounts - Criação de Payment Initiation

Visão Geral

A payment initiation é o objeto central do Sweeping Accounts. Ela define as regras do consentimento recorrente: quem é o recebedor, quais os limites de valor por transação e por período, e qual o teto total autorizado. Após criada, retorna uma authorizationUrl para onde o usuário deve ser redirecionado para aprovar o consentimento na detentora de conta.

Criar Payment Initiation

POST /v1/open/itp/sweeping-accounts/payment-initiation

Cria uma nova payment initiation de Sweeping Accounts.

Autenticação: Bearer Token (application_token)

Request

POST /v1/open/itp/sweeping-accounts/payment-initiation
Authorization: Bearer {{application_token}}
Content-Type: application/json

{
  "brandId": "{{brand_id}}",
  "redirectUrl": "https://seu-dominio.com/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": "2026-02-12T00:00:00Z"
      }
    }
  }
}

Campos do Request

Nível raiz

data.creditors[]

data.loggedUser.document

data.recurringConfiguration.sweeping

data.recurringConfiguration.sweeping.periodicLimits

Ao menos um período deve ser informado. Os limites devem ser coerentes (diário ≤ semanal ≤ mensal ≤ anual).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "authorizationUrl": "https://detentora.exemplo.com.br/auth?request_uri=...&client_id=...",
  "status": "PENDING",
  "createdAt": "2026-02-12T10:00:00Z"
}

Códigos de Retorno

Pontos de Atenção

⚠️

Identidade do creditor: O cpfCnpj do creditor deve ser idêntico ao loggedUser.document.identification. O Sweeping Accounts é exclusivamente para transferências entre contas do mesmo titular. Divergências causam rejeição imediata.

⚠️

Coerência dos limites periódicos: Os valores de transactionLimit devem respeitar a hierarquia: day ≤ week ≤ month ≤ year. O mesmo vale para quantityLimit. Limites inconsistentes resultam em erro 422.

⚠️

totalAllowedAmount: Este é o teto absoluto do consentimento. Quando a soma de todos os pagamentos executados atingir esse valor, o consentimento expira automaticamente. Planeje esse valor com cuidado para não interromper o fluxo do cliente antes do esperado.

⚠️

redirectUrl: A URL de callback deve estar pré-registrada e acessível. Em sandbox, pode-se usar http://localhost:8080/callback. Em produção, utilize um domínio válido com HTTPS.

⚠️

startDateTime: A vigência do consentimento começa nesta data. Transações de pagamento só podem ser executadas após esta data. Use sempre UTC (sufixo Z).

⚠️

Guarde o id retornado: O paymentInitiationId é necessário para todas as operações subsequentes: consulta, execução de pagamentos e cancelamento.