Retrieve up to 12 months of transaction data.

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 are always retrieved in pages of 500, using a cursor-based pagination mechanism.

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 servico",
  "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 Instituicao 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"
}

Payment Data & Boleto Payment Data are available for our direct connectors, refer to Coverage Page for more information.

Transaction Credit Card Metadata Schema#

Transactions associated with credit cards may contain additional data, such as 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. The payload carries only the transaction IDs (not the deleted amount, date or description). Handle deletions idempotently: a transaction can occasionally disappear from a sync and reappear in a later one, so a deleted event is not necessarily permanent.

{
  "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 — how to reconcile

When Pluggy syncs transactions with the financial institution, we compute a hash that lets us keep the same transaction id across syncs. Most changes — including the PENDING → POSTED transition — arrive as an in-place update (transactions/updated) that preserves the id.

Only when the data changes too much to confirm it is the same transaction — typically date, description or amount — do we delete the existing transaction and create a new one with a new id. The payload does not include a field linking the deleted transaction to its replacement.

To reconcile across a delete/recreate, anchor on a provider-side identifier: providerId (the provider's transaction id, only returned for Open Finance connectors) or providerCode (an institution code such as an NSU; format varies per institution). For direct (non-Open-Finance) connectors there is no guaranteed stable identifier, so match on attributes (date + amount + description).

Reconnecting an account creates a new item, whose transactions receive new ids; Pluggy does not automatically de-duplicate transactions across items. Reconcile on your side using providerId (Open Finance) plus transaction attributes.

Recommendations

• Use a page size of 500 transactions. (Since 01/12/2025, this will be the default page size when recovering transactions).

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
    },
    {
      "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
    },
    {
      "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 PJ, Sicredi PF & PJ, Bradesco PJ).

Santander PJ case#

For this institution, whenever possible, we should rely on the transaction types provided by Contamax to identify and interpret account movements.

These transactions do not appear every day in the statement. In general, they are recorded only on business days. Even so, there may be business days in which no transactions are shown, for example if there is not activity during the day.

At the end of each day, only one of the two operations can occur, depending on the account balance before the daily closing:

• Positive ending balance (above zero): An automatic investment application is executed with the available balance.
• Negative ending balance (below zero): An automatic redemption is executed to cover the negative balance.

Both operations will never appear on the same day -- only an application or a redemption, according to the account's final balance at the end of the day.

In the cases where these transactions appear in the statement, they can be interpreted as the end-of-day balance result:

• An application indicates that the final balance for the day was positive.
• A redemption indicates that the final balance for the day was negative.

Itau PJ aggregable transactions#

Within the institution Itau 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 Itau PJ regulated connector, they will always come in Detailed form.

For our Itau 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 > Manutencao > Alteracao de servico 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.

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

Santander PJ coverage limitation#

In Santander Business accounts, when the account is connected through an account operator, the available transaction history is limited to the past 3 months.

Additionally, if a single day contains more than 400 transactions, only the first 400 will be retrieved -- any transactions beyond that limit will not be returned.

In these cases, our general recommendation is to use the institution's regulated connector to avoid this limitation.