Creating a preauthorization

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.

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 to know how to use this endpoint. To know the paymentInstitutionId, you need to use this endpoint

This will return the following response:

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

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

For more details about this endpoint, check our API docs

🚧
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:

{
    "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 números.",
                "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, 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, 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:

{
  "configuration": {
    "totalAllowedAmount": 100.5, // The sum of all transactions must be <= R$100.50
    "transactionLimit": 10,  // The maximum amount of each transactions is R$10
    "periodicLimits": {
      "day": {
        "quantityLimit": 2, // Only 2 payments can be executed per day
        "transactionLimit": 5 //  The sum of all transactions for the day must be <= R$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.