Documentation

Testing

Suggest Edits

To validate your integration, you may simulate transactions using specific values in our test mode environment.

🚧

Base URL for Sandbox

https://api.sandbox.international.pagseguro.com


Simulation of success scenarios

Create Transaction

To simulate a transaction creation you can send a request following the field specifications documented here.

Below are sample request payloads and responses:

Payload 
curl --location '<https://api.sandbox.international.pagseguro.com>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <value>' \
--header 'Idempotency-Key: <value>'
--data-raw '{
    "integration": {
        "reference": "REF-XXX-${{random}}",
        "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
        "language": "pt_BR"
    },
    "order": {
        "currency": "BRL",
        "items": [
            {
                "quantity": 1,
                "description": "Product description",
                "unit_price": 101.10
            }
        ]
    },
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "credit_card": {
            "raw": {
                "number":"4073020000000002",
                "cvc":"123",
                "expiration_month":"12",
                "expiration_year":"2028"
            },
            "holder_name": "jonh doe"
        }
    },
    "payer": {
        "email": "[email protected]",
        "ip": "192.0.2.146",
        "person": {
            "name": "Jonh Doe",
            "birth_date": "1970-01-01",
            "document": {
                "type": "CPF",
                "number": "29002996080"
            },            
            "phone": {
                "country_code": "55",
                "number": "44900000000"
            }
        }
    }
}'
Response 
{
    "code": "46c214d0-51b7-4b2c-b5b2-e8d0683070f9",
    "reference": "REF-XXX-1737137850",
    "amount": 101.1,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "created_at": "2025-01-17T18:17:29Z"
}

📘

Post creation

After creating your transactions, you can simulate their status changes. This will allow you to receive notifications about these status changes through the integration.notification_url provided during creation.

Simulator

PagSeguro offers a panel for properly simulating all statuses and the integration flow. See the section: Sandbox Environment

Search API

PagSeguro offers an API to retrieve transaction details, this is useful so that you can check the transaction current status. See the section: Search API


Error simulation with special values

Idempotency Errors

Request Already In Progress

To simulate this scenario in transactions in test mode, you must send the following idempotency key header:

Idempotency-Key: a5b6c9c8-e98c-40d5-aaf7-646c4771bcb
Payload 
curl --location 'https://api.sandbox.international.pagseguro.com' \
--header 'Authorization: <value>' \
--header 'Idempotency-Key: a5b6c9c8-e98c-40d5-aaf7-646c4771bcb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "integration": {
        "reference": "REF-XXX-1737140601",
        "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
        "language": "pt_BR"
    },
    "order": {
        "currency": "BRL",
        "items": [
            {
                "quantity": 1,
                "description": "Product description",
                "unit_price": 101.10
            }
        ]
    },
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "credit_card": {
            "raw": {
                "number":"4073020000000002",
                "cvc":"123",
                "expiration_month":"12",
                "expiration_year":"2028"
            },
            "holder_name": "jonh doe"
        }
    },
    "payer": {
        "email": "[email protected]",
        "ip": "192.0.2.146",
        "person": {
            "name": "Mr. Payer Full Name",
            "birth_date": "1970-01-01",
            "document": {
                "type": "CPF",
                "number": "29002996080"
            },            
            "phone": {
                "country_code": "55",
                "number": "44900000000"
            }
        }
    }
}'
Response 
{  
    "message": "request_already_in_progress"  
}

Request body mismatched with same idempotency key

To simulate this scenario, you must send the same idempotency key twice, with a different body in each request.

Response 
{  
    "errors": {  
        "message": "Request body mismatched with same idempotency key",  
        "location": "header.idempotency_key"  
    }  
}

Domain Errors

payer_buy_limit_exceed

To simulate this error in transactions in test mode you can use the following data set:

CountryDocument TypeDocument Number
BRCPF36898228072
COCC1112223334
COCEZ778899
PECEBC11122233
MXCURPdcba001122habcde12
PEDNI87654321b
CONIT2222222222
MXRFCzbc123456pl2
CLRUT12345678k
COTI01234567891
PERUC0123456789
Payload 
curl --location '<https://api.sandbox.international.pagseguro.com>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <value>' \
--header 'Idempotency-Key: <value>'
--data-raw '{
    "integration": {
        "reference": "REF-XXX-${{random}}",
        "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
        "language": "pt_BR"
    },
    "order": {
        "currency": "BRL",
        "items": [
            {
                "quantity": 1,
                "description": "Product description",
                "unit_price": 101.10
            }
        ]
    },
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "credit_card": {
            "raw": {
                "number":"4073020000000002",
                "cvc":"123",
                "expiration_month":"12",
                "expiration_year":"2028"
            },
            "holder_name": "jonh doe"
        }
    },
    "payer": {
        "email": "[email protected]",
        "ip": "192.0.2.146",
        "person": {
            "name": "Jonh Doe",
            "birth_date": "1970-01-01",
            "document": {
                "type": "CPF",
                "number": "36898228072"
            },            
            "phone": {
                "country_code": "55",
                "number": "44900000000"
            }
        }
    }
}'
Response 
{
     "error": "payer_buy_limit_exceed"
}

integration_reference_already_exists

To simulate this error in transactions in test mode you can send a reference more than once.

Payload 
curl --location '<https://api.sandbox.international.pagseguro.com>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <value>' \
--header 'Idempotency-Key: ef226ae8-05ff-47cf-91f1-6bd47fe37e0f'
--data-raw '{
    "integration": {
        "reference": "REF-XXX-123",
        "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
        "language": "pt_BR"
    },
    "order": {
        "currency": "BRL",
        "items": [
            {
                "quantity": 1,
                "description": "Product description",
                "unit_price": 101.10
            }
        ]
    },
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "credit_card": {
            "raw": {
                "number":"4073020000000002",
                "cvc":"123",
                "expiration_month":"12",
                "expiration_year":"2028"
            },
            "holder_name": "jonh doe"
        }
    },
    "payer": {
        "email": "[email protected]",
        "ip": "192.0.2.146",
        "person": {
            "name": "Jonh Doe",
            "birth_date": "1970-01-01",
            "document": {
                "type": "CPF",
                "number": "36898228072"
            },            
            "phone": {
                "country_code": "55",
                "number": "44900000000"
            }
        }
    }
}'
Response 
{
     "error": "integration_reference_already_exists"
}

🚧

Errors Unavailable - TestMode

Other domain errors not listed on this page are not yet available in the test mode. We are working to make your experience as assertive as possible.

Updated about 16 hours ago