Search API

Transaction Search API

Retrieve information about transactions. The API can return information about one specific transaction or a list of transactions, based on the search criteria requested via API.

🚧

If the transactionCode is not sent, a date range search is mandatory. The maximum date range search is 30 days.

📘

Search API URL for Production

https://api.boacompra.com/transactions/{transactionCode}

Method: GET

Input Parameters

ParameterMandatory?TypeDescription
initial-order-dateOptionalTimestampInitial date, based when the order was created, to be searched. Only transactions created after the date sent in this parameter will be returned. If a transactionCode is not sent, a date range search is mandatory.
Format: YYYY-MM-DDThh:mm:ss.sTZD
Example: 2015-06-09T14:00:00.000-03:00
final-order-dateOptionalTimestampFinal date, based when the order was created, to be searched. Only transactions created before this date will be returned. If an initial-order-date is sent and the final-order-date is left in blank, the current date will be considered unless it is greater than 30 days. In this case, will be considered a 30-day search.
If a final-order-date is sent, the parameter initial-order-date is required.
Format: YYYY-MM-DDThh:mm:ss.sTZD
Example: 2015-06-10T14:00:00.000-03:00
initial-payment-dateOptionalTimestampInitial date, based when the order was payed, to be searched. Only transactions payed after the date sent in this parameter will be returned.
If a transactionCode is not sent, a date range search is mandatory.
Format: YYYY-MM-DDThh:mm:ss.sTZD
Example: 2015-06-09T14:00:00.000-03:00
final-payment-dateOptionalTimestampFinal date, based when the order was created, to be searched. Only transactions payed before this dates will be returned. If an initial-payment-date is sent and the final-payment-date is left in blank, the current date will be considered unless it is greater than 30 days. In this case, will be considered a 30-day search.
If a final-payment-date is sent, the parameter initial-payment-date becomes required.
Format: YYYY-MM-DDThh:mm:ss.sTZD
Example: 2015-06-10T14:00:00.000-03:00
initial-last-status-change-dateOptionalTimestampInitial date, based on the last status change, to be searched. Only transactions with changes on their status after the date sent in this parameter will be returned.
If a transactionCode is not sent, a date range search is mandatory.
Format: YYYY-MM-DDThh:mm:ss.sTZD
final-last-status-change-dateOptionalTimestampFinal date, based on the last status change, to be searched. Only transactions with changes on their status before this dates will be returned. If the initial-last-status-change-date is sent and the final-last-status-change-date is left in blank, the current date will be considered unless it is greater than 30 days. In this case, will be considered a 30-day search.
If final-last-status-change-date is sent, the parameter initial-last-status-change-date becomes required.
Format: YYYY-MM-DDThh:mm:ss.sTZD
Example: 2015-06-10T14:00:00.000-03:00
statusOptionalStringTransactions status to be filtered.
Values: CANCELLED, COMPLETE, CHARGEBACK, EXPIRED, NOT-PAID, PENDING, REFUNDED, UNDER-REVIEW
pageOptionalIntIf the search result is presented in more than one page, it’s possible to use this parameter to navigate among the pages.
max-page-resultsOptionalIntNumber of results per page. Default value and maximum accepted is 10.

In the sequence, a few examples of requests are available:

  1. https://api.boacompra.com/transactions/{transactionCode} - Returns the information of a specific transaction

  2. https://api.boacompra.com/transactions?initial-order-date=2015-06-10T14:00:00.000-03:00&final-order-date=2015-06-20T14:00:00.000-03:00 - Returns the first ten transactions created on the informed period

Success Response

The response contains metadata information with the number of transactions returned for the request and an array of transaction’s object with the information of each transaction.
HTTP Status Code: 200

Transaction Status Description

NameDescription
CANCELLEDTransaction was cancelled by PagSeguro
COMPLETETransaction was paid and approved. Products should be delivered to the End User
CHARGEBACKAn approved transaction was cancelled by the End User. Please consult your Account Manager for costs.
EXPIREDPayment date of transaction expired
NOT-PAIDPayment confirmation of transaction was not receive.
PENDINGTransaction was created
REFUNDEDA partial or full refund was requested and accepted for the transaction
UNDER-REVIEWTransaction is under review by PagSeguro Analysis team. It will be approved or cancelled based on the analysis.

Response example

{
    "transaction-result": {
        "store-id": "10",
        "transactions": [
            {
                "transaction-code": "87990145",
                "order-id": " 1500397602",
                "order-description": "Purchase Test",
                "status": "REFUNDED",
                "currency": "BRL",
                "amount": "10.00",
                "customer-email": "[email protected]",
                "customer-country": "BR",
                "notify-url": "https://merchant.store.com/consume_notifications.php",
                "payment-country": "BR",
                "payment-id": "3",
                "payment-name": "mastercard",
                "order-date": "2017-07-18T14:18:44-03:00",
                "payment-date": "2017-07-18T14:21:02-03:00",
                "last-status-change-date": "2017-07-18T14:30:10-03:00",
                "chargeback-date": null,
                "refundable": false,
                "refunds": [
                    {
                        "refund-id": "32926",
                        "refund-status": "PROCESSED",
                        "refund-amount": "10.00",
                        "refund-date": "2017-07-18T14:21:47-03:00",
                        "refund-processing-date": "2017-07-18T00:00:00-03:00",
                        "refund-reference": "BC-34134"
                    }
                ],
                "payment-methods": [
                    {
                        "code": "123E4567E89B12D3A456426655440000",
                        "date-created": "2018-04-11T11:31:11.571488493-03:00",
                        "credit-card": {
                            "brand": "visa",
                            "masked-number": "************0002",
                            "expiration-date": "2026-12"
                        }
                    }
                ],
                "payment-response": {
                    "code": 20000,
                    "message": "Success"
                }
            }
        ]
    },
    "metadata": {
        "found": "1",
        "page-results": 1,
        "current-page": 1,
        "total-pages": 1
    }
}

Response body contents

ParameterDescription
transactions-result Object
transaction-codePagSeguro unique identifier for the transaction
order-idMerchant unique identifier for the transaction
order-descriptionDescription provided by the Merchant when the checkout was created
statusTransaction status
currencyCurrency related to the amount of the transaction
amountAmount of the transaction
customer-mailCustomer e-mail used in PagSeguro checkout
customer-countryCountry in which the customer IP was tracked
notify-urlURL that PagSeguro notified the Merchant
payment-countryCountry where the payment was made
payment-idPagSeguro payment identifier (for more information, check the Integration Guide)
order-dateDate that the checkout was created
payment-dateDate that the customer paid the order
last-status-change-dateDate that the last status change occurred
chargeback-dateDEPRECATED - Return is null
refunds Object
refund-idPagSeguro unique identifier for a refund
refund-statusStatus of the refund
refund-amountAmount to be refunded
refund-dateDate that the refund was requested
refund-processing-dateDate that the refund was paid
refund-referenceMerchant refund identifier
payment-methods Object
codeTokenized card code
date-createdTokenized card creation date
credit-cart Object
brandBrand of the credit card
masked-numberThe last 4 digits of the credit card
expiration-dateExpiration date of the credit card
payment-response Object Returning only when the transaction is “BR”, with “CREDIT CARD” and status “NOT PAID”
codeCredit card rejection reason code
messageDetailed credit card reason code message

Response with error

In case of errors in the request, expect a HTTP Status Code different from 200. The body response also contains an error object with the description and an error code, like the following example. Error Code list here.

{
    "errors": [
        {
            "code": "17078",
            "description": "currency_not_accepted"
        }
    ]
}