Search API

The Search API will return the details of the transaction processed by PagSeguro, according to the flow below:

How it Works

The Query API can be done in two ways, through the transaction code, where the API returns the specific data of the informed transaction, and through the query parameters, where a list of transactions corresponding to the parameters will be returned.

📘

To perform authentication, use the default authentication method defined in Authentication Section.

Search by Transaction Code

The query performed through transaction-code, sent by the Notify API (which uses the url informed in the integration.notification_url parameter).

📘

Individual transaction search URL for Production

https://api.boacompra.com/v3/transactions/{transaction_code}

Method: GET

🚧

Individual transaction search URL for Sandbox

https://api.sandbox.boacompra.com/v3/transactions/{transaction_code}

Method: GET

Search by Transaction Code request

ParametersDescriptionTypeValidationErrorsMandatory
transaction_codeUnique transaction identifierUuidLength 36[*]Yes.

Search by Transaction Code response

ParametersDescriptionType
codeUnique identifier of the transaction generated by PagSeguroUuid
statusTransaction Status [see more]String
refundableIndicates whether the transaction is refundable or notBoolean
integration.referenceOrder reference sent by MerchantString
integration.storeMerchant IdentifierInteger
integration.projectProject number submitted by MerchantInteger
integration.notification_urlNotification URL used by PagSeguro to notify Merchant about transaction status updatesString
charge.countryPayer's countryString
charge.typePayment type grouper used by the payer [*]String
charge.methodPayment method used by the payer [*]String
charge.credit_card.installmentsNumber of installments used by the payerInteger
charge.payment_responseObject returned when there is failure in the card processing by PagSeguro. This return only occurs for some payments, please consult your Account Manager for more information.Object
charge.payment_response.codeTransaction refusal reason codeInteger
charge.payment_response.messageMessage with details of the reason for rejecting the transactionString
checkout.languageLanguage used at checkout by the payerString
payer.emailPayer's EmailString
order.dateTransaction creation date in Coordinated Universal Time (UTC)UTC DateTime
order.currencyCurrency in which the order was sentString
order.itemsDue to current limitations, it will only return 1 item, even if several are sent through the API. At any time, you can return the items as shippedArray of Objects
order.items[].quantityItem quantityString
order.items[].descriptionItem descriptionString
order.items[].unit_priceItem unit priceString
refunds[]List of refunds registered for the transactionArray of Objects
refunds[].idRefund unique identifierInteger
refunds[].referenceRefund reference sent by merchantString
refunds[].statusRefund Status: REQUESTED, PROCESSING, PROCESSED, REJECTEDString
refunds[].amountRequested refund amountFloat
refunds[].dateRefund request date in Coordinated Universal Time (UTC)UTC DateTime
refunds[].processing_dateRefund processing date in Coordinated Universal Time (UTC)UTC DateTime

Example

{
   "code": "FCDA9C80-AF1F-4968-87AB-F71890CCF137",
   "status": "REFUNDED",
   "refundable": true,
   "integration": {
      "reference": "3ecb69fe75bf444889dc55c514a60494",
      "store": 10,
      "project": 1,
      "notification_url": "https://merchantwebsite.com/?notify"
   },
   "charge": {
      "country": "BR",
      "type": "CREDIT_CARD",
      "method": "MASTERCARD",
      "credit_card": {
         "installments": 1
      }
   },
   "checkout": {
      "language": "pt_BR"
   },
   "payer": {
      "email": "[email protected]"
   },
   "order": {
      "currency": "BRL",
      "date": "2021-06-01T14:52:08Z",
      "items": [
         {
            "quantity": 1,
            "description": "Product Example",
            "unit_price": 1
         }
      ]
   },
   "refunds": [
      {
         "id": 254593,
         "reference": "REFUND-REFERENCE-TEST",
         "status": "PROCESSED",
         "amount": 1,
         "date": "2021-06-01T14:54:22Z",
         "processing_date": "2021-06-01T03:00:00Z"
      }
   ]
}

Search by Period

In this query, the API returns all transactions processed by PagSeguro according to the period informed.

📘

Period transaction search URL for Production

https://api.boacompra.com/v3/transactions/{query}

Method: GET

🚧

Period transaction search URL for Sandbox

https://api.sandbox.boacompra.com/v3/transactions/{query}

Method: GET

Search by Period request

ParameterDescriptionTypeValidationErrorsMandatory
initial_transaction_dateTransaction start dateUTC DateTimeFormat: yyyy-mm-ddThh:mm:ssZ [*] Yes.
final_transaction_dateTransaction end dateUTC DateTimeFormat: yyyy-mm-ddThh:mm:ssZ[*]Yes.
pagePage numberIntegerMin: 1[*]No.
Default: 1
max_resultsMaximum number of results per pageIntegerMin: 1, Max: 10[*]No.
Default: 10

Search by Period response

The transaction query by period returns a list of transactions, which has the same contract as the transaction code query, in addition to the pagination data:

{
  "transactions": [
    {
      "code": "F2C09432-02DD-4FCF-B2DD-362850B63077",
      "status": "NOT-PAID",
      "refundable": false,
      "integration": {
        "reference": "bc874692de33485aa9f1f98c21f2bd09",
        "store": 10,
        "project": 1,
        "notification_url": "https://merchantwebsite.com/?notify"
      },
      "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "method": "MASTERCARD",
        "payment_response": {
          "code": 10000,
          "message": "Not authorized by acquirer"
        },
        "credit_card": {
          "installments": 1
        }
      },
      "checkout": {
        "language": "pt_BR"
      },
      "payer": {
        "email": "[email protected]"
      },
      "order": {
        "currency": "BRL",
        "date": "2021-06-01T14:58:27Z",
        "items": [
          {
            "quantity": 1,
            "description": "Product Example",
            "unit_price": 1
          }
        ]
      },
      "refunds": []
    },
    {
      "code": "FCDA9C80-AF1F-4968-87AB-F71890CCF137",
      "status": "REFUNDED",
      "refundable": true,
      "integration": {
        "reference": "3ecb69fe75bf444889dc55c514a60494",
        "store": 10,
        "project": 1,
        "notification_url": "https://merchantwebsite.com/?notify"
      },
      "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "method": "MASTERCARD",
        "credit_card": {
          "installments": 1
        }
      },
      "checkout": {
        "language": "pt_BR"
      },
      "payer": {
        "email": "[email protected]"
      },
      "order": {
        "date": "2021-06-01T14:52:08Z",
        "currency": "BRL",
        "items": [
          {
            "quantity": 1,
            "description": "Product Example",
            "unit_price": 1
          }
        ]
      },
      "refunds": [
        {
          "id": 254593,
          "reference": "REFUND-REFERENCE-TEST",
          "status": "PROCESSED",
          "amount": 1,
          "date": "2021-06-01T14:54:22Z",
          "processing_date": "2021-06-01T03:00:00Z"
        }
      ]
    },
    ...
  ],
  "pagination": {
    "total": 339,
    "results": 10,
    "page": 1,
    "pages": 34
  }
}

Transaction Status Description

Each transaction has a transaction.status that represent its current state, as well as any action you should take:

NameDescription
CANCELLEDTransaction was cancelled by PagSeguro
COMPLETE Transaction was paid and approved. Products should be delivered to the Customer.
CHARGEBACKAn approved transaction was cancelled by the Customer. Please consult your Account Manager for costs.
EXPIREDPayment date of transaction expired.
NOT-PAIDPayment confirmation of transaction was not received.
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.