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

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.
The MFA parameter can only be solved by the user by completing a challenge generated by the financial institution, 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 successfully 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:

Itau PF #

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

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

Caixa PF #

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

For Caixa PF please see below (Exception Flows).

Caixa PJ #

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

Santander PF #

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

Agora #

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

Genial #

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

Sicredi PJ #

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

Clear #

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

Sicoob PJ / Sicoob PF #

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

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.

Inter #

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

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

XP #

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

Rico #

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

Conta Simples #

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

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).