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

Parameters	Description	Type	Validation	Errors	Mandatory
transaction_code	Unique transaction identifier	Uuid	Length 36	[*]	Yes.

Search by Transaction Code response

Parameters	Description	Type
code	Unique identifier of the transaction generated by PagSeguro	Uuid
status	Transaction Status [see more]	String
refundable	Indicates whether the transaction is refundable or not	Boolean
integration.reference	Order reference sent by Merchant	String
integration.store	Merchant Identifier	Integer
integration.project	Project number submitted by Merchant	Integer
integration.notification_url	Notification URL used by PagSeguro to notify Merchant about transaction status updates	String
charge.country	Payer's country	String
charge.type	Payment type grouper used by the payer [*]	String
charge.method	Payment method used by the payer [*]	String
charge.credit_card.installments	Number of installments used by the payer	Integer
charge.payment_response	Object 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.code	Transaction refusal reason code.	Integer
charge.payment_response.message	Message with details of the reason for rejecting the transaction	String
checkout.language	Language used at the checkout by the payer	String
payer.email	Payer's Email	String
order.date	Transaction creation date in Coordinated Universal Time (UTC)	UTC DateTime
order.currency	Currency in which the order was sent	String
order.items	Due 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 shipped	Array of Objects
order.items[].quantity	Item quantity	String
order.items[].description	Item description	String
order.items[].unit_price	Item unit price	String
refunds[]	List of refunds registered for the transaction	Array of Objects
refunds[].id	Refund unique identifier	Integer
refunds[].reference	Refund reference sent by merchant	String
refunds[].status	Refund Status: REQUESTED, PROCESSING, PROCESSED, REJECTED	String
refunds[].amount	Requested refund amount	Float
refunds[].date	Refund request date in Coordinated Universal Time (UTC)	UTC DateTime
refunds[].processing_date	Refund 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

Parameter	Description	Type	Validation	Errors	Mandatory
initial_transaction_date	Transaction start date	UTC DateTime	Format: yyyy-mm-ddThh:mm:ssZ	[*]	Yes.
final_transaction_date	Transaction end date	UTC DateTime	Format: yyyy-mm-ddThh:mm:ssZ	[*]	Yes.
page	Page number	Integer	Min: 1	[*]	No. Default: 1
max_results	Maximum number of results per page	Integer	Min: 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:

Name	Description
CANCELLED	Transaction was canceled by PagSeguro
COMPLETE	Transaction was paid and approved. Products should be delivered to the Customer.
CHARGEBACK	An approved transaction was canceled by the Customer. Please consult your Account Manager for costs.
EXPIRED	Payment date of the transaction expired.
NOT-PAID	Payment confirmation of the transaction was not received.
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 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.

Code	Message	Error details	Retry
10000	Not authorized by the 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	Payer tax id mismatched
10052	Unknown error - contact the processor
10053	Invalid Submerchant
10055	Insufficient information - Please try again
10058	3DS - Authentication failed
10065	Pre auth required

Search API

How it Works

📘

Search by Transaction Code

📘
Individual transaction search URL for Production

🚧
Individual transaction search URL for Sandbox

Accept Header for Transaction Search

🚧

Search by Transaction Code request

Search by Transaction Code response

Example

Search by Period

📘
Period transaction search URL for Production

🚧
Period transaction search URL for Sandbox

Search by Period request

Search by Period response

Transaction Status Description

Reason Code

How it Works

📘

Search by Transaction Code

📘Individual transaction search URL for Production

🚧Individual transaction search URL for Sandbox

Accept Header for Transaction Search

🚧

Search by Transaction Code request

Search by Transaction Code response

Example

Search by Period

📘Period transaction search URL for Production

🚧Period transaction search URL for Sandbox

Search by Period request

Search by Period response

Transaction Status Description

Reason Code

📘
Individual transaction search URL for Production

🚧
Individual transaction search URL for Sandbox

📘
Period transaction search URL for Production

🚧
Period transaction search URL for Sandbox