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 is 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.international.pagseguro.com/v3/transactions/{transaction_code}

Method: GET

🚧

Individual transaction search URL for Sandbox

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

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

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 a 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 code.Integer
charge.payment_response.messageMessage with details of the reason for rejecting the transactionString
checkout.languageLanguage used at the 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.international.pagseguro.com/v3/transactions/{query}

Method: GET

🚧

Period transaction search URL for Sandbox

https://api.sandbox.international.pagseguro.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 status that represents the transaction's current state. It also informs any action you should take:

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

Reason Code

Reason Codes are used to identify the decline cause for rejecting payment. These codes are typically used for cards, but may also happen on other payment methods, like EFT.

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