--- updatedAt: 2026-08-25T10:07:22.000Z agentTools: projectIndex: https://developers.international.pagseguro.com/llms.txt --- # Search Transactions by Period Retrieves a list of transactions processed by PagSeguro within the specified date range. This endpoint allows merchants to filter transactions based on their creation date and supports pagination. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "PagSeguro International API", "description": "", "version": "1.0.0" }, "servers": [ { "url": "https://api.sandbox.international.pagseguro.com", "description": "Sandbox Server" } ], "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Basic Authentication using merchant_id and secret_key.\nAuthorization header must contain the word **Basic** followed by a **space** and a **base64-encoded string** with **merchant_id:secret_key**.\nFor example: `Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=`\n" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "location": { "type": "string", "description": "Location of the error." } } } } }, "description": "Schema for error responses." } }, "responses": { "BadRequest": { "description": "Bad Request - The request was malformed or contained invalid data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized - Authentication failed due to missing or invalid credentials." } } }, "tags": [ { "name": "Search API", "description": "Operations for searching transactions." } ], "paths": { "/v3/transactions": { "get": { "summary": "Search Transactions by Period", "operationId": "search-transactions-by-period", "description": "Retrieves a list of transactions processed by PagSeguro within the specified date range. \nThis endpoint allows merchants to filter transactions based on their creation date and supports pagination.\n", "tags": [ "Search API" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "in": "query", "name": "initial_transaction_date", "schema": { "type": "string", "format": "date-time" }, "required": true, "description": "Start date and time for filtering transactions, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z').\n" }, { "in": "query", "name": "final_transaction_date", "schema": { "type": "string", "format": "date-time" }, "required": true, "description": "End date and time for filtering transactions, in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss'Z').\n" }, { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number for pagination. Defaults to `1` if not provided.\n" }, { "in": "query", "name": "max_results", "schema": { "type": "integer", "minimum": 1, "maximum": 10 }, "description": "Maximum number of results per page. Must be between `1` and `10`. Defaults to `10` if not specified.\n" } ], "responses": { "200": { "description": "Transactions retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "description": "List of transactions matching the search criteria.", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Unique transaction identifier (UUID) assigned by PagSeguro." }, "status": { "type": "string", "description": "Current status of the transaction." }, "refundable": { "type": "boolean", "description": "Indicates whether the transaction is eligible for a refund." }, "integration": { "type": "object", "description": "Details related to the merchant's store and order reference.", "properties": { "reference": { "type": "string", "description": "Unique order reference assigned by the merchant." }, "store": { "type": "integer", "description": "Identifier of the merchant's store." }, "project": { "type": "integer", "description": "Project ID provided by the merchant during integration." }, "notification_url": { "type": "string", "description": "URL where PagSeguro sends transaction status updates." } } }, "charge": { "type": "object", "description": "Information about the payment method used for the transaction.", "properties": { "country": { "type": "string", "description": "Country where the payer is located." }, "type": { "type": "string", "description": "Payment type used by the payer." }, "method": { "type": "string", "description": "Specific payment method used for the transaction." }, "credit_card": { "type": "object", "properties": { "installments": { "type": "integer", "description": "Number of installments selected by the payer." }, "bin": { "type": "string", "description": "The first 6 digits of the credit card number." }, "last_four": { "type": "string", "description": "The last 4 digits of the credit card number." }, "expiration_date": { "type": "string", "description": "Credit card expiration date in YYYY-MM format." }, "card_on_file": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the stored card." } } } } }, "initiated_by": { "type": "string", "description": "Indicates who initiated the transaction." }, "recurrence": { "type": "object", "properties": { "id": { "type": "string", "description": "The recurrence ID." }, "type": { "type": "string", "description": "The type of recurrence." }, "scheduling": { "type": "string", "description": "The scheduling type for the recurrence (e.g., INITIAL, SUBSEQUENT)." } } }, "payment_response": { "type": "object", "description": "Contains details of a failed payment attempt due to issues with card processing. This object is only returned for certain transactions. Contact your Account Manager for more details.\n", "properties": { "code": { "type": "integer", "description": "Error code indicating the reason for transaction failure." }, "message": { "type": "string", "description": "Description of the error or failure reason." } } } } }, "checkout": { "type": "object", "description": "Details of the checkout process.", "properties": { "language": { "type": "string", "description": "Language used at the checkout by the payer." } } }, "payer": { "type": "object", "description": "Information about the customer who made the purchase.", "properties": { "email": { "type": "string", "description": "Payer's email address." } } }, "order": { "type": "object", "description": "Details of the order associated with the transaction.", "properties": { "date": { "type": "string", "format": "date-time", "description": "Date and time when the transaction was created (UTC format)." }, "currency": { "type": "string", "description": "Currency in which the order was processed (ISO 4217 code)." }, "items": { "type": "array", "description": "List of products or services included in the transaction.", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "Number of units purchased for this item." }, "description": { "type": "string", "description": "Description of the item." }, "unit_price": { "type": "number", "format": "float", "description": "Price per unit of the item." } } } } } }, "payment": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of payment." }, "method": { "type": "string", "description": "The payment method used." } } }, "refunds": { "type": "array", "description": "List of refunds associated with the transaction.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the refund request." }, "reference": { "type": "string", "description": "Refund reference assigned by the merchant." }, "status": { "type": "string", "description": "Current status of the refund request. Possible values: - `REQUESTED`: Refund has been requested. - `PROCESSING`: Refund is being processed. - `PROCESSED`: Refund has been successfully completed. - `REJECTED`: Refund request was denied.\n" }, "amount": { "type": "number", "format": "float", "description": "Amount requested for the refund." }, "date": { "type": "string", "format": "date-time", "description": "Date and time when the refund request was created (UTC format)." }, "processing_date": { "type": "string", "format": "date-time", "description": "Date and time when the refund was processed (UTC format)." } } } } } } }, "pagination": { "type": "object", "description": "Pagination details for the search results.", "properties": { "total": { "type": "integer", "description": "Total number of transactions matching the search criteria." }, "results": { "type": "integer", "description": "Number of results per page." }, "page": { "type": "integer", "description": "Current page number." }, "pages": { "type": "integer", "description": "Total number of pages available." } } } } }, "examples": { "ExampleResponse": { "summary": "Example of a paginated transaction search response", "value": { "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": "payer@example.com" }, "order": { "currency": "BRL", "date": "2021-06-01T14:58:27Z", "items": [ { "quantity": 1, "description": "ProductExample", "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": "payer@example.com" }, "order": { "date": "2021-06-01T14:52:08Z", "currency": "BRL", "items": [ { "quantity": 1, "description": "ProductExample", "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 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```