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

🚧
Search API URL for Sandbox
https://api.sandbox.boacompra.com/transactions/{transactionCode}
Method: GET

Accept Header for Transaction Search

🚧
Please note that the Transaction Search API will only receive the following Accept header value:
application/vnd.boacompra.com.v1+json; charset=UTF-8

Input Parameters

Parameter	Mandatory?	Type	Description
initial-order-date	Optional	Timestamp	Initial 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-date	Optional	Timestamp	Final 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-date	Optional	Timestamp	Initial 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-date	Optional	Timestamp	Final 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-date	Optional	Timestamp	Initial 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-date	Optional	Timestamp	Final 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
status	Optional	String	Transactions status to be filtered. Values: `CANCELLED`, `COMPLETE`, `CHARGEBACK`, `EXPIRED`, `NOT-PAID`, `PENDING`, `REFUNDED`, `UNDER-REVIEW`
page	Optional	Int	If the search result is presented in more than one page, it’s possible to use this parameter to navigate among the pages.
max-page-results	Optional	Int	Number of results per page. Default value and maximum accepted is 10.

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

https://api.boacompra.com/transactions/{transactionCode} - Returns the information of a specific transaction
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

Name	Description
CANCELLED	Transaction was cancelled by PagSeguro
COMPLETE	Transaction was paid and approved. Products should be delivered to the End User
CHARGEBACK	An approved transaction was cancelled by the End User. Please consult your Account Manager for costs.
EXPIRED	Payment date of transaction expired
NOT-PAID	Payment confirmation of transaction was not receive.
PENDING	Transaction was created
REFUNDED	A partial or full refund was requested and accepted for the transaction
UNDER-REVIEW	Transaction 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

Parameter	Description
transactions-result Object
transaction-code	PagSeguro unique identifier for the transaction
order-id	Merchant unique identifier for the transaction
order-description	Description provided by the Merchant when the checkout was created
status	Transaction status
currency	Currency related to the amount of the transaction
amount	Amount of the transaction
customer-mail	Customer e-mail used in PagSeguro checkout
customer-country	Country in which the customer IP was tracked
notify-url	URL that PagSeguro notified the Merchant
payment-country	Country where the payment was made
payment-id	PagSeguro payment identifier (for more information, check the Integration Guide)
order-date	Date that the checkout was created
payment-date	Date that the customer paid the order
last-status-change-date	Date that the last status change occurred
chargeback-date	DEPRECATED - Return is null
refunds Object
refund-id	PagSeguro unique identifier for a refund
refund-status	Status of the refund
refund-amount	Amount to be refunded
refund-date	Date that the refund was requested
refund-processing-date	Date that the refund was paid
refund-reference	Merchant refund identifier
payment-methods Object
code	Tokenized card code
date-created	Tokenized card creation date
credit-cart Object
brand	Brand of the credit card
masked-number	The last 4 digits of the credit card
expiration-date	Expiration date of the credit card
payment-response Object	Returning only when the transaction is “BR”, with “CREDIT CARD” and status “NOT PAID” *[]**
code	Credit card rejection reason code
message	Detailed 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"
        }
    ]
}

Reason Code

Reason Codes are used to identify the reason for rejecting a payment made with cards, it can be credit or debit. These codes are typically only used when a card payment cannot be processed because of reasons like expiration date, incorrect CVV code, or the card is not on file.

Code	Message
10000	Not authorized by acquirer
10001	Contact your card central
10002	Expired card - do not try again
10003	Not authorized. Contact your card central
10004	Invalid requirement
10005	Invalid transaction
10007	Check the card data
10008	Invalid installment - do not try again
10009	Invalid cvv
10010	Canceled transaction
10011	Exceeded date for operation
10012	Transaction value not allowed. Do not try again
10013	Capture failure
10014	Cancellation failed
10015	System unavailable
10017	Transaction not allowed. Do not try again
10019	Re-enter transaction
10020	Database error
10021	Non-registered or request out of time
10022	Number of tries exceeded
10023	Integrator error
10024	Time out
10025	Incorrect validity date
10026	Suspicious card
10027	Fraudulent card
10029	Canceled card
10030	Transaction already exists
10031	Card not configured
10032	Undo transaction
10033	Not authorized
10034	Transaction already canceled
10037	Contact your card issuer. Do not try again
10040	Card does not allow international transaction
10041	Invalid data
10042	Invalid token
10043	Error running operation
10044	Disabled purchaser
10045	The company cannot complete this transaction. Contact our support
10046	Transaction amount exceeded - try again later
10047	Rejected transaction. Contact your card issuer
10048	Insufficient funds
10049	Invalid Card
10050	3-D Secure required
10051	Invalid document correlation