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

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). For more details about this endpoint, check our API docs

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.