Transactions data of the accounts provide insights into the user's financial behavior. These transactions are recovered for the product Account when syncing the item for the first time and can be listed for all account types CREDIT (credit cards & loans) or BANK (checking & savings account).

You can review more about how to recover the transactions on the Transactions endpoint. Transactions can be recovered up to 500 per request and should be paginated for further transaction history.

For transactions that are available in "Open" invoices or are future installments, the status will return them as PENDING, since the transaction has not yet impacted the due balance.

{
  "total": 1,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "id": "6ec156fe-e8ac-4d9a-a4b3-7770529ab01c",
      "description": "TED Example",
      "descriptionRaw": null,
      "currencyCode": "BRL",
      "amount": 1500,
      "date": "2021-04-12T00:00:00.000Z",
      "balance": 3500,
      "category": "Transfer",
      "categoryId": "05000000",
      "accountId": "03cc0eff-4ec5-495c-adb3-1ef9611624fc",
      "providerCode": "123456",
      "type": "CREDIT",
      "status": "POSTED",
      "paymentData": null,
      "operationCategory": null,
      "creditCardMetadata": {
        "installmentNumber": 1,
        "totalInstallments": 6,
        "totalAmount": 9000
      },
      "merchant": null,
      "providerId": null
    } 
	]
}

Sign Convention for Credit Card Transactions

Credit card transactions use the following sign convention to reflect changes to the card balance:

• Positive amounts (+X) indicate debits—i.e., new charges that increase the outstanding balance (you owe more).
• Negative amounts (–X) indicate credits/payments—i.e., funds that reduce the outstanding balance.

// GET /transactions?from=2025‑06‑01&to=2025‑06‑30
[
  {
    "id": "txn_001",
    "date": "2025‑06‑05",
    "description": "Grocery Store",
    "amount": 75.00
  },
  {
    "id": "txn_002",
    "date": "2025‑06‑10",
    "description": "Statement Payment",
    "amount": -150.00
  }
]

Transaction Payment Data Schema

Some transactions that are Payments or Transfers may contain related data to understand from whom and to whom the operation was made, reference numbers like PIX Identifier, the user's defined reason or the method used to make the movement.

{
  "payer": {
    "name": "Tiago Rodrigues Santos",
    "branchNumber": "090",
    "accountNumber": "1234-5",
    "routingNumber": "001",
    "routingNumberISPB": "00000000",
    "documentNumber": {
      "type": "CPF",
      "value": "882.937.076-23"
    }
  },
  "reason": "Taxa de serviço",
  "receiver": {
    "name": "Pluggy",
    "branchNumber": "999",
    "accountNumber": "9876-1",
    "routingNumber": "002",
    "routingNumberISPB": "27652684",
    "documentNumber": {
      "type": "CNPJ",
      "value": "08.050.608/0001-32"
    }
  },
  "paymentMethod": "TED",
  "referenceNumber": "123456789",
  "receiverReferenceId": "company-reference-id"
}

Each participant of the "PaymentData" will have references to the account in which the transfer was originated or received.

Boleto Metadata

If the transaction is related to a Boleto, the following information will be returned in the boletoMetadata object (see supported institutions)

{
  "payer": {
    "name": "Francisco Souza",
    "branchNumber": "1111",
    "accountNumber": "11111-7",
    "routingNumber": "341",
    "documentNumber": {
      "type": "CPF",
      "value": "111.111.111-11"
    },
    "routingNumberISPB": "60701190"
  },
  "receiver": {
    "name": "Pluggy Brasil Instituição de Pagamento LTDA",
    "documentNumber": {
      "type": "CNPJ",
      "value": "37.943.755/0001-30"
    }
  },
  "paymentMethod": "BOLETO",
  "boletoMetadata": {
    "baseAmount": 1520,
    "digitableLine": "11190000111001113911100000021110600000000111000",
    "discountAmount": 0,
    "interestAmount":10
  },
  "referenceNumber": "173631925"
}

Transaction Credit Card Metadata Schema

Transactions associated with credit cards may contain extra data like the total of installments, the installment number and the total amount (the sum of all installments).

{
  "installmentNumber": 1,
  "totalInstallments": 6,
  "totalAmount": 9000,
  "payeeMCC": 1234,
  "cardNumber": "1234",
  "billId": "03cc0eff-4ec5-495c-adb3-1ef9611624fc"
}

Transaction Merchant Schema

Transactions retrieved may contain extra information regarding the merchant/company associated with the transaction. Such information is the legal name of the company, cnpj number and the merchants associated category.

{
  "name": "Netflix",
  "businessName": "NETFLIX ENTRETENIMENTO BRASIL LTDA.",
  "cnpj": "00.000.000/0000-00",
  "cnae": "5911100",
  "category": "Video Streaming"
}

📘

See Transaction in our API reference for more information.

How to synchronize and merge transactions

Prerequisites:

• Configure webhooks for transactions/updated, transactions/deleted and transactions/created.

There are a few things to do:

• Receive the transactions/created webhook event, and using the createdTransactionsLink page all the transactions available and insert them in your data source.)

{
    "itemId": "de7bbf5a-abf2-47e4-94b1-586b36758423",
    "event": "transactions/created",
    "id": "de7bbf5a-abf2-47e4-94b1-586b36758423",
    "eventId": "4e69d62d-b7c8-4f01-b591-a1d8a94710b9",
    "accountId": "0d5a0de2-9c82-4ea2-af50-31643a632a33",
    "transactionsCreatedAtFrom": "2025-02-13T17:21:53.719Z",
    "createdTransactionsLink": "https://api.pluggy.ai/transactions?accountId=0d5a0de2-9c82-4ea2-af50-31643a632a33&createdAtFrom=2025-02-13T17:21:53.719Z"
}

• Receive the transactions/updated webhook event, and using the list of IDs received, you should page the /transactions endpoint by an ids list, updating your data with it.

{
  "event":"transactions/updated",
  "eventId":"d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
  "accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
  "transactionIds": [
    "5a14feae-eaa7-423a-820c-6b83837c35b7",
    "786c7d98-6085-4879-9c7f-2255260e2436"
  ]
}

• Receive the transactions/deleted webhook and then delete all transactions matching the specified IDs.

{
  "event":"transactions/deleted",
  "eventId":"d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId":"a5c763cb-0952-457b-9936-630f79c5b016",
  "accountId": "8a6e2c17-2817-40bb-b03d-546febc6a60a",
  "transactionIds": [
    "5a14feae-eaa7-423a-820c-6b83837c35b7",
    "786c7d98-6085-4879-9c7f-2255260e2436"
  ]
}

🚧

Transaction Id can change

When Pluggy syncs transactions with the Financial Institution, we create a hash related to the transaction, that allows us to maintain the transaction's id between synchronization.
In case there are too many changes on the transaction's data such as Date, Description, or Amount, that can't allow us to confirm the transaction is the same as the one before.
In those cases, we will delete the existing transaction and create a new one.
Please review the How to synchronize and merge transactions guide for more information.

End-of-Day Balance

Sometimes for conciliation use cases, you want to obtain the balance of an account at the end of a certain day (normally it's yesterday). The account's usual balance field will not solve this need, as it could have been already affected by today's transactions.

In these cases, you can obtain an end-of-day balance by looking at the balance of the latest transaction within that day. In our Transactions endpoint, it is the first one shown for that day:

{
  "total": 1,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "description": "Example transaction 4",
      "amount": -100,
      "date": "2024-10-04T18:00:00.000Z",
      "balance": 800 // End-of-day balance of October 4th
      ...
    },
    {
      "description": "Example transaction 3",
      "amount": -100,
      "date": "2024-10-04T10:00:00.000Z",
      "balance": 900
      ...
    },
    {
      "description": "Example transaction 2",
      "amount": -100,
      "date": "2024-10-03T18:00:00.000Z",
      "balance": 1000 // End-of-day balance of October 3rd
      ...
    },
    {
      "description": "Example transaction 1",
      "amount": -100,
      "date": "2024-10-03T10:00:00.000Z",
      "balance": 1100
      ...
    } 
	]
}

This is only supported by Pluggy's Direct connectors (Itau PF & PJ, Sicredi PF & PJ, Sicoob PF & PJ, Bradesco PF & PJ, Santander PJ).

Itaú PJ aggregable transactions

Within the institution Itaú PJ, there are certain aggregable transactions (SISPAG and PIX TRANSF types). These aggregable transactions can come in one of two forms:

• Consolidated form: many operations of the same type within the same day are represented as a single Transaction
• Detailed form: each operation is represented as a separate Transaction

For our Itaú PJ regulated connector, they will always come in Detailed form.

For our Itaú PJ direct connector, it will depend on the Item's connected company's configuration. To force Detailed view, the user needs to access Internet Banking and go to Contas a pagar > Manutenção > Alteração de serviço and turn all extratos to Detalhado. This requires an access token to change, and a user with enough permissions.

If the Item has the Payment Data product enabled, our Direct Connector will attempt to disaggregate SISPAG and PIX transactions as much as possible, even if the company doesn't have detailed transactions enabled. However, if you need guaranteed disaggregation, it is recommended to use the Regulated connector.

Itaú PJ SISPAG Supported

When retrieving payment data for SISPAG transfers, there are certain specific subtypes that our API handles. These cases are:

• SISPAG FORNECEDORES (Suppliers)
• SISPAG PIX
• SISPAG CONCESSIONARIA (Utility Company)
• SISPAG MISMA TITULARIDADE (Same Ownership)