Acquiring Banks (BETA)

Pluggy offers obtaining data from acquiring 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 establishments at once, you will have to connect them separately, that is, one item per establishment.
  • After connecting, Items will contain Accounts, Sales, Receivables, Anticipations and Identity, which can be retrieved from Pluggy API in their respective endpoints.

Identity data model

Identity contains the establishment's general information. All the fields' information can be found here.

{
  "id": "42888436-62f5-49d2-8cf9-e312c7939509",
  "fullName": "Francisco Sousa",
  "companyName": "Pluggy Inc.",
  "document": "076.630.975-48",
  "taxNumber": "38.512.121/0001-95",
  "documentType": "CPF",
  "jobTitle": "Comercial",
  "birthDate": "1991-05-01T00:00:00.000Z",
  "establishmentCode": "001",
  "establishmentName": "Pluggy Establishment 1",
  "createdAt": "2020-09-30T14:38:12.724Z",
  "updatedAt": "2020-09-30T14:38:12.724Z"
}

Accounts data model

Accounts represent the bank account in which the establishment can receive funds transferred by the acquiring bank.

More information of each field can be found here.

[{
  "id": "37f0e756-0af1-4870-80aa-f2d0141f58c9",
  "type": "BANK",
  "subtype": "EXTERNAL_ACCOUNT",
  "name": "Conta Corrente",
  "taxNumber": "53.288.835/0001-55",
  "number": "033/0001/12345-0",
  "balance": 0,
  "currencyCode": "BRL",
}]

Sales, Receivables and Anticipation data model

For acquiring connectors, the core data is provided in three different entities:

1. Sales

Returns the information about sales made. If the sale has installments, it is returned as a single sale, with an array of installments in it.

It also includes cancelled sales (chargeback).

Can be retrieved from GET /acquirer-sales?item-id={id}

{
      "id": "71996b6d-8991-450c-8542-ae59069d1a9d",
      "itemId": "9aab8d24-c89b-4b0e-8974-7dd5614686e4",
      "description": "Venda a Prazo",
      "currencyCode": "BRL",
      "date": "2023-10-02T03:00:00.000Z",
      "grossAmount": 34,
      "installmentCount": 2,
      "paymentMethod": "CARD",
      "authorizationCode": "123456",
      "cardFlag": "VISA",
      "cardNumber": "123456******1234",
      "cardFundingSource": "CREDIT",
      "nsu": "12345678912345",
      "status": "APPROVED",
      "netAmount": 30.6,
      "mdrFee": 10,
      "mdrFeeAmount": 3.4,
      "installments": [
        {
          "number": 1,
          "netAmount": 15.3,
          "grossAmount": 17,
          "receiptDate": "2023-11-02T00:00:00"
        },
        {
          "number": 2,
          "netAmount": 15.3,
          "grossAmount": 17,
          "receiptDate": "2023-12-02T00:00:00"
        }
      ],
      "terminalId": "1234561234561234"
}

Data Dictionary

PropertyDescriptionRequired
idUnique and internal identifier of the sale.
descriptionDesciption of the sale
currencyCodeCurrency ISO code of the sale, ie BRL, USD.
datePosted date of the sale, formatted in ISO8601
grossAmountGross amount of the sale
installmentCountNumber of installments from the sale
paymentMethodPayment method.
Can be: CARD, PIX
authorizationCodeSale authorization code.
cardFlagCredit card brand
Can be: VISA; MASTERCARD; AMEX; CABAL; ELO; OTHER
cardNumberCredit card number
cardFundingSourceType of payment.
Can be: DEBIT, CREDIT, PIX.
nsuAcquiring identification of the sale
statusStatus of the sale.
Can be: APPROVED; CANCELLED
netAmountNet amount of the sale
mdrFeePercentage of the fee charged from the sale
mdrFeeAmountAmount of the fee charged from the sale
installments.numberInstallment's reference number
installments.netAmountInstallment's net amount
installments.grossAmountInstallment's gross amount
installments.receiptDateDate which the sale amount will be transfered to the seller

2. Receivables

Data from receivables, which is the money to be received for sales made.

The information presented here refers to both future or already paid receivable.

Can be retrieved from GET /acquirer-receivables?item-id={id}

{
      "id": "71996b6d-8991-450c-8542-ae59069d1a9d",
      "itemId": "9aab8d24-c89b-4b0e-8974-7dd5614686e4",
      "description": "",
      "currencyCode": "BRL",
      "grossAmount": 34,
      "netAmount": 31.1,
      "date": "2023-10-02T03:00:00.000Z",
      "paymentId": "123445567755353",
      "settlementStatus": "PAID",
      "destinationAccount": {
        "receivingBank": "Banco do Brasil S.A.",
        "agency": "1234",
        "account": "12345678-9"
      },
      "cardFlag": "VISA",
      "relatedSales": [
        {
          date: '2023-10-01T18:31:51.697Z',
          grossAmount: 315,
          netAmount: 310.5585,
          installmentCount: 1,
          installmentNumber: 1,
          nsu: '42111111111222',
        },
      ]
    }

Data Dictionary

PropertyDescriptionRequired
idUnique and internal identifier of the receivable.
descriptionIf the acquiring bank returns any description within the receivable, it will appear here
currencyCodeCurrency ISO code of the sale, ie BRL, USD.
grossAmountGross amount of the receivable.
netAmountNet amount of the receivable
dateDate of the receivable
paymentIdAcquirer identification of the receivable
settlementStatusStatus of the receivable
Can be: PAID; SENT; REJECTED; EXPECTED
destinationAccount.receivingBankAccount which the receivable will be sent to
destinationAccount.agencyAgency number
destinationAccount.accountAccount number
cardFlagCredit card brand related to the receivable

3. Anticipations

Information on the amount taken in advance by the establishment.

The information presented here refers to both made and requested anticipation.

Can be retrieved from GET /acquirer-anticipations?item-id={id}

{
      "id": "71996b6d-8991-450c-8542-ae59069d1a9d",
      "itemId": "9aab8d24-c89b-4b0e-8974-7dd5614686e4",
      "description": "",
      "currencyCode": "BRL",
      "grossAmount": 313.28,
      "date": "2023-02-06T03:00:00.000Z",
      "status": "APPROVED",
      "netAmount": 308.66,
      "fee": 1.82,
      "feeAmount": 4.62
    }

Data Dictionary

PropertyDescriptionRequired
idUnique and internal identifier of the receivable.
descriptionIf the acquiring bank returns any description within the anticipation, it will appear here
currencyCodeCurrency ISO code of the sale, ie BRL, USD.
grossAmountGross amount of the anticipation
dateDate of the anticipation request
statusStatus of the anticipation.
Can be: SIMULATED; REQUESTED; CANCELLED;IN_ANALYSIS; APPROVED
netAmountNet amount of the anticipation
feePercentage of the fee charged from the anticipation
feeAmountFee amount charged from the anticipation

Status fields

Here are the possible status values depending on the used endpoint:

  • Sales (status):

    • APPROVED: the sale was completed
    • CANCELLED: the sale was cancelled by the customer (chargeback)
  • Receivables (settlementStatus):

    • 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.
  • Anticipation (status):

    • 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 acquiring bank transactions, check out our API reference.

Deprecated model

In case you are using our deprecated acquiring bank model, please refer to the deprecated model doc page.