Recupere até 12 meses de dados de transações.

Os dados das transações das contas fornecem insights sobre o comportamento financeiro do usuário. Essas transações são recuperadas para o produto Account ao sincronizar o item pela primeira vez e podem ser listadas para todos os tipos de conta CREDIT (cartões de crédito e empréstimos) ou BANK (conta corrente e poupança).

Você pode revisar mais sobre como recuperar as transações no Transactions endpoint. As transações são sempre recuperadas em páginas de 500, usando um mecanismo de paginação baseado em cursor.

Para transações que estão disponíveis em faturas "Abertas" ou são parcelas futuras, o status as retornará como PENDING, uma vez que a transação ainda não impactou o saldo devedor.

{
  "total": 1,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "id": "6ec156fe-e8ac-4d9a-a4b3-7770529ab01c",
      "description": "Exemplo TED",
      "descriptionRaw": null,
      "currencyCode": "BRL",
      "amount": 1500,
      "date": "2021-04-12T00:00:00.000Z",
      "balance": 3500,
      "category": "Transferência",
      "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
    }
  ]
}

Convenção de Sinal para Transações de Cartão de Crédito#

As transações de cartão de crédito usam a seguinte convenção de sinal para refletir mudanças no saldo do cartão:

• Valores positivos (+X) indicam débitos -- ou seja, novas cobranças que aumentam o saldo devedor (você deve mais).
• Valores negativos (-X) indicam créditos/pagamentos -- ou seja, fundos que reduzem o saldo devedor.

// GET /transactions?from=2025-06-01&to=2025-06-30
[
  {
    "id": "txn_001",
    "date": "2025-06-05",
    "description": "Supermercado",
    "amount": 75.00
  },
  {
    "id": "txn_002",
    "date": "2025-06-10",
    "description": "Pagamento de Fatura",
    "amount": -150.00
  }
]

Esquema de Dados de Pagamento de Transação#

Algumas transações que são Pagamentos ou Transferências podem conter dados relacionados para entender de quem e para quem a operação foi feita, números de referência como Identificador PIX, a razão definida pelo usuário ou o método usado para realizar o movimento.

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

Cada participante do "PaymentData" terá referências à conta na qual a transferência foi originada ou recebida.

Metadados do Boleto#

Se a transação estiver relacionada a um Boleto, as seguintes informações serão retornadas no objeto boletoMetadata (veja instituições suportadas).

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

Dados de Pagamento & Dados de Pagamento de Boleto estão disponíveis para nossos conectores diretos, consulte a Página de Cobertura para mais informações.

Esquema de Metadados de Cartão de Crédito de Transação#

Transações associadas a cartões de crédito podem conter dados adicionais, como o total de parcelas, o número da parcela e o valor total (a soma de todas as parcelas).

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

Esquema de Comerciante de Transação#

As transações recuperadas podem conter informações extras sobre o comerciante/empresa associada à transação. Essas informações são o nome legal da empresa, número do CNPJ e a categoria associada aos comerciantes.

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

Veja Transaction em nossa referência de API para mais informações.

Como sincronizar e mesclar transações#

Pré-requisitos:

• Configure webhooks para transactions/updated, transactions/deleted e transactions/created.

Há algumas coisas a fazer:

• Receba o evento webhook transactions/created, e usando o createdTransactionsLink pague todas as transações disponíveis e insira-as em sua fonte de dados.

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

• Receba o evento webhook transactions/updated, e usando a lista de IDs recebidos, você deve paginar o endpoint /transactions por uma lista de ids, atualizando seus dados com isso.

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

• Receba o webhook transactions/deleted e então exclua todas as transações que correspondem aos IDs especificados.

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

O Id da transação pode mudar

Quando a Pluggy sincroniza transações com a Instituição Financeira, criamos um hash relacionado à transação, que nos permite manter o id da transação entre as sincronizações. Caso haja muitas mudanças nos dados da transação, como Data, Descrição ou Valor, que não nos permitem confirmar que a transação é a mesma que a anterior. Nesses casos, excluiremos a transação existente e criaremos uma nova. Por favor, revise o guia Como sincronizar e mesclar transações para mais informações.

Recomendações

• Use um tamanho de página de 500 transações. (Desde 01/12/2025, este será o tamanho de página padrão ao recuperar transações).

Saldo de Fim de Dia#

Às vezes, para casos de conciliação, você deseja obter o saldo de uma conta no final de um determinado dia (normalmente é o dia anterior). O campo saldo usual da conta não resolverá essa necessidade, pois pode já ter sido afetado pelas transações de hoje.

Nesses casos, você pode obter um saldo de fim de dia observando o saldo da última transação dentro daquele dia. Em nosso endpoint de Transações, é a primeira mostrada para aquele dia:

{
  "total": 1,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "description": "Transação de exemplo 4",
      "amount": -100,
      "date": "2024-10-04T18:00:00.000Z",
      "balance": 800
    },
    {
      "description": "Transação de exemplo 3",
      "amount": -100,
      "date": "2024-10-04T10:00:00.000Z",
      "balance": 900
    },
    {
      "description": "Transação de exemplo 2",
      "amount": -100,
      "date": "2024-10-03T18:00:00.000Z",
      "balance": 1000
    },
    {
      "description": "Transação de exemplo 1",
      "amount": -100,
      "date": "2024-10-03T10:00:00.000Z",
      "balance": 1100
    }
  ]
}

Isso é suportado apenas pelos conectores Diretos da Pluggy (Itau PJ, Sicredi PF & PJ, Bradesco PJ).

Caso Santander PJ#

Para esta instituição, sempre que possível, devemos nos basear nos tipos de transação fornecidos pela Contamax para identificar e interpretar os movimentos da conta.

Essas transações não aparecem todos os dias no extrato. Em geral, são registradas apenas em dias úteis. Mesmo assim, pode haver dias úteis em que nenhuma transação é mostrada, por exemplo, se não houver atividade durante o dia.

No final de cada dia, apenas uma das duas operações pode ocorrer, dependendo do saldo da conta antes do fechamento diário:

• Saldo final positivo (acima de zero): Uma aplicação automática de investimento é executada com o saldo disponível.
• Saldo final negativo (abaixo de zero): Uma resgate automático é executado para cobrir o saldo negativo.

Ambas as operações nunca aparecerão no mesmo dia -- apenas uma aplicação ou um resgate, de acordo com o saldo final da conta no final do dia.

Nos casos em que essas transações aparecem no extrato, elas podem ser interpretadas como o resultado do saldo de fim de dia:

• Uma aplicação indica que o saldo final do dia foi positivo.
• Um resgate indica que o saldo final do dia foi negativo.

Transações agregáveis do Itau PJ#

Dentro da instituição Itau PJ, existem certas transações agregáveis (tipos SISPAG e PIX TRANSF). Essas transações agregáveis podem vir em uma de duas formas:

• Forma consolidada: muitas operações do mesmo tipo dentro do mesmo dia são representadas como uma única Transação
• Forma detalhada: cada operação é representada como uma Transação separada

Para nosso conector regulado do Itau PJ, elas sempre virão em forma detalhada.

Para nosso conector direto do Itau PJ, dependerá da configuração da empresa conectada do Item. Para forçar a visualização Detalhada, o usuário precisa acessar o Internet Banking e ir para Contas a pagar > Manutenção > Alteração de serviço e mudar todos os extratos para Detalhado. Isso requer um token de acesso para mudar e um usuário com permissões suficientes.

Se o Item tiver o produto Dados de Pagamento habilitado, nosso Conector Direto tentará desagregar transações SISPAG e PIX o máximo possível, mesmo que a empresa não tenha transações detalhadas habilitadas. No entanto, se você precisar de desagregação garantida, é recomendável usar o conector Regulamentado.

Itau PJ SISPAG Suportado#

Ao recuperar dados de pagamento para transferências SISPAG, existem certos subtipos específicos que nossa API manipula. Esses casos são:

• SISPAG FORNECEDORES (Fornecedores)
• SISPAG PIX
• SISPAG CONCESSIONARIA (Companhia de Utilidade)
• SISPAG MISMA TITULARIDADE (Mesma Propriedade)

Limitação de cobertura do Santander PJ#

Em contas empresariais do Santander, quando a conta é conectada através de um operador de conta, o histórico de transações disponível é limitado aos últimos 3 meses.

Além disso, se um único dia contiver mais de 400 transações, apenas as primeiras 400 serão recuperadas -- quaisquer transações além desse limite não serão retornadas.

Nesses casos, nossa recomendação geral é usar o conector regulamentado da instituição para evitar essa limitação.