# Criando uma pré-autorização

Nesta seção, você aprenderá como criar uma pré-autorização para realizar pagamentos sem interação do usuário.

## Criar um destinatário de pagamento

Primeiro, você precisa criar **Destinatários de Pagamento**. Estes serão os destinos permitidos para enviar transferências. Todos os destinatários devem pertencer ao mesmo proprietário.

```shell
curl --location 'https://api.pluggy.ai/payments/recipients' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ••••••' \
--data '{
  "account": {
    "type": "CHECKING_ACCOUNT",
    "number": "1111111",
    "branch": "0001"
  },
  "paymentInstitutionId": "abfd2a88-bc7b-407f-9fcc-395548ee6840",
  "name": "John Doe",
  "taxNumber": "11111111111"
}'
```

Verifique a [documentação da API](/reference/payment-recipient/payment-recipient-create) para saber como usar este endpoint. Para saber o `paymentInstitutionId`, você precisa usar este [endpoint](/reference/payment-recipient/payment-recipients-institution-list).

Isso retornará a seguinte resposta:

```json
{
  "type": "BANK_ACCOUNT",
  "id": "ded2e966-bd40-4e82-b467-d32fe4b4f40e",
  "name": "John Doe",
  "taxNumber": "11111111111",
  "isDefault": false,
  "paymentInstitution": {
    "id": "abfd2a88-bc7b-407f-9fcc-395548ee6840",
    "name": "Banco XP S.A.",
    "tradeName": "BCO XP S.A.",
    "ispb": "33264668",
    "compe": "348",
    "createdAt": "2023-12-08T17:52:21.001Z",
    "updatedAt": "2023-12-08T17:52:21.001Z"
  },
  "account": {
    "type": "CHECKING_ACCOUNT",
    "number": "1111111",
    "branch": "0001"
  },
  "pixKey": null,
  "createdAt": "2024-08-01T16:32:29.276Z",
  "updatedAt": "2024-08-01T16:32:29.276Z"
}
```

## Criar a Pré-autorização de Transferência Inteligente

Agora, você está pronto para criar uma pré-autorização de transferência inteligente. Para fazer isso, você precisa realizar a seguinte solicitação:

```shell
curl --location 'https://api.pluggy.ai/smart-transfers/preauthorizations' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ••••••' \
--data '{
  "connectorId": 612,
  "parameters": {
    "cpf": "11111111111"
  },
  "recipientIds": [
    "ded2e966-bd40-4e82-b467-d32fe4b4f40e"
  ],
  "callbackUrls": {
    "success": "https://my-success-page.com",
    "error": "https://my-error-page.com"
  },
  "configuration": {
    "transactionLimit": 100
  },
  "linkedJourney": true
}'
```

- O `connectorId` será aquele associado à instituição da sua conta devedora (por exemplo, se você quiser criar a pré-autorização no Nubank, você precisa enviar o id `612`).

- Você pode configurar os limites de transação enviando o campo `configuration` (veja a [seção de Configuração de limites de transação](#configuring-transaction-limits)).

- **linkedJourney** (opcional, padrão falso): também peça ao usuário, na mesma aprovação no banco, permissão para ler o saldo da conta de origem. Veja [Saldo da conta de origem](#source-account-balance).

  Para mais detalhes sobre este endpoint, verifique nossa [documentação da API](/reference/smart-transfer/smart-transfer-preauthorization-create).

<Callout variant="warning" title="Importante">
Para contas PF, você pode configurar apenas um destinatário por autorização. Apenas contas PJ podem configurar múltiplos destinatários para a mesma autorização.
</Callout>

Isso retornará a seguinte resposta:

```json
{
  "id": "7e3e1dbb-8009-4966-9254-1eaab05ad18b",
  "status": "CREATED",
  "consentUrl": "https://this-is-the-consent-url.com",
  "clientPreauthorizationId": null,
  "callbackUrls": null,
  "recipients": [
    {
      "type": "BANK_ACCOUNT",
      "id": "ded2e966-bd40-4e82-b467-d32fe4b4f40e",
      "name": "John Doe",
      "taxNumber": "11111111111",
      "isDefault": false,
      "paymentInstitution": {
        "id": "abfd2a88-bc7b-407f-9fcc-395548ee6840",
        "name": "Banco XP S.A.",
        "tradeName": "BCO XP S.A.",
        "ispb": "33264668",
        "compe": "348",
        "createdAt": "2023-12-08T17:52:21.001Z",
        "updatedAt": "2023-12-08T17:52:21.001Z"
      },
      "account": {
        "type": "CHECKING_ACCOUNT",
        "number": "1111111",
        "branch": "0001"
      },
      "pixKey": null,
      "createdAt": "2024-07-31T15:56:03.938Z",
      "updatedAt": "2024-07-31T15:56:23.123Z"
    }
  ],
  "connector": {
    "id": 612,
    "name": "Nubank",
    "primaryColor": "8a0fbe",
    "institutionUrl": "https://nuapp.nubank.com.br/open-banking/logo.svg",
    "country": "BR",
    "type": "PERSONAL_BANK",
    "credentials": [
      {
        "validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
        "validationMessage": "CPF deve ter 11 numeros.",
        "label": "CPF",
        "name": "cpf",
        "type": "number",
        "placeholder": "",
        "optional": false
      }
    ],
    "imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/212.svg",
    "hasMFA": false,
    "oauth": true,
    "health": {
      "status": "ONLINE",
      "stage": null
    },
    "products": [
      "ACCOUNTS",
      "TRANSACTIONS",
      "IDENTITY",
      "CREDIT_CARDS",
      "PAYMENT_DATA",
      "LOANS",
      "INVESTMENTS"
    ],
    "createdAt": "2023-09-01T18:05:09.145Z",
    "isSandbox": false,
    "isOpenFinance": true,
    "updatedAt": "2024-08-01T16:33:57.978Z",
    "supportsPaymentInitiation": true,
    "supportsScheduledPayments": true,
    "supportsSmartTransfers": true
  },
  "dataConsent": {
    "status": "AWAITING_AUTHORISATION",
    "rejectionReason": null,
    "updatedAt": "2026-10-07T18:43:08.390Z"
  },
  "createdAt": "2024-08-01T16:39:27.946Z",
  "updatedAt": "2024-08-01T16:39:32.448Z"
}
```

Após a pré-autorização ser criada, você precisa redirecionar seu usuário para a `consentUrl` retornada na resposta. Lá, o usuário precisa aprovar a pré-autorização em sua instituição de pagamento. Após o consentimento ser dado, o usuário será redirecionado para a URL de callback `success` se tudo estiver ok, ou para a URL de callback `error` se o consentimento for rejeitado ou se ocorrer um erro no processo.

Nota: se você não definir um conjunto de `callbackUrls`, o usuário será redirecionado para uma página padrão da Pluggy.

Agora, se você verificar o status da pré-autorização usando [este endpoint](/reference/smart-transfer/smart-transfer-preauthorization-retrieve), você verá com um dos seguintes status:

- **COMPLETED**: A pré-autorização foi concluída e você está pronto para criar pagamentos.
- **REJECTED**: O usuário rejeitou a pré-autorização no fluxo de consentimento da instituição.
- **ERROR**: Ocorreu um erro no fluxo de consentimento da instituição.

Na [próxima seção](/docs/smart-transfers/creating-payment), você verá como criar um pagamento sem interação do usuário.

## Configurando limites de transação

Você pode configurar os limites de transação enviando o objeto `configuration`.

| Campo | Tipo | Opcional | Descrição |
|-------|------|----------|-------------|
| totalAllowedAmount | number | true | Valor máximo a ser alcançado pela soma de todas as transações que utilizam o consentimento autorizado pelo cliente. |
| transactionLimit | number | true | Valor máximo para cada transação de pagamento associada a este consentimento. |
| periodicLimits | object | true | Limites transacionais por período conforme determinado pelo usuário pagador. |

No objeto `periodicLimits`, você pode configurar os limites por período. Os períodos disponíveis são `day`, `week`, `month` e `year`, e para cada um você pode configurar:

| Campo | Tipo | Opcional | Descrição |
|-------|------|----------|-------------|
| quantityLimit | number | true | Número máximo de transações permitidas a ocorrer no período. |
| transactionLimit | number | true | Valor máximo a ser transacionado no período. |

Exemplo:

```json
{
  "configuration": {
    "totalAllowedAmount": 100.5,
    "transactionLimit": 10,
    "periodicLimits": {
      "day": {
        "quantityLimit": 2,
        "transactionLimit": 5
      },
      "week": {
        // limites semanais
      },
      "month": {
        // limites mensais
      },
      "year": {
        // limites anuais
      }
    }
  }
}
```

No caso de algum limite ser atingido, você receberá um erro apropriado da API.

## Saldo da conta de origem

As Transferências Inteligentes são pagas da conta do usuário sem uma nova aprovação, portanto, uma transferência pode ser rejeitada por saldo insuficiente. Crie a pré-autorização com `linkedJourney: true` para também pedir ao usuário, na mesma aprovação no banco, permissão para ler o saldo da conta de origem. Nada mais muda no redirecionamento, no retorno ou nas transferências.

### Status da permissão

A pré-autorização carrega um objeto `dataConsent` enquanto a permissão existir. Ele é `null` quando `linkedJourney` não foi solicitado, e também pode ser `null` quando a permissão de saldo não está disponível para aquela instituição ou ambiente. Nesse caso, a pré-autorização é criada normalmente, sem a permissão.

| `status` | Significado |
|---|---|
| `AWAITING_AUTHORISATION` | O usuário ainda não aprovou. |
| `AUTHORISED` | O saldo pode ser lido. |
| `REJECTED` | Rejeitado, revogado, cancelado ou expirado. Não volta; `rejectionReason` diz o porquê. |

A permissão termina com a pré-autorização. Se o usuário revogar qualquer uma delas em seu banco, o endpoint de saldo responde `403`, e o status armazenado ainda pode ler `AUTHORISED` até que a instituição reporte a mudança.

`dataConsent` é atualizado pela instituição quando você recupera a pré-autorização pelo id. A lista retorna o último status conhecido. `updatedAt` é quando a Pluggy viu pela última vez a mudança de status.

### Ler o saldo

`GET /smart-transfers/preauthorizations/{id}/balance` lê o saldo da conta de origem em tempo real da instituição. Os valores estão em BRL.

```json
{
  "balance": 5.48,
  "overdraft": {
    "contracted": 1000,
    "used": 0,
    "available": 1000
  }
}
```

`overdraft` é o limite de cheque especial da conta: quanto foi contratado, quanto está em uso e quanto ainda está disponível. É `null` quando a instituição não o compartilha.

| Status | `codeDescription` | Significado |
|---|---|---|
| `200` | | Saldo lido. |
| `400` | `SMART_TRANSFER_DATA_CONSENT_NOT_REQUESTED` | A pré-autorização foi criada sem `linkedJourney`. |
| `403` | `SMART_TRANSFER_DATA_CONSENT_NOT_AVAILABLE` | A permissão está pendente, rejeitada ou revogada. |
| `429` | `BALANCE_OPEN_FINANCE_RATE_LIMIT` | O limite de taxa na instituição foi atingido, por exemplo, a cota mensal de saldo da conta. |

<Callout variant="warning" title="Cada chamada conta para a cota da instituição">
Cada chamada lê o saldo da instituição, sem cache. Open Finance limita as leituras de saldo por conta por mês (veja [Limites Operacionais de Taxa](/docs/open-finance/rate-limits)). Leia o saldo bem antes de uma transferência, não em um cronograma.
</Callout>

### Cancelar apenas a permissão

`DELETE /smart-transfers/preauthorizations/{id}/data-consent` cancela a permissão de saldo e retorna a pré-autorização com `dataConsent.status` definido como `REJECTED`. A pré-autorização permanece ativa e suas transferências continuam funcionando. Uma permissão não pode ser adicionada a uma pré-autorização existente: crie uma nova com `linkedJourney`.

| Status | `codeDescription` | Significado |
|---|---|---|
| `200` | | Permissão cancelada, ou já havia terminado. |
| `400` | `SMART_TRANSFER_DATA_CONSENT_NOT_REQUESTED` | A pré-autorização foi criada sem `linkedJourney`. |
| `403` | `SMART_TRANSFER_DATA_CONSENT_NOT_AVAILABLE` | A instituição não aceitou o cancelamento, por exemplo, porque o usuário ainda não aprovou a permissão. |
| `429` | `BALANCE_OPEN_FINANCE_RATE_LIMIT` | O limite de taxa na instituição foi atingido. |

Cancelar uma permissão que já terminou (rejeitada, revogada, ou sua pré-autorização revogada ou rejeitada) responde `200` com `status: REJECTED`, então tentar novamente é seguro.