Check a Transaction Status

You can track the status of a payment using transaction status notifications or by querying the transaction directly via the Search API. This page explains both options, including request formats, response handling, and sandbox testing.

Notification Flow

PagSeguro automatically notifies your system whenever a transaction status changes.

PagSeguro notifies the merchant that a transaction status has changed.
The merchant requests the transaction details using the provided transaction code.
PagSeguro responds with the updated transaction information.

📘
When the transaction status is returned as COMPLETE, you can deliver the purchase to the end user.

Notification Example

PagSeguro will send a POST request to the notify URL provided when the transaction was created. The notification expects an HTTP 200 OK response. If not received, the notification will be retried every 10 minutes until success.

POST http://your-virtual-store.com/transaction-notification/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
transaction-code=1234567890
notification-type=transaction
test-mode=false

The notification includes the following parameters.

Parameter	Type	Description
transaction-code	String	Unique transaction identifier (same as `transaction_id`).
notification-type	String	Literal value `"transaction"`.
test-mode	Boolean	Indicates if the transaction was created in the sandbox environment.

Querying a Transaction

You can also check the status of a transaction using the Search API. To get the information from an specific transaction, you must use the Get Transaction by Code endpoint, providing the transaction code you received when creating the payment using the Create a Payment endpoint.

The following code block shows an example of response form the Get Transaction by Code endpoint, including all the information related to a transaction:

{
  "transaction-result": {
    "store-id": "string",
    "transactions": [
      {
        "transaction-code": "string",
        "order-id": "string",
        "order-description": "string",
        "status": "CANCELLED",
        "currency": "string",
        "amount": "string",
        "customer-mail": "string",
        "customer-country": "string",
        "notify-url": "string",
        "payment-country": "string",
        "payment-id": "string",
        "order-date": "2025-05-26T10:21:16.443Z",
        "payment-date": "2025-05-26T10:21:16.443Z",
        "last-status-change-date": "2025-05-26T10:21:16.443Z",
        "chargeback-date": "2025-05-26T10:21:16.443Z",
        "refundable": true,
        "refunds": [
          {
            "refund-id": "string",
            "refund-status": "string",
            "refund-amount": "string",
            "refund-date": "2025-05-26T10:21:16.443Z",
            "refund-processing-date": "2025-05-26T10:21:16.443Z",
            "refund-reference": "string"
          }
        ],
        "payment-methods": [],
        "payment-response": {
          "code": 0,
          "message": "string"
        },
        "payment": {
          "payment-method": {
            "type": "string",
            "sub-type": "string"
          },
          "bank": {
            "name": "string",
            "code": "string",
            "compe": "string",
            "account": {
              "number": "string",
              "branch": "string",
              "type": "string",
              "holder": {
                "name": "string",
                "document": {
                  "number": "string"
                }
              }
            }
          },
          "gateway": {
            "transaction-code": "string",
            "account": {
              "id": "string"
            }
          }
        }
      }
    ]
  },
  "metadata": {
    "found": "string",
    "page-results": 0,
    "current-page": 0,
    "total-pages": 0
  }
}