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.

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 APIAPI para saber como usar este endpoint. Para saber o paymentInstitutionId, você precisa usar este endpointAPI.

Isso retornará a seguinte resposta:

{
  "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:

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).
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.

Para mais detalhes sobre este endpoint, verifique nossa documentação da APIAPI.

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.

Isso retornará a seguinte resposta:

{
  "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 endpointAPI, 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, 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:

{
  "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.

{
  "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.

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). Leia o saldo bem antes de uma transferência, não em um cronograma.

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.

Criar um destinatário de pagamento#

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

Configurando limites de transação#

Saldo da conta de origem#

Status da permissão#

Ler o saldo#

Cancelar apenas a permissão#