Get Transactions

The Transaction Requests endpoint allows retrieving transaction data. This endpoint is particularly useful when you need to validate the status of one or more transactions or locate a specific one. Its usage is straightforward, as it does not require a Request Body. There are two main use cases:

To retrieve a single transaction using transactionId.
To retrieve multiple transactions using transactionOrderId and date filters.

Let’s explore these functionalities in more detail:

1. Get a Single Transaction using transactionId

This operation aims to fetch details about a specific transaction by using transactionId as a Path Variable in the following endpoint:

Request Endpoint

GET {{baseUrl}}/partners-int/accounts/transactions/pix/:transactionId

Path Parameters

As previously mentioned, this endpoint does not use a request body. Instead, it requires the transactionId as a Path Variable, as outlined below:

Parameter	Format	Description
transactionId	string (UUID)	Identifier of the transaction to find

By executing this endpoint, you can view the details of a specific transaction.

2. Get Multiple Transactions using transactionOrderId and Date Filters

This operation is intended to list all transactions associated with an orderId and within a specified date range. To perform this query, you will use Query Parameters.

Request Endpoint

GET {{baseUrl}}/partners-int/accounts/transactions/pix

Query Parameters

Similar to the previous endpoint, this one does not require a request body. Instead, the filters are applied via Query Parameters. These parameters are as follows:

Parameter	Type	Description
`startDate`	string	The start date for filtering transactions (in ISO 8601 format, e.g., `2023-01-01T00:00:00Z`).
`endDate`	string	The end date for filtering transactions (in ISO 8601 format, e.g., `2023-12-31T23:59:59Z`).
`dataset.limit`	number	Maximum number of transactions to return in the response.
`dataset.offset`	number	Offset for pagination, indicating the starting point for the dataset.
`transactionOrderId`	string	Identifier for the transaction order to filter the results.

Possible Responses

The response for both cases is generally similar. However, the response for Retrieve a Single Transaction includes more detailed information about the transaction, whereas the response for Retrieve Multiple Transactions provides a summarized version to handle a larger volume of data. Let’s take a closer look at these responses.

{
    "statusCode": "Done",
    "data": {
        "transaction": {
            "id": "<string>",
            "externalResourceId": "<string>",
            "orderId": "<string>",
            "orderDescription": "<string>",
            "date": "<string>",
            "stateRegisteredDate": "<string>",
            "stateCompletedDate": "<string>",
            "stateCancelledDate": "<string>",
            "stateRefundDate": "<string>",
            "stateReversedDate": "<string>",
            "stateErrorDate": "<string>",
            "stateErrorCause": "<string>",
            "type": "<string>",
            "paymentType": "<string>",
            "category": "<string>",
            "amount": "<string>",
            "refundsAmount": "<string>",
            "currency": "<string>",
            "state": "<string>",
            "charges": "<string>",
            "chargesObject": {
                "costValue": "<string>",
                "rateValue": "<string>",
                "rate": "<string>"
            },
            "receiptUrl": "<string>",
            "receiptDate": "<string>",
            "receiptVoucher": "<string>",
            "receiptAmount": "<string>",
            "metadata": {},
            "payer": {
                "name": "<string>",
                "taxNumber": "<string>",
                "bankCode": "<string>",
                "bankName": "<string>",
                "accountAgency": "<string>",
                "accountNumber": "<string>",
                "accountDigit": "<string>"
            },
            "customerName": "<string>",
            "accountName": "<string>",
            "accountNumber": "<string>",
            "brandInfo": {
                "name": "<string>",
                "logo": "<string>"
            },
            "partnerInfo": {
                "name": "<string>",
                "logo": "<string>"
            },
            "account": {
                "accountNumber": "<string>",
                "accountType": "<string>"
            }
        },
        "payment": {
            "value": {
                "original": "<string>"
            },
            "qrCode": "<string>",
            "qrCodeLocation": "<string>",
            "payer": {
                "name": "<string>",
                "cpf": "<string>",
                "cnpj": "<string>"
            }
        },
        "webhook": {
            "url": "<string>",
            "customHeaderN": "<string>",
            "customHeaderValue": "<string>",
            "deliveryStatus": "<string>",
            "deliveryTime": "<string>"
        }
    }
}

{
    "statusCode": "Done",
    "data": {
        "limit": 50,
        "offset": 0,
        "total": 1,
        "items": [
            {
                "transaction": {
                    "id": "<string>",
                    "orderId": "<string>",
                    "orderDescription": "<string>",
                    "date": "<string>",
                    "stateRegisteredDate": "<string>",
                    "stateCompletedDate": "<string>",
                    "stateCancelledDate": "<string>",
                    "stateRefundDate": "<string>",
                    "stateReversedDate": "<string>",
                    "stateErrorDate": "<string>",
                    "stateErrorCause": "<string>",
                    "type": "<string>",
                    "paymentType": "<string>",
                    "amount": "<string>",
                    "refundsAmount": "<string>",
                    "currency": "<string>",
                    "state": "<string>",
                    "charges": "<string>",
                    "chargesObject": {
                        "costValue": "<string>",
                        "rateValue": "<string>",
                        "rate": "<string>"
                    },
                    "receiptVoucher": "<string>",
                    "payer": {
                        "name": "<string>",
                        "taxNumber": "<string>"
                    },
                    "brandInfo": {
                        "name": "<string>",
                        "logo": "<string>"
                    },
                    "account": {
                        "accountNumber": "<string>",
                        "accountType": "<string>"
                    }
                },
                "payment": {
                    "payer": {
                        "name": "<string>",
                        "cpf": "<string>",
                        "cnpj": "<string>"
                    }
                },
                "webhook": {
                    "deliveryStatus": "<string>"
                }
            }
        ]
    }
}

{
  "statusCode": "<string>",
  "error": {
    "name": "<string>",
    "message": "<string>",
    "details": [
      {
        "path": "<string>",
        "code": "<string>",
        "message": "<string>",
        "info": "<object>"
      },
      {
        "path": "<string>",
        "code": "<string>",
        "message": "<string>",
        "info": "<object>"
      }
    ]
  }
}

{
  "statusCode": "<string>",
  "error": {
    "name": "<string>",
    "message": "<string>",
    "details": {
      "reason": "<string>"
    }
  }
}

{
  "statusCode": "<string>",
  "error": {
    "name": "<string>",
    "message": "<string>"
  }
}

Sucess Response Fields

The responses for both cases contain a significant amount of data. To interpret them correctly, it is important to understand the meaning of each field. Refer to the table below for detailed field descriptions:

Field	Type	Description
`statusCode`	string	The status of the transaction request (e.g., "Done").
`data`	object	Contains detailed information about the transaction, payment, and webhook.
`data.transaction`	object	Information about the specific transaction.
`transaction.id`	string (UUID)	Unique identifier of the transaction.
`transaction.externalResourceId`	string (UUID)	External resource identifier for the transaction.
`transaction.orderId`	string	Identifier of the order associated with the transaction.
`transaction.orderDescription`	string	Description of the order associated with the transaction.
`transaction.date`	string (ISO 8601)	Timestamp when the transaction was created.
`transaction.stateRegisteredDate`	string (ISO 8601)	Timestamp when the transaction state was registered.
`transaction.stateCompletedDate`	string (ISO 8601)	Timestamp when the transaction state was completed.
`transaction.stateCancelledDate`	string (ISO 8601)	Timestamp when the transaction was canceled (if applicable).
`transaction.stateRefundDate`	string (ISO 8601)	Timestamp when the transaction was refunded (if applicable).
`transaction.stateReversedDate`	string (ISO 8601)	Timestamp when the transaction was reversed (if applicable).
`transaction.stateErrorDate`	string (ISO 8601)	Timestamp when an error occurred in the transaction (if applicable).
`transaction.stateErrorCause`	string	Description of the error cause (if applicable).
`transaction.type`	string	Type of transaction (e.g., "Credit").
`transaction.paymentType`	string	Type of payment method used (e.g., "PIX").
`transaction.category`	string	Category of the transaction (e.g., "PartnerSales").
`transaction.amount`	string	Total amount of the transaction.
`transaction.refundsAmount`	string	Amount refunded for the transaction (if applicable).
`transaction.currency`	string	Currency used in the transaction (e.g., "BRL").
`transaction.state`	string	Current state of the transaction (e.g., "Completed").
`transaction.charges`	string	Charges applied to the transaction.
`transaction.chargesObject`	object	Details of the transaction charges.
`chargesObject.costValue`	string	Base cost of the transaction.
`chargesObject.rateValue`	string	Rate value applied to the transaction.
`chargesObject.rate`	string	Rate percentage applied to the transaction.
`transaction.receiptUrl`	string (URL)	URL to download the receipt for the transaction.
`transaction.receiptDate`	string (ISO 8601)	Timestamp when the receipt was issued.
`transaction.receiptVoucher`	string	Voucher code for the receipt.
`transaction.receiptAmount`	string	Amount displayed on the receipt.
`transaction.metadata`	object	Additional metadata related to the transaction.
`transaction.payer`	object	Information about the payer of the transaction.
`payer.name`	string	Name of the payer.
`payer.taxNumber`	string	Tax identification number of the payer.
`payer.bankCode`	string	Bank code of the payer's bank.
`payer.bankName`	string	Name of the payer's bank.
`payer.accountAgency`	string	Agency number of the payer's bank account.
`payer.accountNumber`	string	Account number of the payer.
`payer.accountDigit`	string	Check digit of the payer's account.
`transaction.customerName`	string	Name of the customer associated with the transaction.
`transaction.accountName`	string	Name of the account associated with the transaction.
`transaction.accountNumber`	string	Number of the account associated with the transaction.
`transaction.brandInfo`	object	Brand information related to the transaction.
`brandInfo.name`	string	Name of the brand.
`brandInfo.logo`	string (URL)	URL of the brand's logo.
`transaction.partnerInfo`	object	Partner information related to the transaction.
`partnerInfo.name`	string	Name of the partner.
`partnerInfo.logo`	string (URL)	URL of the partner's logo.
`transaction.account`	object	Details of the account associated with the transaction.
`account.accountNumber`	string	Number of the account.
`account.accountType`	string	Type of account (e.g., "Partner").
`data.payment`	object	Details of the payment associated with the transaction.
`payment.value`	object	Payment value details.
`value.original`	string	Original amount of the payment.
`payment.qrCode`	string	QR code associated with the payment.
`payment.qrCodeLocation`	string (URL)	URL to view the QR code for the payment.
`payment.payer`	object	Payer information for the payment.
`payer.name`	string	Name of the payer.
`payer.cpf`	string	CPF of the payer (if applicable).
`payer.cnpj`	string	CNPJ of the payer (if applicable).
`data.webhook`	object	Webhook details related to the transaction.
`webhook.url`	string (URL)	URL of the webhook endpoint.
`webhook.customHeaderName`	string	Custom header name sent in the webhook request.
`webhook.customHeaderValue`	string	Custom header value sent in the webhook request.
`webhook.deliveryStatus`	string	Status of the webhook delivery (e.g., "Sent").
`webhook.deliveryTime`	string (ISO 8601)	Timestamp of the webhook delivery.