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

*For Itaú PF with joint account (conta conjunta) 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": ""
}

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

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.

 

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 “PARTIAL_SUCCESS”, so your connection will be ended.

Remember that the first time you connect an account, the result will be “PARTIAL_SUCCESS” as BB PJ does not bring any information when you authorize a device for the first time. So, you need to update the connection in order to get “SUCCESS” and bring all the account information.

 

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: 
 
Send MFA Parameter user-triggered:
{
    "titular":""
}
 

The name must be sent according to the example below:

 
Send MFA Parameter user-triggered:
{
   "titular":"RENATO"
}

 

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

The name must be sent according to the example below:

 
Send MFA Parameter user-triggered:
{
   "titular":"VALTER"
}

 

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" and "clientSecret" in client home banking account. Follow this link to do it.

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

{
    "connectorId": 225,
    "parameters": {
        "clientId": "",
        "clientSecret": ""
    },
    "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": ""
}