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
Property | Description | Required |
---|---|---|
id | Unique and internal identifier of the sale. | |
description | Desciption of the sale | |
currencyCode | Currency ISO code of the sale, ie BRL, USD. | |
date | Posted date of the sale, formatted in ISO8601 | |
grossAmount | Gross amount of the sale | |
installmentCount | Number of installments from the sale | |
paymentMethod | Payment method. Can be: CARD, PIX | |
authorizationCode | Sale authorization code. | |
cardFlag | Credit card brand Can be: VISA ; MASTERCARD ; AMEX ; CABAL ; ELO ; OTHER | |
cardNumber | Credit card number | |
cardFundingSource | Type of payment. Can be: DEBIT, CREDIT, PIX. | |
nsu | Acquiring identification of the sale | |
status | Status of the sale. Can be: APPROVED ; CANCELLED | |
netAmount | Net amount of the sale | |
mdrFee | Percentage of the fee charged from the sale | |
mdrFeeAmount | Amount of the fee charged from the sale | |
installments.number | Installment's reference number | |
installments.netAmount | Installment's net amount | |
installments.grossAmount | Installment's gross amount | |
installments.receiptDate | Date 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
Property | Description | Required |
---|---|---|
id | Unique and internal identifier of the receivable. | |
description | If the acquiring bank returns any description within the receivable, it will appear here | |
currencyCode | Currency ISO code of the sale, ie BRL, USD. | |
grossAmount | Gross amount of the receivable. | |
netAmount | Net amount of the receivable | |
date | Date of the receivable | |
paymentId | Acquirer identification of the receivable | |
settlementStatus | Status of the receivable Can be: PAID ; SENT ; REJECTED ; EXPECTED | |
destinationAccount.receivingBank | Account which the receivable will be sent to | |
destinationAccount.agency | Agency number | |
destinationAccount.account | Account number | |
cardFlag | Credit 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
Property | Description | Required |
---|---|---|
id | Unique and internal identifier of the receivable. | |
description | If the acquiring bank returns any description within the anticipation, it will appear here | |
currencyCode | Currency ISO code of the sale, ie BRL, USD. | |
grossAmount | Gross amount of the anticipation | |
date | Date of the anticipation request | |
status | Status of the anticipation. Can be: SIMULATED ; REQUESTED ; CANCELLED ;IN_ANALYSIS ; APPROVED | |
netAmount | Net amount of the anticipation | |
fee | Percentage of the fee charged from the anticipation | |
feeAmount | Fee amount charged from the anticipation |
Status fields
Here are the possible status values depending on the used endpoint:
-
Sales (
status
):APPROVED
: the sale was completedCANCELLED
: the sale was cancelled by the customer (chargeback)
-
Receivables (
settlementStatus
):PAID
: it was received on the target bank accountSENT
: 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 institutionREQUESTED
: the anticipation has been requested to the institutionCANCELLED
: the anticipation has been cancelled by the userIN_ANALYSIS
: the anticipation is being reviewed to see if it should be accepted by the institutionAPPROVED
: the anticipation has been approvedAPI 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.
Updated 3 months ago