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

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

```json
{
  "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

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

> For Caixa PF please see below (Exception Flows).

### Caixa PJ

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

### Santander PF

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

### Agora

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

### Genial

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

### Sicredi PJ

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

### Clear

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

### Sicoob PJ / Sicoob PF

```json
{
  "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

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

### Modal Mais

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

### XP

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

### Rico

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

### Conta Simples

```json
{
  "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).

### Bradesco PJ

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

Send MFA Parameter user-triggered:

```json
{
  "token": ""
}
```

### B3 CEI

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

Send MFA Parameter user-triggered:

```json
{
  "code": ""
}
```

### BTG Pactual

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

Send MFA Parameter user-triggered:

```json
{
  "token": ""
}
```

### Safra

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

Send MFA Parameter user-triggered:

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

### Avenue

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

Send MFA Parameter user-triggered:

```json
{
  "token": ""
}
```

### Genial

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

Send MFA Parameter user-triggered:

```json
{
  "mfa": ""
}
```

### Empiricus Investimentos

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

Send MFA Parameter user-triggered:

```json
{
  "value": ""
}
```

## 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 is 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.

### Sicoob PJ

```json
{
  "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 e 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:

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

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

Make calls on the "Specific Item" endpoint passing the ItemId to check the status of the connection until you get the `parameter` element in the response with the `options` element which contains the list of accounts registered at the institution.

Then call the "Send MFA Parameter user-triggered" endpoint with the selected account value. After that, the token MFA parameter will need to be provided with the correct user-provided value.

Resume making calls on the "Specific Item" endpoint until the `executionStatus` attribute is set to `SUCCESS` (or `PARTIAL_SUCCESS`), meaning your connection has been created/updated successfully.

> **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. The account used for the connection must have 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:

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

Call the "Specific Item" endpoint until you get `executionStatus` as `WAITING_USER_INPUT` and the `parameter` attribute with a list of cell phones registered at the institution. Select a phone, then provide the SMS token URL received on that phone.

### Itau PF (Conta Conjunta)

First, make a call on the "Create Item" endpoint:

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

Then, call the "Specific Item" endpoint until you get the `executionStatus` as `WAITING_USER_INPUT`. The `parameter` element will include a list of accounts (operators). Select one and send it via the "Send MFA Parameter user-triggered" endpoint.

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

### Itau PF (with MFA)

Some accounts from Itau PF require MFA. Create the item with the standard credentials, then poll the "Specific Item" endpoint until `WAITING_USER_INPUT` with `"name": "mfa"` in the parameter. Send the MFA token via the "Send MFA Parameter user-triggered" endpoint.

### Itau PJ

The "Itau" connector is mapped to both simple (individual) and joint accounts. To connect to the joint account, send the name of the account holder via the "Send MFA Parameter user-triggered" endpoint.

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

### XP (CPF access - joint account)

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

```json
{
  "connectorId": 202,
  "parameters": {
    "account": "",
    "password": "",
    "token": ""
  },
  "clientUserId": ""
}
```

Poll the "Specific Item" endpoint until `WAITING_USER_INPUT` with a `selectedAccount` parameter, then send the selected account value.

### Santander PJ

For Santander PJ, the connection requires scanning a QR code and sending an extra validation code.

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

Poll the "Specific Item" endpoint until `WAITING_USER_INPUT`. The `parameter` will contain a base64 encoded QR code image in the `data` attribute. Display the QR code, scan it with a phone, and send the resulting token via the "Send MFA Parameter user-triggered" endpoint.

### Inter PJ

This connector uses the bank's OAuth 2 API. You need to first generate and obtain `clientId`, `clientSecret`, the files `API_Chave.key` and `API_Certificado.crt` from the client's home banking account.

The private key and certificate should be provided as base64 without line breaks between each file's header and footer.

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

### 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, send the name of the account holder via the "Send MFA Parameter user-triggered" endpoint.

### Caixa PF and PJ

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

Keep in mind that from the moment the user enters their 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:

Caixa PF:

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

Caixa PJ:

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

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

Use the "Specific Item" endpoint (`GET /items/:id`) to check the connection status. Call the endpoint until the response attribute `executionStatus` has the value `USER_AUTHORIZATION_PENDING`, just like in the example below:

```json
{
  "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==,cHJ1ZWJhJJ=="
    }
  }
}
```

**Now the user should authorize the new device from their Caixa mobile app**, 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 the list for the device with the same name that was returned in the `deviceNickname` field of the previous call, and select it.
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 three 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 (`PATCH /items/:id`).

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 the execution status can quickly change, and you can also find a `CREATED` or even `LOGIN_IN_PROGRESS` status.

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

```json
{
  "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 authorizes the new device, it's necessary to wait 30 minutes until Caixa approves it. Then we can have two different situations:

1. The user triggers an update, and if everything is ok we will return `SUCCESS`.
2. Our automatic update system will run every 6 hours (after the 30 minutes necessary to authorize the device) in order to get `status: SUCCESS` on the Items that did get the device authorized, but didn't have the data collected (were not updated after the 30 minutes). This flow runs 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 - yyyy-mm-dd hh-mm`) through the Safra mobile app.

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

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

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

```json
{
  "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 from the user.

or

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

or

- 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 from the user.

### Banco Inter PF

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 login flow will be by QR:

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

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

```json
{
  "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 commas.

```json
{
  "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 the Pluggy API.

### Mercado Bitcoin

This connector requires creating an API Key (chave de API) in the institution account. To do that, follow [this tutorial](https://suporte.mercadobitcoin.com.br/hc/pt-br/articles/360040781391-Como-gerar-uma-chave-de-API). 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 and the FI, back and forth.

### OAuth v1

The first implementation Pluggy provided returns an `oauthUrl` on the [List Connectors](/reference/connectors-list) endpoint that is necessary to redirect the user to provide consent.

```json
{
  "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 they authorize Pluggy, we will redirect them back to your application.

This affects the connectors: "MercadoPago".

### OAuth v2

After improving the flow from the previous version, we 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; instead, they don't require any credential to start the execution, and have an `oauth` flag to indicate that these connectors authenticate through OAuth.

```json
{
  "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:

```json
{
  "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` makes it easy to understand that an OAuth flow is required, and the `data` attribute returns the URL to redirect the user to. After the callback, the Item will be created.

On updates, the flow will be the same.