Connect an account

In this section, we will learn how to connect the Pluggy API with a financial institution.

Each financial entity will have a connector and specific payloads necessary for the connection that must be completed in the body of the request in Postman.

These required payloads are found in the List Connectors (GET /connectors) response, in the "credentials" field inside each Connector object. Each of these credential represents the structure definition for each parameter that needs to be sent, to solve the login step.

There are connectors that also require an additional Multi-factor Authentication (MFA) parameter. We have two possible scenarios here:

1- the MFA parameter can be solved by the user alone without a prompt from the financial institution, for example with Google Authenticator. In this scenario, the parameter will be found inside the "credentials" payload, it will have the field "mfa: true" set. It has to be sent in the initial login step.

2- the MFA parameter can only be solved by the user by completing a challenge generated by the financial insitution, such as a token sent by email or SMS, scanning a QR code, or answering some other prompt. The details to solve this parameter will be found after succesfully logging in, in the Retrieve Item (GET /items/:id) response, in the "parameter" payload. Then, the parameter value has to be sent with the Send Item MFA (POST /items/:id/mfa) endpoint.
Connectors with this scenario can be distinguished with the field "mfa: true" at the base of the connector payload definition.

Therefore, we will divide the connectors to facilitate understanding:

Connectors without verification code
Connectors with one-step verification code ("MFA 1-step")
Connectors with two-step verification code ("MFA 2-step")

Connectors without verification code

To connect an account that does not need an extra validation code, simply access the Postman Collection, expand the "Items" folder and select the "Create Item" request.
On the "Body" tab, enter your credentials in the elements presented in the "Create Item" request.

We list each of the institutions and their specificities below:

{
    "connectorId": 201,
    "parameters": {
        "agency": "",
        "account": "",
        "password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 211,
    "parameters": {
	"agency": "",
	"account": "",
	"password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 219,
    "parameters": {
	"user": "",
	"password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 216,
    "parameters": {
	"user": "",
	"password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 208,
    "parameters": {
        "user": "<cpf>",
        "password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 220,
    "parameters": {
        "cpf": "",
	"password": "",
	"signature": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 213,
    "parameters": {
	"email": "",
	"password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 210,
    "parameters": {
        "email": "",
	"password": "",
	"birthDate": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 227,
    "parameters": {
        "cnpj": "",
	"user": "",
	"password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 223,
    "parameters": {
        "user": "",
	"password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 228,
    "parameters": {
        "cooperativa": "",
        "chaveAcesso": "",
        "password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 228,
    "parameters": {
        "cooperativa": "",
        "chaveAcesso": "<Account Number>",
        "password": ""
    },
    "clientUserId": ""
}

For Itaú PF to recover Payment Data, it's necessary update the item at least once.
For Itaú PF with joint account (conta conjunta) please see below (Exception Flows)

For Caixa PF please see below (Exception Flows)

Connectors with one-step verification code ("MFA 1-step")

To connect an account that requests an extra validation code in a single login step, simply access the Postman Collection, expand the "Items" folder and select the "Create Item with MFA" request.
In the "Body" tab, your credentials to access the institution must be inserted together with the verification code (token, SMS, etc), as presented in the elements of the "Create Item with MFA" request.

📘
Connector "MFA 1-step"
You can detect which institutions are included in this scenario, by finding the "mfa": true value, in one of the "credentials" objects, inside the connectors in the List Connectors response.

We list each of the institutions and their specificities below:

{
    "connectorId": 215,
    "parameters": {
    },
    "clientUserId": ""
}

{
    "connectorId": 204,
    "parameters": {
      "user": "<cpf>",
      "password": "",
      "token": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 202,
    "parameters": {
        "account": "<account number or CPF>",
        "password": "",
        "token": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 207,
    "parameters": {
        "user": "",
	"password": "",
	"token": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 205,
    "parameters": {
        "user": "",
        "password": "",
        "token": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 283,
    "parameters": {
        "email": "<email>",
        "password": "",
        "token": ""
    },
    "clientUserId": ""
}

Connectors with two-step verification code ("MFA 2-step")

In this flow, the parameter for inserting verifier code will be requested after the user's credentials are validated. Thus, it is necessary to send the credentials and wait for validation so that the verification code can be sent.

📘
Connector "MFA 2-step"
You can detect which institutions are included in this scenario, by finding the "mfa": true value, at the base definitions of a Connector, found in the List Connectors response.

Note: To check if the credentials have been validated and the verification code must already be sent, just access the Postman Collection, expand the "Items" folder, select the "Specific Item" request and insert the item_id as a parameter of the URL. In the service response, the token must be sent when the "status" and ”executionStatus” elements have the value "WAITING_USER_INPUT".

At this point, the verification code must be sent in order for the connection to be established. To send the code, simply access the Postman Collection, expand the "Items" folder and select the “Send MFA Parameter user-triggered” request.

In the "Body" tab, the verification code must be inserted as shown in the elements of the "Send MFA Parameter user-triggered" request (token, sms etc).

{
    "connectorId": 212,
  	"parameters": {
      "cpf": "",
      "password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "code": ""
}

{
    "connectorId": 209,
    "parameters": {
        "user": "",
        "password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "token": ""
}

{
    "connectorId": 222,
    "parameters": {
		"user": "",
		"password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "code": ""
}

{
    "connectorId": 214,
    "parameters": {
		"cpf": "",
		"password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "token": ""
}

{
    "connectorId": 214,
    "parameters": {
                "agency": "",
		"account": "",
		"password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "value": ""
}

{
    "connectorId": 230,
    "parameters": {
	     "email": "",
	     "password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "token": ""
}

{
    "connectorId": 213,
    "parameters": {
		"email": "",
		"password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "mfa": ""
}

{
    "connectorId": 233,
    "parameters": {
		"cpf": "",
		"password": ""
    },
    "clientUserId": ""
}


Send MFA Parameter user-triggered:
{
    "value": ""
}

Safra: the MFA will be asked twice in the item's first execution. Then, for item updates, it will be requested only once. Please see below "Safra" in Exception Flows

Connectors with Company Selection

The business connectors may require you to select which company you want to connect with, depending on if the user that its accessing has access to more than one single company.

In those cases, after initializing the item with the initial parameters you will be prompted with an additional parameter.
This parameter can be recovered from “Specific Item” endpoint, sending the id created, and will be of type select this means that one of the list values must be sent back to us for selection.

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "paramater": {
        "type": "select",
        "name": "selectedCompany",
        "label": "Qual é a sua empresa?",
        "instructions": "Selecione a conta que deseja conectar",
        "options": [
          { 
            "value": "9025000",
            "label": "902.500-0 One Company ltda",
          },
          { 
            "value": "9025001",
            "label": "902.500-1 Second Company ltda",
          },
        ],
        "expiresAt": "2023-03-28T18:17:59.532Z"
    },
    ...
}

Once the user has selected the company, send it back using the Send MFA Endpoint

{
    "selectedCompany": "9025000"
}

Exception flows

Bradesco PF Conta Conjunta

The connector "Bradesco PF" is mapped to both simple (individual) and joint accounts (Conta Conjunta).

To connect to the joint account, you can just send any random “token” value in the endpoint “Create Item with MFA”, for example “000000”, it won't matter because the Account selection step, if applies, will take precedence and is going to be resolved first.

{
    "connectorId": 203,
    "parameters": {
        "agency": "",
        "account": "",
        "password": "",
        "token": "000000"
    },
    "clientUserId": ""
}

Make calls on the “Specific Item” endpoint passing in the URL the ItemId of the connection to check the status of the connection until you get the “parameter” element in the response with the "options" element which contains list of accounts registered at the institution, and the value for each one, like so:

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "selectedOwner",
        "label": "Qual é o seu nome?",
        "type": "select",
        "options": [
            {
                "value": "GABRIEL",
                "label": "GABRIEL"
            },
            {
                "value": "MARCOS",
                "label": "MARCOS"
            }
        ],
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

Call the “Send MFA Parameter user-triggered” endpoint, passing the connection's ItemId in the URL and the “selectedOwner” element in the payload with the user-selected value for the account you want to access.
Note: Send it before the parameter expires (60 seconds).

For example, if the user selects the account "1" (in our case, the one with "label": "MARCOS"):

{
    "selectedOwner": "1"
}

After making this call, continue calling the “Specific Item” endpoint. Eventually, the Item “executionStatus” attribute returned in the Body Response will have the value “WAITING_USER_INPUT”, with the "parameter" element, like so:

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "token",
        "label": "Chave de segurança",
        "type": "number",
        "placeholder": "Exemplo: 123456",
        "validationMessage": "O token deve ter 6 números.",
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

This time, the "token" MFA parameter has to be provided (which we had sent before as "000000", or some other random value), but now send it with the correct user-provided value.

Call the “Send MFA Parameter user-triggered” endpoint, passing the connection's ItemId in the URL and the “token” element in the payload with the user provided MFA token.

{
    "token": "123456"
}

Resume making calls on the “Specific Item” endpoint passing the connection ItemId in the URL until the “executionStatus” attribute is set to “SUCCESS” (or “PARTIAL_SUCCESS”), meaning your connection has been created/updated successfully.

At this point, you'll be able to retrieve the products data for this Item.

📘
Data recovered
As this is a joint account, keep in mind that Pluggy will only collect the data from the account selected by the user on the first step.

Banco do Brasil PJ

In the case of Banco do Brasil Empresas, in order for the connection to be established, it will be necessary to use a computer that is the same as the one already authorized in internet banking or, in case of use by cell phone, that this device is also the same already authorized in internet banking, and that the account used for the connection has a cell phone registered with Banco do Brasil, as this will receive a confirmation link to be inserted at the time of connection.

First, make a call on the “Create Item” endpoint passing the credentials payload like so:

{
    "connectorId": 217,
    "parameters": {
        "userJ": "",
        "passwordJ": "",
        "password": ""
    },
    "clientUserId": ""
}

Call the “Specific Item” endpoint until you get "executionStatus" as "WAITING_USER_INPUT" and the “parameter” attribute present in the response, with a list of cell phones registered at the institution and the value for each option.

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "phone",
        "label": "Selecione um numero abaixo para receber o SMS",
        "type": "select",
        "options": [
            {
                "value": "phone_1",
                "label": "123123123"
            },
            {
                "value": "phone_2",
                "label": "123456456"
            }
        ],
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

Then call the “Send MFA Parameter user-triggered” endpoint, passing the connection ItemId in the URL and the “phone” element in the payload with the value referring to the primary cell phone listed.

Note: Send the element before it expires (60 seconds).

{
    "phone": "phone_1"
}

Call the "Specific Item" endpoint until obtaining the "executionStatus" as "WAITING_USER_INPUT" and the "parameter" element in the response (again), this time with the indication of sending an MFA token, which the user will receive via SMS on the cell phone previously specified (in our example, the one corresponding to "phone_1").

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "sms",
        "label": "SMS token URL",
        "type": "text",
        "placeholder": "Ex: https://www49.bb.com.br/sms/ato?c=ABC123...",
        "assistiveText": "Cole aqui a URL recebida por sms",
        "validation": "^.{10,120}$",
        "validationMessage": "O URL não pode estar vazio",
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

Return to the “Send MFA Parameter user-triggered” endpoint, passing the connection ItemId in the URL and the “sms” element in the payload, copying the URL received via sms on the cell phone selected in the step above.

Note: Send the element before it expires (4 minutes).

{
    "sms": ""
}

At this point you'll be able to retrieve the products data for this Item.

Itaú PF (Conta Conjunta)

First, make a call on the “Create Item” endpoint passing the credentials payload like so:

{
    "connectorId": 201,
    "parameters": {
        "agency": "",
        "account": "",
        "password": ""
    },
    "clientUserId": ""
}

Then, make a call on the “Specific Item” endpoint passing in the URL the ItemId to check the status of the connection. Call the endpoint until you get the "executionStatus" as "WAITING_USER_INPUT". The “parameter” element will be present in the response, with a list of accounts registered at the institution and the value for each account like so:

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "operatorNumber",
        "label": "Escolha uma opçāo",
        "type": "select",
        "instructions": "Selecione o código do operador",
        "validationMessage": "Account must be provided",
        "options": [
            {
                "value": "operador_1",
                "label": "operador_1"
            },
            {
                "value": "operador_2",
                "label": "operador_2"
            }
        ],
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

To connect to the joint account, call the “Send MFA Parameter user-triggered” endpoint, passing the connection's ItemId in the URL and the "operatorNumber" element in the payload with the user-selected value for the account you want to access. Send it before it expires (at the "expiresAt" date). For example:

{
    "operatorNumber": "operador_1"
}

Note: this parameter "operatorNumber" is asked only for the first time the Item is created, then it is stored and reutilized for any subsequent updates of the same Item instance.

At this point you'll be able to retrieve the products data for this Item.

📘
Data recovered
As it is a joint account, take in mind that Pluggy will only collect the data from the account selected by the user on the first step.

Itaú PF (with mfa)

Some accounts from Itau PF require MFA. In order to connect to this type of account, it will be necessary to send the MFA (token) in the endpoint: “Send MFA Parameter user-triggered”.

First, make a call on the “Create Item” endpoint passing the credentials payload like so:

{
    "connectorId": 201,
    "parameters": {
        "agency": "",
        "account": "",
        "password": ""
    },
    "clientUserId": ""
}

Calling the “Specific Item” endpoint you'll get the "executionStatus" as "WAITING_USER_INPUT", and the “parameter” attribute in the response with the "name": "token" value, like so:

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "mfa",
        "label": "Seu token de segurança",
        "type": "text",
        "instructions": "Insira o token de segurança do seu aplicativo para continuar.",
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

Then, make a call to the "Send MFA Parameter user-triggered" endpoint in order to send the MFA (token):

{
    "mfa": ""
}

At this point you'll be able to retrieve the products data for this Item.

Itaú PJ

The "Itaú" connector is mapped to both simple (individual) and joint accounts. To connect to the joint account, it will be necessary to send the name of the account holder in the endpoint: “Send MFA Parameter user-triggered”.

First, make a call on the “Create Item” endpoint passing the credentials payload like so:

{
    "connectorId": 218,
    "parameters": {
        "agency": "",
        "account": "",
        "password": "",
        "cpfOrOperator": ""
    },
    "clientUserId": ""
}

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "operatorNumber",
        "label": "Escolha uma opçāo",
        "type": "select",
        "instructions": "Selecione o código do operador",
        "validationMessage": "Account must be provided",
        "options": [
            {
                "value": "operador_1",
                "label": "operador_1"
            },
            {
                "value": "operador_2",
                "label": "operador_2"
            }
        ],
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

{
    "operatorNumber": "operador_1"
}

Note: this parameter "operatorNumber" is asked only for the first time the Item is created, then it is stored and reutilized for any subsequent updates of the same Item instance.

At this point, you'll be able to retrieve the products data for this Item.

📘
Data recovered
As it is a joint account, take in mind that Pluggy will only collect the data from the account selected by the user on the first step.

XP (CPF access - joint account)

The "XP" allows connecting both simple accounts (account number access) and joint accounts (with CPF access).

First, make a call on the “Create Item” endpoint passing the credentials payload like so:

{
    "connectorId": 202,
    "parameters": {
        "account": "", // some CPF
        "password": "",
        "token": ""
    },
    "clientUserId": ""
}

Then, make a call on the “Specific Item” endpoint passing in the URL the ItemId to check the status of the connection. Call the endpoint until you get the "executionStatus" as "WAITING_USER_INPUT". The "parameter" field in the response will include the list of accounts to choose from:

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "selectedAccount",
        "label": "Conta",
        "type": "select",
        "instructions": "Selecione a conta que deseja conectar",
        "options": [
            {
                "value": "account_1",
                "label": "account_1"
            },
            {
                "value": "account_2",
                "label": "account_2"
            }
        ],
        "expiresAt": "2024-12-14T19:09:08.780Z"
    }
}

To connect to the account, call the “Send MFA Parameter user-triggered” endpoint, passing the connection's ItemId in the URL and the "selectedAccount" element in the payload with the user-selected value for the account you want to access. Send it before it expires (at the "expiresAt" date).
For example:

{
    "selectedAccount": "account_1"
}

Note: this parameter "selectedAccount" is asked only for the first time the Item is created, then it is stored and reutilized for any subsequent updates of the same Item instance.

At this point, you'll be able to retrieve the products data for this Item.

📘
Data recovered
As it is a joint account, take in mind that Pluggy will only collect the data from the account selected by the user on the first step.

Santander PJ

In the case of Santander PF, for the connection to be established, it will be necessary to scan the QR code and send the extra validation code (endpoint: “Send MFA Parameter user-triggered”).

First, make a call on the “Create Item” endpoint, sending the credentials payload like so:

{
    "connectorId": 221,
    "parameters": {
        "agency": "",
        "account": "",
        "user": "",
        "password": ""
    },
    "clientUserId": ""
}

Then, make a call on the “Specific Item” endpoint passing the newly created item id as a parameter until the “executionStatus” attribute is set to “WAITING_USER_INPUT”.

During the token validation period, copy the value returned in the “data” attribute, located inside “parameter”, like the below example. This value is a base 64 image encoded.

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "token",
        "label": "Token",
        "type": "image",
        "placeholder": "Exemplo: 12345678",
        "assistiveText": "Digite o código gerado em seu celular",
        "validationMessage": "O token deve ter 8 dígitos",
        "instructions": "No aplicativo, clique em \"ID Santander\" > \"Internet Banking\". Aponte a câmera para o código e insira o token gerado.",
        "data": "...............",
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

1- Paste the parameter copied from postman from the “data” attribute inside an <img src="__data_here__"> tag. Click 'Ctrl + S' to save the change.
2- The QR Code will be available on the right screen, and the account holder will simply point to the cell phone to obtain the necessary token to validate the connection with the Santander PF account.
3- Copy the token obtained by reading the QR Code.

In Postman, now activate the "Collection" menu, expand the "Items" folder, and select the request "Send MFA Parameter user-triggered".

Call the “Send MFA Parameter user-triggered” endpoint, passing the connection's ItemId in the URL and the "token" element in the payload with the token just copied from the QR code. Send it before it expires. For example:

{
    "token": ""
}

Inter PJ

This connector has the peculiarity of using bank Oauth 2 API, so in order to connect an account is necessary first generate and get "clientId", "clientSecret", the files "API_Chave.key" and "API_Certificado.crt" in client home banking account. Follow this link to do it.

Then, you can use these four parameters to invoke the create item endpoint in your client.

The private key (API_Chave.key) and certificate (API_Certificado.crt) is a base64 without line breaks between each file's header and footer.

Here is an example of how to get privateKey from API_Chave.key

MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCx5hjjydzLHl4/KePMBQBGO/L6jnKDQk1KFfcy+zWumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRkuqeplC4utkJxQgWUa2m7rhfr6Z+RqXeY8JaekMFk+GPGIIGhuYjJ5PxWwLXB2WEeRWumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRku235235tsdgd265t2r4wdf52325LWs/GulyKInRduRkZC39OadjesyNTjLhvF6EEHxkAm3C0RGvJmBSJmM9CN03/8wWc5C20WvwcwojLQ/1m5GYNnhqyx19DjTbnV4M6cySE4b3zIzgwE9pUWdYYH9Scu1pxPMOo+0jAgMBAAECggEAPfPawSEgYiAeRDLrYLZxJQRllroayPlC/0TtBHUVecvefe3EOmV2tjRz0NYgKzlh/+BE9y1lOalg7q4/sZa2uuf8d9DIC/T74cuT3rZlhmFS96lJW1V3DrgTDQv0MlTCLRU6EVORsbUGn5fEjSnpr1/IQxwweagJY0p7CZw32HseWumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRku235235tsdgd265t2r4wdf52325xt1pnd9zENVPx+yHI1DEZrR9qIfBKPUhZdwNf0i8GOyjK3gnz1MDsNqzeBqnPHFhgpTBzZK747wyaL0UzWpNYCu9wCW4DQ3DvI6l3tQC2QKBgQD1E0qxBweyx0MHsk9vg1e7LkXsxt7xxz/vzKBHlgPy460zrLbOa0vNLJxcUdggcgjQgfjgt34HfW+Mr7PTZuBC7cLXQNj2jItOEAabiuZoeNQ8O9hpcH3b4Ycp9e+RbF4Xm1LRz3ne5/Kz0uf0P4kjw/w1stXF1FHifkJiPMoQrQKBgQC51DZAsjVAo4qTpQf5LmrL2zA5hnoTaxP7125124WumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRkuvbsdgd265t2r4wdf5325PKdQgXzwco2nIEkjkfjw7adZpEq5SkGychRSW5qxUwpVZM/ONOTl30+WGRxkGImr9ago0ugfDwKBgBH6wFgMc/whskE2S62arS0GUAr27BRA0ef90yRtVQzUtzg7S44JQR5kT3RWbMy0kQD7CA80ZwKVqUFhAohX28wNNWYlU8WCuhWYB2QR5KV1d9yTZ2UU46bl/MyPRmwczypcMs9BsWcxDRU0O+AnaSA+mJo37Ib+9KLxMF2UqB5hAoGAc0eCoH/tKTxLK2yllZ+GARDoycby1DkJHEh3BnUne15lkOCe2l8EsikkrnwdLZyMN0pjHGlkjjbhk1DXh9u5Ilkhno98kpJ4ohX28wNNWYlU8WCuhWYB24124124DFSQACQQvCa3wGmTb4Yqo/GMTk5KQQMy6aWPQm4S88Bi32ECgYEAgRhstNkXeC6g9ovAbXVCb+X+RbPUxFoCQd9wdWcjIwxgSWHM33KX60KGoRC5/ONEm0ZkHG1vckph5Z9gsPqUvg9sISDe28CiQexk9ASDASDASD21C4M595/WcLLjRhH9NiQSjKevRvjqBotAkIhsO1yGOetxR/35qCWcxQkl5O8=

Then, make a call on the “Create Item” endpoint, sending the credentials payload like so:

{
    "connectorId": 225,
    "parameters": {
        "clientId": "",
        "clientSecret": "",
        "privateKey": "",
        "certificate": ""
    },
    "clientUserId": ""
}

Make calls on the “Specific Item” endpoint passing the connection ItemId in the URL until the “executionStatus” attribute is set to “SUCCESS” (or “PARTIAL_SUCCESS”), meaning your connection has been created/updated successfully.

At this point you'll be able to retrieve the products data for this Item.

Ailos

This connector groups all the cooperatives behind the Ailos system. So, it is necessary to specify the cooperative name in the item creation (always without spaces and in lower-case).

To be sure that the cooperative name is right, it's suggested to first invoke the "Specific Connector" endpoint for Ailos (connector id 224). The following is an example response

{
    "id": 224,
    "name": "Ailos",
    "primaryColor": "00A9CE",
    "institutionUrl": "https://www.viacredi.coop.br/",
    "country": "BR",
    "type": "PERSONAL_BANK",
    "credentials": [
        {
            "validation": "^\\d{2,7}\\d$",
            "validationMessage": "A conta deve ter de 3 a 8 números.",
            "label": "Conta",
            "name": "account",
            "type": "text",
            "placeholder": "Exemplo: 12345678",
            "optional": false
        },
        {
            "validation": "^\\d{8}$",
            "validationMessage": "A senha deve ter 8 números.",
            "label": "Senha",
            "name": "password",
            "type": "password",
            "placeholder": "",
            "optional": false
        },
        {
            "validation": "^.{10,40}$",
            "validationMessage": "A Frase deve ter de 10 e 40 caracteres.",
            "label": "Frase Secreta",
            "name": "phrase",
            "type": "password",
            "placeholder": "Exemplo: 12345678901",
            "optional": false
        },
        {
            "name": "cooperative",
            "label": "Cooperativa",
            "type": "select",
            "options": [
                {
                    "value": "viacredi",
                    "label": "Viacredi"
                },
                {
                    "value": "evolua",
                    "label": "Evolua"
                },
                {
                    "value": "acentra",
                    "label": "Acentra"
                },
                {
                    "value": "civia",
                    "label": "Civia"
                },
                {
                    "value": "credifoz",
                    "label": "Credifoz"
                },
                {
                    "value": "unilos",
                    "label": "Unilos"
                },
                {
                    "value": "viacredialtovale",
                    "label": "Viacredi Alto Vale"
                },
                {
                    "value": "acredi",
                    "label": "Acredicoop"
                },
                {
                    "value": "credcrea",
                    "label": "CredCrea"
                },
                {
                    "value": "credicomin",
                    "label": "Credicomin"
                },
                {
                    "value": "crevisc",
                    "label": "Crevisc"
                },
                {
                    "value": "transpocred",
                    "label": "Transpocred"
                }
            ],
            "optional": false
        }
    ],
    "imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/224.svg",
    "hasMFA": false,
    "health": {
        "status": "ONLINE",
        "stage": null
    },
    "products": [
        "ACCOUNTS",
        "TRANSACTIONS"
    ],
    "createdAt": "2022-03-15T19:51:37.386Z"
}

Then, pick the "value" field of the desired cooperative, and make a call on the “Create Item” endpoint, sending the credentials payload like so:

{
    "connectorId": 224,
    "parameters": {
        "account": "",
        "password": "",
        "phrase": "",
        "cooperative": "",
    },
    "clientUserId": ""
}

At this point, you'll be able to retrieve the products data for this Item.

BTG Pactual, Empiricus and EQI

The "BTG" (Empiricus and Eqi) connector is mapped to both simple and joint accounts. To connect to the joint account, it will be necessary to send the name of the account holder in the endpoint: “Send MFA Parameter user-triggered”.

First, make a call on the “Create Item” endpoint passing the credentials payload like so:

{
    "connectorId": 214,
    "parameters": {
        "cpf": "",
        "password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 233,
    "parameters": {
        "cpf": "",
        "password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 271,
    "parameters": {
        "cpf": "",
        "password": ""
    },
    "clientUserId": ""
}

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "selectedOwner",
        "label": "Selecione sua conta",
        "type": "select",
        "options": [
            {
                "value": "0",
                "label": "ACC123 - OWNER1"
            },
            {
                "value": "ACC123 - OWNER2",
                "label": "1"
            }
        ],
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

To connect to the joint account, call the “Send MFA Parameter user-triggered” endpoint, passing the connection's ItemId in the URL and the "operatorNumber" element in the payload with the user-selected value for the account you want to access to. Send it before it expires (at the "expiresAt" date). For example:

{
    "selectedOwner": "1"
}

Note: this parameter "selectedOwner" is asked only for the first time the Item is created, then it is stored and reutilized for any subsequent updates of the same Item instance.

After making this call, continue calling the “Specific Item” endpoint. Eventually the Item “executionStatus” attribute returned in the Body Response will have the value “WAITING_USER_INPUT”, with the "parameter" element, like so:

{
    "id": "a9481a68-38cc-4433-bfcc-dafc05022c60",
    "status": "WAITING_USER_INPUT",
    "executionStatus": "WAITING_USER_INPUT",
    "lastUpdatedAt": null,
    "error": null,
    "parameter": {
        "name": "token",
        "label": "Token",
        "type": "number",
        "placeholder": "Exemplo: 123456",
        "validationMessage": "O token deve ter 6 números.",
        "expiresAt": "2022-12-14T19:09:08.780Z"
    }
}

Call the “Send MFA Parameter user-triggered” endpoint, passing the connection's ItemId in the URL and the “token” element in the payload with the user provided MFA token.

{
    "token": ""
}

At this point, you'll be able to retrieve the products data for this Item.

📘
Data recovered
As this is a joint account, keep in mind that Pluggy will only collect the data from the account selected by the user on the first step.

Caixa PF and PJ

Using this connector requires the user to authorize a new device (Pluggy) within his mobile Caixa app.

Keep in mind that from the moment the user enters his credentials, it can take up to 30 minutes to complete the login process.

First, use the “Create Item” endpoint and send the necessary parameters for connection:

{
    "connectorId": 219,
    "parameters": {
        "user": "",
        "password": ""
    },
    "clientUserId": ""
}

{
    "connectorId": 216,
    "parameters": {
        "user": "",
        "password": ""
    },
    "clientUserId": ""
}

If everything is ok, the connector will return the status USER_AUTHORIZATION_PENDING and a device name.

For this, use the “Specific Item” endpoint to check the connection status using > GET /items.
Call the endpoint until the response attribute “executionStatus” has the value “USER_AUTHORIZATION_PENDING” just like in the example below.

{
    "createdAt": "2022-12-29T17:42:43.926Z",
    "updatedAt": "2022-12-29T17:42:46.836Z",
    "status": "OUTDATED",
    "executionStatus": "USER_AUTHORIZATION_PENDING",
    "lastUpdatedAt": null,
    "webhookUrl": null,
    "error": {
        "code": "USER_AUTHORIZATION_PENDING",
        "message": "The user needs to grant necessary permissions for their account.",
        "providerMessage": "No Internet Banking, clique em > Senhas e Configurações > Computadores e Dispositivos > Gerenciar \n Você precisa ativar o seguinte dispositivo:",
        "attributes": {
            "deviceNickname": "nick-name",
            "qrCodes": "cHJ1ZWJh,cHJ1ZWJhMg=="
        }
    }
}

Now the user should authorize the new device from their Caixa app mobile.

How? By following the steps below:

1- Access the “Passwords and Settings” menu
2- Select “Manage Devices” then “Registered Devices”. A list will be returned with the devices registered in that account, search in the list for the device with the same name that was returned in the "deviceNickname" field of the previous call and select.
3- Click on the “Activate device” button.
4- The 'Activate Device' screen will be displayed, click on the 'Continue' button.
5- Scan the QRs received in the qrcodes attribute in the previous payload. It contains two comma separated QRs that will rotate every 5 seconds.

As soon as the step above is finished, wait 30 minutes for Caixa to authorize the device, then make a call to the “Update Item” endpoint.

Use: PATCH /items/itemId
Inform the ItemID that you want to update in the endpoint parameter and make the call with an empty body (no need to re-enter the credentials). The expected outcome is executionStatus: UPDATING.

Note: Keep in mind that execution status can quickly change and you can also find a CREATED or even LOGIN_IN_PROGRESS.

Return to the endpoint “Specific Item” so you can check the connection status. The expected result is executionStatus: SUCCESS.

{
    "createdAt": "2022-12-29T17:42:43.926Z",
    "updatedAt": "2022-12-29T17:42:44.011Z",
    "status": "UPDATED",
    "executionStatus": "SUCCESS",
    "lastUpdatedAt": null,
    "webhookUrl": null,
    "error": null,
    "clientUserId": "client-usr-id",
    "statusDetail": null,
    "parameter": null
}

At this point, you'll be able to retrieve the products data for this Item.

Maybe you are wondering if Pluggy can automatically update the items that have the device authorized, here is a little explanation of how we do it. Feel free to reach out to us if it is not clear enough.

Once the user authorized the new device, it's necessary to wait 30 minutes until Caixa approves it. Then we can have two different situations:
1- The user makes an update and if everything is ok we will return SUCCESS
2- Our automatic update system will run every 6 hours (after 30 min necessary to authorize the device) in order to get status = SUCCESS in the items that did get the device authorized, but didn't have the data colleted (did not updated it after 30 min). This flow is done for 48 hours until receiving the SUCCESS status, then it does not continue updating automatically.
If the user did not update at any time, they will receive USER_AUTHORIZATION_NOT_GRANTED.

Safra

To connect an account, this connector requires the user to authorize a new device (Pluggy - yyy-mm-dd hh-mm) through the Safra mobile app.

First, use the “Create Item” endpoint and send the necessary parameters for connection:

{
    "connectorId": 229,
    "parameters": {
      "agency": "",
      "account": "",
      "password": ""
    }
}

If everything is ok, after entering the token provided by Safra app, the connector will return the executionStatus WAITING_USER_ACTION. Use the “Specific Item” endpoint to check the connection status using > GET /items. Call the endpoint until the response attribute “executionStatus” has the value “WAITING_USER_ACTION” just like in the example below:

{
    "id": "c33872c7-85dc-4d67-b262-6490d85ea2d3",
    "connector": {
        "id": 229,
        "name": "Safra",
        "primaryColor": "#00003C",
        "institutionUrl": "https://www.safra.com.br/",
        "country": "BR",
        "type": "PERSONAL_BANK",
        "credentials": [
            {
                "validation": "^\\d{3,3}\\d$",
                "validationMessage": "O agência deve ter 4 números.",
                "label": "Agência",
                "name": "agency",
                "type": "number",
                "placeholder": "Exemplo: 1234",
                "optional": false
            },
            {
                "validation": "^\\d{6,6}-?\\d$",
                "validationMessage": "A conta deve ter 7 números.",
                "label": "Conta",
                "name": "account",
                "type": "number",
                "placeholder": "Exemplo: 12345-6",
                "optional": false
            },
            {
                "validation": "^\\d{1,6}$",
                "validationMessage": "A senha deve ter menos de 6 números.",
                "label": "Senha",
                "name": "password",
                "type": "password",
                "placeholder": "",
                "optional": false
            }
        ],
        "imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/229.svg",
        "hasMFA": true,
        "health": {
            "status": "ONLINE",
            "stage": null
        },
        "products": [
            "ACCOUNTS",
            "TRANSACTIONS",
            "INVESTMENTS"
        ],
        "createdAt": "2022-11-04T21:12:51.716Z"
    },
    "createdAt": "2023-02-27T17:42:40.521Z",
    "updatedAt": "2023-02-27T17:43:47.114Z",
    "status": "WAITING_USER_ACTION",
    "executionStatus": "WAITING_USER_ACTION",
    "lastUpdatedAt": null,
    "webhookUrl": null,
    "error": null,
    "clientUserId": null,
    "statusDetail": null,
    "parameter": null,
    "userAction": {
        "instructions": "User needs to authorize the device in their Safra App",
        "attributes": {
            "deviceNickname": "Pluggy - 2023-02-27 17:42"
        },
        "expiresAt": "2023-02-27T17:45:46.237Z"
    },
    "nextAutoSyncAt": null
}

The item will remain in that state until:

The user authorizes the device in the Safra app: In this case, the item status will change automatically and a new token will be requested to the user.

The user doesn't authorize the device in the Safra app: the item will return the execution status USER_AUTHORIZATION_NOT_GRANTED.

The current date is after the expiresAt date returned in the userAction property: the item will return the status USER_AUTHORIZATION_PENDING. In this scenario, the user can authorize the device later, and after that the item can be updated.

This flow will happen only on item creation. If the device was authorized and the item is updated, it will only request a token to the user.

Banco Inter / Inter Investimentos

Using this connector for an item in the first execution requires the user to authorize the login with Inter by scanning a QR code with their Inter mobile app.

To do so, the user must be prepared to scan the QR code by logging in to the mobile app and going to Options > iSafe e Internet Banking > QR Code.

First, use the “Create Item” endpoint, no parameters necessary, since the entire flow of login will be by QR:

{
    "connectorId": 215,
    "parameters": {
    }
}

Then, return to the endpoint “Specific Item” so you can check the connection status. Soon after creation, the item will reach a WAITING_USER_ACTION status. At which point, the userAction.attributes.data field of the item will be a field with a QR code in base64 to be scanned:

{  
    "createdAt": "2023-02-27T12:46:25.707Z",
    "updatedAt": "2023-02-27T12:46:33.365Z",
    "status": "WAITING_USER_ACTION",
    "executionStatus": "WAITING_USER_ACTION",
    "lastUpdatedAt": null,
    "webhookUrl": null,
    "error": null,
    "clientUserId": null,
    "statusDetail": null,
    "parameter": null,
    "userAction": {
        "instructions": "SCAN QR",
        "expiresAt": 123456789,
        "attributes": {
            "name": "qr",
            "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALkAAAC5CAAAAABRxsGAAAAByElEQVR42u3cUW6DMBAFQO5/6fYCwXnPtiKBx1+JEmCKxHq96/T6e+q4yMnJycnJycnJycnJyd8iv76P28NuX30689LVyMmPlt8/1B8+DYDpsemn5OTk97Fgoze9Gjk5+YT8Vjmey8nJyX8XW8YzeBp5yMnJd+bnqXflK+Tk5LM1ro2vflydIyd/sjxu1QyjzO2Fx6KfdLjIyZ8sT1fBafKdrsODiEJOTv7lb6hasv2NSWMQOfmx8mBN29ee0yZumhaQkx8rr2b15SLZuDNMTk4+MecnZeLm2Ikcgpz8aPk4mKw0i8ar6vjGkJOfKq9y8bTi3O+G2pS3kJO/TR7k4tXepjSFrxpI5OTHytOqcYXpfz5ATk4ex5Zqyq7CSrBjg5ycPD512kWaLDFvz8/Jyd8rD7YwVUvr4ARxgk9OTh489+mGqaAU3ZW2yclPlaejbxul+5LX+0Tk5O+VV79kC95WTeH4JpCTHy2vitKTqUK6cicnJ48bQ1UsCHY+VRVscnLyTfJ008RkKZqcnHz2vxRObmTcmZ+Tk58gX87ex4FjsrxFTk5+VQ9/uqE/neSX8nNy8pfLHzHIycnJycnJycnJycnJnzj+ATnf0jtEQEXdAAAAAElFTkSuQmCC"
        }
    },
    "nextAutoSyncAt": null
}

Since we return the image in base64, you'll need to render it so the client can scan it. Once the user successfully scans the login QR with their mobile app, the login flow will continue normally.

🚧
Important info and recommendation
Take in mind that the QR code expires in 5 seconds, and the item info will be updated with a new QR code, as such, you'll need to poll the "Specific Item" endpoint to check for updates to the code. Given the very short expiration time, it's easy to render an expired QR code. So, we recommend polling every 1 second until the status of the item changes.

XP Wealth

This connector also allows you to specify which customers you want to collect financial data from. To do that, you need to send a credential selectedCustomers with all customer codes you want to connect separated by comma.

{
    "connectorId": 248,
    "parameters": {
        "clientId": "clientId",
        "clientSecret": "clientSecret",
        "selectedCustomers": "409185,551175,176189"
    },
    "webhookUrl": "https://www.myapi.com/notifications"
}

🚧
Important
This customization is not available in our widget, you need to create the item using Pluggy API.

Mercado Bitcoin

This connector requires to create an API Key (chave de API) in the institution account. To do that, follow this tutorial. After that, use the client id and client secret to create an item.

Connectors with OAuth

OAuth connections require the user to provide authorization directly inside the Financial Institution's application, so there is a redirect flow that needs to happen between Pluggy & FI, back and forth.

OAuth v1

The first implementation Pluggy provided returns an oauthUrl on the connector's list endpoint that is necessary to redirect the user to provide consent.

{
  "id": 206,
  "name": "Mercado Pago",
  "oauthUrl": "https://auth.mercadopago.com.br/authorization?client_id=3960514748228649&redirect_uri=https://api.pluggy.ai/connectors/206/oauth/callback&response_type=code&platform_id=mp&scopes=read,offline_access&state=27364b4a-354e-479d-89bd-05cef476e1f4"
  
}

If the connector provides the oauthUrl you will be required to redirect the user to that page, and after he authorized Pluggy, we will redirect him back to your application.

This affects the connectors: "MercadoPago"

OAuth v2

After improving the flow from the previous version we have launched the integration directly through the item, to provide better tracking of the connection attempts for our customers. Now connectors don't return the URL but instead don't require any credential to start the execution, and have a oauth flag to understand that this connectors will access through oauth authentication.

{
  "id": 240,
  "name": "Splitwise",
  "credentials": [],
  "oauth": true
   
}

Once the execution has started we will provide the oauthUrl as a parameter for the user to be redirected.

{
  "id": "54a8d5e2-583a-40fd-a716-c9cee38a73dc",
  "parameter": {
    "label": "Oauth Code",
    "name": "oauthCode",
    "type": "oauth",
    "instructions": "Log into Splitwise page to continue",
    "data": "https://secure.splitwise.com/oauth/authorize?response_type=code&client_id=I351UBINPK5b5psYXToACr90XVD5g5GuBdvg4SG4&redirect_uri=https://api.pluggy.ai/items/oauth/callback&scope=&state=4eb2909b-c4c5-4f68-ba2b-84f2772fb15a",
    "expiresAt": "2023-03-09T11:02:54.796Z"
  }
}

The parameter's type oauth make it easy to understand that an OAuth flow its required, and the data attribute returns the URL to redirect the user. After callback, the item will be created.

On updates, the flow will be the same.

Connect an account

Connectors without verification code

Connectors with one-step verification code ("MFA 1-step")

📘
Connector "MFA 1-step"

Connectors with two-step verification code ("MFA 2-step")

📘
Connector "MFA 2-step"

Connectors with Company Selection

Exception flows

Bradesco PF Conta Conjunta

📘
Data recovered

Banco do Brasil PJ

Itaú PF (Conta Conjunta)

📘
Data recovered

Itaú PF (with mfa)

Itaú PJ

📘
Data recovered

XP (CPF access - joint account)

📘
Data recovered

Santander PJ

Inter PJ

Ailos

BTG Pactual, Empiricus and EQI

📘
Data recovered

Caixa PF and PJ

Safra

Banco Inter / Inter Investimentos

🚧
Important info and recommendation

XP Wealth

🚧
Important

Mercado Bitcoin

Connectors with OAuth

OAuth v1

OAuth v2

Connectors without verification code

Connectors with one-step verification code ("MFA 1-step")

📘Connector "MFA 1-step"

Connectors with two-step verification code ("MFA 2-step")

📘Connector "MFA 2-step"

Connectors with Company Selection

Exception flows

Bradesco PF Conta Conjunta

📘Data recovered

Banco do Brasil PJ

Itaú PF (Conta Conjunta)

📘Data recovered

Itaú PF (with mfa)

Itaú PJ

📘Data recovered

XP (CPF access - joint account)

📘Data recovered

Santander PJ

Inter PJ

Ailos

BTG Pactual, Empiricus and EQI

📘Data recovered

Caixa PF and PJ

Safra

Banco Inter / Inter Investimentos

🚧Important info and recommendation

XP Wealth

🚧Important

Mercado Bitcoin

Connectors with OAuth

OAuth v1

OAuth v2

📘
Connector "MFA 1-step"

📘
Connector "MFA 2-step"

📘
Data recovered

📘
Data recovered

📘
Data recovered

📘
Data recovered

📘
Data recovered

🚧
Important info and recommendation

🚧
Important