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. |
Updated 3 months ago