Testing and Troubleshooting

Use this page before launch and whenever browser payment behavior looks inconsistent.

For the sandbox test cards, documents, and amounts that drive each outcome (approved, declined, 3DS challenge/frictionless, tokenization, and Pix/Boleto settlement), see Test Data.

Test checklist

confirm the browser uses the sandbox public key
confirm the backend uses the sandbox secret token
verify the backend returns the transaction payload intact
verify webhook delivery before trusting browser state
reconcile any interrupted 3DS attempt

Example backend request

{
  "external_ref": "order_2001",
  "amount": 2490,
  "currency": "BRL",
  "method": "credit_card",
  "token": "pgct_token_from_browser"
}

Example backend response

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b43-7c9a-8d3e-1a2b3c4d5e70",
    "status": "pending"
  }
}

Common error

{
  "type": "https://api.pagou.ai/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data.",
  "errors": [
    {
      "field": "token",
      "message": "Token is required for credit card payments",
      "code": "invalid_type"
    }
  ]
}

Fix: if the backend cannot see a valid Payment Element token, stop and verify the browser integration before changing order logic or webhook handling.

3D Secure

Migration from WebSDK

Start with Payment Element

Build a Card Checkout

Launch and Migrate

Test checklist

Example backend request

Example backend response

Common error

​Test checklist

​Example backend request

​Example backend response

​Common error

Test checklist

Example backend request

Example backend response

Common error