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 4 months ago

Did this page help you?