# Creating a preauthorization

In this section, you will learn how to create a preauthorization to do payments without user interaction.

## Create a payment recipient

First, you need to create **Payment Recipients**. Those will be the allowed destinations to send transfers. All of recipients must belong to the same owner.

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

Check the [API docs](/reference/payment-recipient/payment-recipient-create) to know how to use this endpoint. To know the `paymentInstitutionId`, you need to use this [endpoint](/reference/payment-recipient/payment-recipients-institution-list).

This will return the following response:

```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"
}
```

## Create the Smart Transfer Preauthorization

Now, you are ready to create a smart transfer preauthorization. To do that, you need to do the following request:

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

- The `connectorId` will be the one associated with the institution of your debtor account (for example, if you want to create the preauthorization in Nubank, you need to send the id `612`).

- You can configure the transaction limits sending the `configuration` field (see [Configuring transaction limits section](#configuring-transaction-limits)).

  For more details about this endpoint, check our [API docs](/reference/smart-transfer/smart-transfer-preauthorization-create).

> **Important: For PF accounts you can only configure one recipient per authorization. Only PJ accounts can configure multiple recipients for the same authorization.**

This will return the following response:

```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
  },
  "createdAt": "2024-08-01T16:39:27.946Z",
  "updatedAt": "2024-08-01T16:39:32.448Z"
}
```

After the preauthorization is created, you need to redirect your user to the `consentUrl` returned in the response. There, the user needs to approve the preauthorization in their payment institution. After the consent is given, the user will be redirected to the `success` callback url if everything is ok, or to the `error` callback url if the consent was rejected or if an error happens in the process.

Note: if you don't define a set of `callbackUrls`, the user will be redirected to a Pluggy's default page.

Now, if you check the preauthorization status using [this endpoint](/reference/smart-transfer/smart-transfer-preauthorization-retrieve), you will see it with one of the following statuses:

- **COMPLETED**: The preauthorization was completed and you are ready to create payments.
- **REJECTED**: The user rejected the preauthorization in the institution consent flow.
- **ERROR**: There was an error in the institution consent flow.

In the [next section](/docs/smart-transfers/creating-payment), you will see how to create a payment without user interaction.

## Configuring transaction limits

You can configure the transaction limits sending the `configuration` object.

| Field | Type | Optional | Description |
|-------|------|----------|-------------|
| totalAllowedAmount | number | true | Maximum amount to be reached by the sum of all transactions that use the consent authorized by the customer. |
| transactionLimit | number | true | Maximum amount for each payment transaction associated with this consent. |
| periodicLimits | object | true | Transactional limits per period as determined by the paying user. |

In the `periodicLimits` object, you can configure the limits per period. The available periods are `day`, `week`, `month` and `year`, and for each one you can configure:

| Field | Type | Optional | Description |
|-------|------|----------|-------------|
| quantityLimit | number | true | Maximum number of transactions allowed to occur in the period. |
| transactionLimit | number | true | Maximum amount to be transacted in the period. |

Example:

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

In the case that some limit is reached, you will receive an appropriate error from the API.