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.

We will divide the connectors to facilitate understanding:

  • Connectors without verification code
  • Connectors with one-step verification code
  • Connectors with two-step verification code

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

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

To connect an account that requests an extra validation code in one 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.

We list each of the institutions and their specificities below:

{
    "connectorId": 215,
    "parameters": {
        "account": "",
        "password": "",
        "token": ""
    },
    "clientUserId": ""
}
{
    "connectorId": 204,
    "parameters": {
        "user": "<cpf>",
    "password": "",
    "token": ""
    },
    "clientUserId": ""
}
{
    "connectorId": 202,
    "parameters": {
        "account": "",
        "password": "",
        "token": ""
    },
    "clientUserId": ""
}
{
    "connectorId": 207,
    "parameters": {
        "user": "",
    "password": "",
    "token": ""
    },
    "clientUserId": ""
}
{
    "connectorId": 205,
    "parameters": {
        "user": "",
    "password": "",
    "token": ""
    },
    "clientUserId": ""
}

Connectors with two-step verification code

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.

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

*Safra: the MFA will be asked only once in the item's first execution. Then, the item will be updatable without MFA expected.

Exception flows

Bradesco PF conta conjunta

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

To connect to the joint account, it will be necessary to send the “token” field filled in with the value “000000” in the endpoint: “Create Item with MFA”.

{
    "connectorId": 203,
    "parameters": {
        "agency": "",
        "account": "",
        "password": "",
        "token": ""
    },
    "clientUserId": ""
}
{
  "options": [
    {
      "value": "1",
      "label": "MARCOS"
    },
    {
      "value": "2",
      "label": "GABRIEL"
    }
  ]
}

Then, make a call on the “Specific Item” endpoint passing in the URL the ItemId of the connection to check the status of the connection.
Call the endpoint until you get the “parameters” element in the response with a list of accounts registered at the institution and the value for each account.

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

After making this call, the “executionStatus” attribute will be returned in the Body Response with the value “WAITING_USER_INPUT”.

Make a call on the “Specific Item” endpoint passing the connection ItemId in the URL until the “executionStatus” attribute is set to “SUCCESS”, so your connection will be updated.

📘

Data recovered

As it is a joint account, take in mind that Pluggy will only recollect 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 payload below:

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

Call the “Specific Item” endpoint until you get the “parameters” attribute in the response with a list of cell phones registered at the institution and the value for each cell.

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 main cell phone listed.
Note: Send element before it expires (60 seconds)

Call the “Specific Item” endpoint until obtaining the “parameters” element in the response with the indication of sending a token received via SMS on the cell phone previously informed.

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 element before it expires (4 minutes)

Make a call on the “Specific Item” endpoint passing the connection ItemId in the URL until the “executionStatus” attribute is set to “SUCCESS” or “PARTIAL_SUCCESS”, so your connection will be ended.

 

Itaú PF (joint account)
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”.

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

- Then, make a call to the following endpoint in order to send the name of the user accessing: 

After the connector sends a list of selectedOwner to select, for example: 

{
    "options": [
        {
            "label": "MARCOS",
            "value": "0"
        },
        {
            "label": "GABRIEL",
            "value": "1"
        }
    ]
}

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

The name must be sent according to the example below:

 
Send MFA Parameter user-triggered:
{
   "selectedOwner":"0"
}

(this parameter of selectedOwner asked the first time, then is stored)

📘

Data recovered

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

 

Itaú PF (with mfa)
Some accounts from Itau PF requires 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”.

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


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

{
    "value":""
}

 

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

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


- Then, make a call to the following endpoint in order to send the name of the user accessing: 
 
Send MFA Parameter user-triggered:
{
    "operatorNumber":""
}
 

After the connector sends a list of operatorNumber to select, for example: 

{
    "options": [
        {
            "label": "XX XXXXX X688",
            "value": "0"
        },
        {
            "label": "XX XXXXX X140",
            "value": "1"
        }
    ]
}

The name must be sent according to the example below:
 
Send MFA Parameter user-triggered:
{
   "operatorNumber":"0"
}

(this parameter of operatorNumberis asked the first time, then is stored)

 

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, to connect to the Santander PF connector, it will be necessary to send the payload below:

{
    "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”. This value is a base64 image encoded.

1- Paste the parameter copied from postman into the “data” attribute inside the tag.
2- Click 'Ctrl + S' to save the change.
3- The QR Code will be available on the right screen, and the account holder will simply point the cell phone to obtain the necessary token to validate the connection with the Santander PF account.
4- Copy the token obtained by reading the QR Code and activate the "Collection'' menu. Activate and expand the "Items" folder, select the request "Send MFA Parameter user-triggered". Send the POST request to the “/items” endpoint /{id}/mfa”, passing as a parameter the “ID”, which was created in step 1, and using the payload below:

{
    "token": ""
}

 

Inter PJ

This connector has the peculiarity of use 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 privateKey (API_Chave.key) and certificate(API_Certificado.crt) is a base64 located without line breaks between each file's header and footer.

Example how to get privateKey from API_Chave.key

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCx5hjjydzLHl4/
KePMBQBGO/L6jnKDQk1KFfcy+zWumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRku
qeplC4utkJxQgWUa2m7rhfr6Z+RqXeY8JaekMFk+GPGIIGhuYjJ5PxWwLXB2WEeR
WumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRku235235tsdgd265t2r4wdf52325
LWs/GulyKInRduRkZC39OadjesyNTjLhvF6EEHxkAm3C0RGvJmBSJmM9CN03/8wW
c5C20WvwcwojLQ/1m5GYNnhqyx19DjTbnV4M6cySE4b3zIzgwE9pUWdYYH9Scu1p
xPMOo+0jAgMBAAECggEAPfPawSEgYiAeRDLrYLZxJQRllroayPlC/0TtBHUVecve
fe3EOmV2tjRz0NYgKzlh/+BE9y1lOalg7q4/sZa2uuf8d9DIC/T74cuT3rZlhmFS
96lJW1V3DrgTDQv0MlTCLRU6EVORsbUGn5fEjSnpr1/IQxwweagJY0p7CZw32Hse
WumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRku235235tsdgd265t2r4wdf52325
xt1pnd9zENVPx+yHI1DEZrR9qIfBKPUhZdwNf0i8GOyjK3gnz1MDsNqzeBqnPHFh
gpTBzZK747wyaL0UzWpNYCu9wCW4DQ3DvI6l3tQC2QKBgQD1E0qxBweyx0MHsk9v
g1e7LkXsxt7xxz/vzKBHlgPy460zrLbOa0vNLJxcUdggcgjQgfjgt34HfW+Mr7PT
ZuBC7cLXQNj2jItOEAabiuZoeNQ8O9hpcH3b4Ycp9e+RbF4Xm1LRz3ne5/Kz0uf0
P4kjw/w1stXF1FHifkJiPMoQrQKBgQC51DZAsjVAo4qTpQf5LmrL2zA5hnoTaxP7
125124WumpexcNTC4F6152nBOvpOSbUyyAESEwF1dRkuvbsdgd265t2r4wdf5325
PKdQgXzwco2nIEkjkfjw7adZpEq5SkGychRSW5qxUwpVZM/ONOTl30+WGRxkGImr
9ago0ugfDwKBgBH6wFgMc/whskE2S62arS0GUAr27BRA0ef90yRtVQzUtzg7S44J
QR5kT3RWbMy0kQD7CA80ZwKVqUFhAohX28wNNWYlU8WCuhWYB2QR5KV1d9yTZ2UU
46bl/MyPRmwczypcMs9BsWcxDRU0O+AnaSA+mJo37Ib+9KLxMF2UqB5hAoGAc0eC
oH/tKTxLK2yllZ+GARDoycby1DkJHEh3BnUne15lkOCe2l8EsikkrnwdLZyMN0pj
HGlkjjbhk1DXh9u5Ilkhno98kpJ4ohX28wNNWYlU8WCuhWYB24124124DFSQACQQ
vCa3wGmTb4Yqo/GMTk5KQQMy6aWPQm4S88Bi32ECgYEAgRhstNkXeC6g9ovAbXVC
b+X+RbPUxFoCQd9wdWcjIwxgSWHM33KX60KGoRC5/ONEm0ZkHG1vckph5Z9gsPqU
vg9sISDe28CiQexk9ASDASDASD21C4M595/WcLLjRhH9NiQSjKevRvjqBotAkIhs
O1yGOetxR/35qCWcxQkl5O8=
-----END PRIVATE 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=
{
    "connectorId": 225,
    "parameters": {
        "clientId": "",
        "clientSecret": "",
        "privateKey":"",
        "certificate":""
    },
    "clientUserId": ""
}

 

Ailos

This connector group all the cooperatives behind 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 cooperative name is right, always invoke "/data" endpoint first and pick the "value" field of the specific cooperative.

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

 

BTG Pactual

The "BTG" 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”.

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

- Then, make a call to the following endpoint in order to send the name of the user accessing: 

After the connector sends a list of selectedOwner to select, for example: 

{
    "options": [
        {
            "label": "MARCOS",
            "value": "0"
        },
        {
            "label": "GABRIEL",
            "value": "1"
        }
    ]
}

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

The name must be sent according to the example below:

 
Send MFA Parameter user-triggered:
{
   "selectedOwner":"0"
}

(this parameter of selectedOwner is asked the first time, then is stored)

- Then, send MFA Parameter user-triggered:

{
    "token": ""
}

 

Caixa PF

This connector depends on the user's action in completing a multi-factor authorization. From the moment he enters his credentials, it can take up to 30 minutes for him to complete his login process.
When the login process is finally confirmed, a “login_success” event is returned and the data pertaining to that item is retrieved.This last step can take around 1 minute.