Transaction
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 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.
Property | Description | Description | Required |
---|---|---|---|
date | date | Posted date of the transaction, formatted in ISO8601 (UTC). | ✅ |
description | string | Description of the transaction, text recovered from the financial institution. | ✅ |
descriptionRaw | string | If available, raw description provided by the financial institution. | |
amount | number | Amount of the transaction. | ✅ |
amountInAccountCurrency | number | Amount of the transaction in Account's Currency, if the transaction is an international transaction. | |
balance | number | Balance after the transaction was made. Only returned for supported financial institutions. | |
currencyCode | string | Currency ISO code of the transaction, ie BRL, USD. | ✅ |
category | string | null | Category of the transactions, provided by our Enrichment Categorizer. Note: requires Pro subscription level. | |
providerCode | string | If available, provider's transaction code. | |
status | string | Status of the transaction. PENDING or POSTED. | ✅ |
type | string | Type of the transaction. DEBIT (outflow) or CREDIT (inflow) | ✅ |
paymentData | object | Data related to the payment/transfer. | |
creditCardMetadata | object | Data related to a credit card transaction. | |
merchant | object | null | Data related to the merchant associated with the transaction. Note: requires feature enabled and Pro subscription level. |
{
"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,
"creditCardMetadata": {
"installmentNumber": 1,
"totalInstallments": 6,
"totalAmount": 9000
},
"merchant": null
}
]
}
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.
Property | Description |
---|---|
payer | The identity of the sender of the transfer. |
receiver | The identity of the receiver of the transfer. |
referenceNumber | The identifier for the transaction that is provided by the institution. |
receiverReferenceId | The identifer provided by the receiver to track the payment |
paymentMethod | The type of transfer used "PIX", "TED", "DOC". |
reason | The payer description/motive of the transfer. |
{
"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.
Property | Description |
---|---|
name | Name of the participant (Payer or Receiver) |
branchNumber | Agency number |
accountNumber | Account number, with verification digit. |
routingNumber | Bank COMPE identification number. Full list can be found here. |
routingNumberISPB | Bank ISPB identification number. Full list can be found here. |
documentNumber | Formatted CPF or CNPJ of the participant. |
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"
}
Property | Description |
---|---|
installmentNumber | The installment number associated with the transaction. |
totalInstallments | The total of installments associated with the transaction. |
totalAmount | The total amount (sum of all installments). Only available when the purchase was made in installments. |
payeeMCC | Merchant category code of the payee |
purchaseDate | Original date of the purchase, for transactions made with installments. |
cardNumber | The credit Card Number associated with the transaction can be different from the account if it's done by an additional or virtual card. |
billId | Id of the bill associated to the transaction. Only available on Open Finance connectors |
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"
}
Property | Description |
---|---|
name | Merchant simple name. |
businessName | Merchant legal registered name. |
cnpj | CNAE number associated to the merchant. |
cnae | CNPJ number associated to the merchant |
category | Category of the merchant. Provided by our Enrichment Categorizer. |
See Transaction in our API reference for more information.
How to synchronize and merge transactions
-
After an item creation, you can save all the transactions retrieved without any other logic.
-
On item update, there are two things to do:
- Get all new transactions using our transactions endpoint and make an upsert in your database using the transaction
id
field. - Has an endpoint to receive
transactions/deleted
and then delete all the transactions that match with the specified ids, once a webhook is received.
- Get all new transactions using our transactions endpoint and make an upsert in your database using the transaction
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.
Updated 4 months ago