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
  }
}'

O connectorId será aquele associado à instituição da sua conta devedor (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 Configurando limites de transação).

Para mais detalhes sobre este endpoint, consulte 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
  },
  "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.

Criar um destinatário de pagamento#

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

Configurando limites de transação#

Criar um destinatário de pagamento #

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

Configurando limites de transação #