Testing PIX Payment Integration in Brazilian E-Commerce Apps

Region Focus: This guide includes examples and patterns specifically relevant to Brazil-based development teams and applications.

Modern web applications require thorough testing strategies that account for regional requirements, diverse user bases, and complex technical architectures. This guide provides actionable Playwright patterns for your specific context.

Introduction

Automate Pix QR code generation, CPF validation, and instant payment confirmation flows for Brazilian e-commerce with Playwright. This guide covers the essential patterns, configurations, and strategies to handle this scenario reliably in your Playwright test suite.

Understanding the nuances of this topic allows your team to ship with confidence, reduce flakiness, and maintain high-quality automation across different environments.

Architecture Overview

graph TD
    Cart["Carrinho"] --> Pix["PIX Selecionado"]
    Pix --> BACEN["BACEN API Mock"]
    BACEN --> QR["QR Code Gerado"]
    QR --> Confirm["Pagamento Confirmado"]

This structure ensures clean separation of concerns and maintainable test code.

Implementation Flow

sequenceDiagram
    participant Test as Playwright Test
    participant App as Application
    participant API as Backend / Mock API

    Test->>App: Navigate and interact
    App->>API: Trigger API call
    API-->>App: Return response
    App-->>Test: UI state updated
    Test->>Test: Assert outcome

Step-by-Step Guide

Follow this implementation to set up the pattern in your test suite.

1. Core Implementation

test('PIX QR code is generated for Brazilian checkout', async ({ page }) => {
  await page.goto('/checkout/pix');
  await page.getByLabel('CPF').fill('123.456.789-09');
  await page.getByRole('button', { name: 'Gerar QR Code PIX' }).click();
  await expect(page.getByTestId('pix-qr-code')).toBeVisible();
  await expect(page.getByTestId('pix-copy-code')).toBeVisible();
});

2. Run and Verify

# Run this specific test file
npx playwright test --grep "Testing PIX Payment"

Run with UI mode for debugging
npx playwright test --ui

Run across all browsers
npx playwright test --project=chromium --project=firefox --project=webkit

3. View Test Report

npx playwright show-report

Reference Table

Best Practices

Common Pitfalls

Frequently Asked Questions

How to mock PIX payment confirmation in Playwright?

Intercept the webhook endpoint your app uses for PIX confirmation and return a mock paid status.

How to test PIX QR code expiration?

Mock a short expiry time and verify that the UI shows an expiration warning and refresh button.

Can Playwright validate CPF numbers?

Yes, test both valid and invalid CPF numbers and verify the form shows correct validation messages.

How to test PIX refunds (devolução)?

Mock the PIX devolution API and verify the transaction status updates to DEVOLUCAO_PROCESSADA.

Does Playwright work with MercadoPago PIX flows?

Yes, mock MercadoPago's API and test your checkout integration with their PIX payment method.

Summary

Automate Pix QR code generation, CPF validation, and instant payment confirmation flows for Brazilian e-commerce with Playwright. By following these patterns, your team can build a reliable, maintainable automation suite that works across environments and handles edge cases gracefully.

Related Articles