Acquiring Banks (Deprecated model)
Pluggy offers obtaining data from acquiring banks (also known as Credit Card Banks) such as Stone, Rede or GetNet. Connectors of those institutions are of type PAYMENT_ACCOUNT. Here are the connectors we offer of that type.
Data Model
Connecting an Item for acquiring banks works just like with any other Pluggy Connector, except for these differences:
- Acquiring bank connections require establishment selection if the company has multiple establishments, and will only sync data from one establishment at a time. If you require to gather data from all companies at once, you will have to connect one item per establishment.
- After connecting, Items will contain Accounts, Transactions and Identity, which can be retrieved with the usual endpoints from Pluggy API. However, the data model will be slightly different from other types of connectors. We will discuss the differences in the rest of this guide.
Accounts data model
Items of acquiring banks have only one Account, representing the selected company (Establishment):
{
"id": "37f0e756-0af1-4870-80aa-f2d0141f58c9",
"type": "BANK",
"subtype": "CHECKING_ACCOUNT",
"name": "My Company (Branch 1)", /* Name of the connected company*/
"taxNumber": "12300001000321", /* CNPJ of the connected company */
"number": "0001/12345-0", /* Establishment number */
"balance": 0, /* Ignore this field, it makes sense only in standard accounts */
"currencyCode": "BRL",
}
Transactions data model
For acquiring connectors, we map these concepts as Transactions:
- Sales: information about sales made. If the sale has installments, it is returned as a single sale, with an array of installments in it. This also includes cancelled sales.
- Receivables: data on receivables (money to be received for sales made), which may be future or already paid.
- Anticipations: information on advances made and requested.
They will all be considered transactions of the Account described earlier (representing the company), and they can all be obtained from our transactions API endpoint.
To know if a transaction is a sale, receivable or anticipation, we include the field acquirerData with the type (SALE, RECEIVABLE or ANTICIPATION) and extra fields with additional information for each type. Here are examples of each type of transaction:
{
"id": "71996b6d-8991-450c-8542-ae59069d1a9d",
"description": "",
"currencyCode": "BRL",
"amount": 34, // Gross amount of the sale
"date": "2023-07-29T20:50:53.774Z", // Date when the sale was made
"acquirerData": {
"type": "SALE",
"saleData": {
"installmentCount": 1, // Amount of installments
"paymentMethod": "CARD", // Method of payment
"authorizationCode": "123456", // Code generated by the card issuer to authorize the sale
"cardFlag": "Visa", // Flag of the card used
"cardNumber": "123456******1234", // Masked card number of the card used
"cardFundingSource": "CREDIT", // CREDIT or DEBIT
"nsu": "12345678912345", // Tax id of the transaction
"status": "APPROVED",
"netAmount": 30.6, // Total amount of the sale, with taxes applied
"mdrFee": 10, // Percentage of the merchant discount rate
"mdrFeeAmount": 3.4, // Total amount of the merchant discount rate
"installments": [
{
"number": 1, // Ordinal number of the installment
"netAmount": 17, // Amount of the installment, with taxes applied
"receiptDate": "2023-08-28T00:00:00"
},
{
"number": 2, // Ordinal number of the installment
"netAmount": 17, // Amount of the installment, with taxes applied
"receiptDate": "2023-07-28T00:00:00"
}
],
"terminalId": "1234561234561234" // Id of the terminal (maquininha) used for the sale
}
}
}
{
"id": "71996b6d-8991-450c-8542-ae59069d1a9d",
"description": "",
"currencyCode": "BRL",
"amount": 12.10, # Net amount received
"date": "2023-10-02T03:00:00.000Z", # The date it was received
...
"acquirerData": {
"type": "RECEIVABLE",
"receivableData": {
"paymentId": "123445567755353",
"establishment": {
"companyCode": "12300001000321", # CNPJ of the company receiving the payment
"companyName": "My Company (Branch 1)", # Name of the receiving company
"receivingBank": "Banco do Brasil S.A.", # Name of the receiving bank
"agency": "1234", # Agency of the receiving account
"account": "12345678-9" # Number of the receiving account
},
"settlementStatus": "PAID", # Status of the payment
"cardFlag": "MasterCard Crédito"
}
}
}
{
"id": "71996b6d-8991-450c-8542-ae59069d1a9d",
"description": "",
"currencyCode": "BRL",
"amount": 313.28, # Gross amount of the anticipation
"date": "2023-02-06T03:00:00.000Z", # Date the anticipation was requested
"acquirerData": {
"type": "ANTICIPATION",
"anticipationData": {
"status": "APPROVED",
"netAmount": 308.66, # Net amount of the anticipation
"fee": 1.82, # Percentage of monthly fee (e.g 1.5 = 1.5%)
"feeAmount": 4.62 # Fee amount
}
}
}
Transactions status
The original transaction field status (POSTED or PENDING) should be ignored for acquiring bank transactions. Instead, the following fields should be inspected for status:
- Sales
statuscan beAPPROVEDif the sale was completed orCANCELLEDif it was cancelled by the customer. - Receivables
settlementStatuscan be:- PAID: it was received on the target bank account
- SENT: it was sent by the acquiring bank, but not yet received.
- REJECTED: it was rejected.
- EXPECTED: it is a future receivable which has not yet been sent.
- OTHER
- Anticipation
statuscan be:- SIMULATED: the anticipation has been created but not requested to the institution
- REQUESTED: the anticipation has been requested to the institution
- CANCELLED: the anticipation has been cancelled by the user
- IN_ANALYSIS: the anticipation is being reviewed to see if it should be accepted by the institution
- APPROVED: the anticipation has been approved
API Reference
For additional information about all the fields returned in acquirer bank transactions, check out our API reference.
Updated 6 months ago