Scope and Requirements

APIs covered, mTLS/OAuth 2.0 requirements, and applicable BACEN regulations.

APIs Covered in this Playbook

Resource	Endpoint	Description
Immediate Charge	`/cob e /cob/{txid}`	CRUD for immediate charges with QR Code
Due-Date Charge	`/cobv e /cobv/{txid}`	Charges with due date (boleto PIX)
Received PIX	`/pix e /pix/{e2eid}`	Query and refund of received PIX payments
Webhook	`/webhook/{chave}`	Push notification configuration
Location (Payload)	`/loc e /loc/{id}`	QR Code payload management
Automatic PIX (Rec)	`/rec e /rec/{idRec}`	Recurring payment management (automatic debit)
CobV Batch	`/lotecobv/{id}`	Creation and management of due-date charge batches
Recurring Request	`/solicrec/{idSolicRec}`	Recurring authorization confirmation

PIX API v2.9.0 — Security Requirements

• mTLS required: ICP-Brasil certificate (production) or PSP-issued (staging)
• OAuth 2.0 Client Credentials: Specific scopes per resource (cob.read, cob.write, pix.read)
• RFC 8705: Token bound to TLS certificate — prevents token use on another connection

Applicable Regulations

Regulation	Scope of Application
BCB Resolution No. 1/2020	Base regulation for the PIX arrangement
PIX Security Manual	Technical security requirements
PIX API Manual	Technical API specifications
Joint Resolution No. 6/2023	Sharing of fraud indicators
BCB Circular No. 3,978/2020	Anti-money laundering prevention
LGPD (Law 13,709/2018)	Personal data protection

Maintain a mapping between each regulation and the corresponding test cases to facilitate audits.

Functional Tests

Test case matrix for /cob, /cobv, /pix and /webhook with P0/P1 prioritization.

Immediate Charge (/cob)

Method	Priority	Test Case	Validations
`POST /cob/{txid}`	P0	Create charge with fixed amount	`HTTP 201, txid, location, QR Code`
`POST /cob/{txid}`	P0	Create Pix Withdrawal charge	`modalidadeAlteracao, retirada`
`POST /cob/{txid}`	P1	Create Pix Change charge	`valor.original, valor.troco`
`GET /cob/{txid}`	P0	Query existing charge	`status, calendario, valor, chave`
`PATCH /cob/{txid}`	P1	Revise charge (change status)	`status REMOVIDA_PELO_USUARIO`
`GET /cob`	P1	List charges with pagination	`parametros.paginacao, filtros`

Received PIX (/pix)

Method	Priority	Test Case	Validations
`GET /pix/{e2eid}`	P0	Query PIX by endToEndId	`e2eid, txid, valor, horario`
`PUT /pix/{e2eid}/devolucao/{id}`	P0	Request refund (MD06)	`rtrId, status, motivo`
`GET /pix/{e2eid}/devolucao/{id}`	P1	Query refund status	`status, horario, motivo`
`GET /pix`	P1	List PIX by period	`inicio, fim, paginacao`

Prioritize P0 for the first test cycle. P1 can be implemented in parallel or in the second iteration.

Security Tests

OWASP API Top 10, OAuth/mTLS validation, and injection vectors for financial APIs.

OWASP API Security Top 10

ID	Vulnerability	Specific Tests
API1:2023	Broken Object Level Authorization	Try to access /cob/{txid} from another user; Manipulate e2eid to query another user's PIX
API2:2023	Broken Authentication	Test expired, revoked, scopeless tokens; Validate mTLS certificate binding
API3:2023	Broken Object Property Level Authorization	Mass Assignment: try to alter readonly fields like status, horario; Check if response exposes sensitive data
API4:2023	Unrestricted Resource Consumption	Validate rate limiting; Test 15s timeout; DoS with parallel requests
API5:2023	Broken Function Level Authorization	Access administrative endpoints; Test privilege escalation in OAuth scopes
API6:2023	Unrestricted Access to Sensitive Business Flows	Automation of mass charge creation; Refund abuse
API7:2023	Server-Side Request Forgery (SSRF)	Test webhookUrl with internal/localhost addresses; Validate URL sanitization
API8:2023	Security Misconfiguration	Security headers (HSTS, CSP); Verify error handling does not expose stack traces
API9:2023	Improper Inventory Management	Map undocumented endpoints; Verify old API versions are not exposed
API10:2023	Unsafe Consumption of APIs	Validate DICT integration; Test malformed partner responses

OAuth 2.0 + mTLS Validation

Scenario	Result	Validation
Valid token + correct certificate	200 OK	Request processed normally
Valid token + different certificate	401	cnf claim does not match the certificate
Expired token	401	TokenExpirado
Token without required scope	403	AcessoNegado - insufficient scope
Expired certificate	TLS Failure	Handshake fails before request
Revoked certificate (CRL/OCSP)	TLS Failure	Verify revocation validation
Self-signed certificate	TLS Failure	Not accepted per regulation
Token with incorrect audience	401	TokenInvalido

Webhook Security

• SSRF: Block internal URLs (localhost, 127.0.0.1, private ranges)
• DNS Rebinding: Resolve DNS only once before connecting
• Protocol Validation: Accept only https://, reject file://, gopher://

Manually validating mTLS certificates, OAuth scopes, and rate limiting on every deploy does not scale. Automated DAST in the pipeline detects vulnerabilities before they reach production.

Voidr runs DAST, validates OpenAPI specs, and centralizes results in a single dashboard.

Ver como funciona: Segurança & Compliance

Synthetic Monitoring

Monitoring scenarios, regulatory SLAs, and alert configuration.

Recommended Monitoring Scenarios

Scenario	Frequency	SLA	Alerts
OAuth Health Check	1 min	< 500ms	PagerDuty P1, Slack #alerts
Token Refresh Flow	5 min	< 1000ms	Slack, Grafana
Create + Query Cob	5 min	< 2000ms	Email, Slack, Grafana
Webhook Delivery	5 min	< 5000ms	PagerDuty P1
DICT Query	5 min	< 1500ms	Slack, Datadog
E2E Payment Flow	15 min	< 10000ms	All channels

Regulatory SLAs (PIX Security Manual)

• Availability: Minimum 99.5% monthly per endpoint
• Timeout: Maximum 15 seconds for synchronous operations
• Maintenance window: Prior communication to BACEN required

Configure alerts on multiple channels (Slack, PagerDuty, email) to ensure rapid incident response.

Performance Tests

Load profiles (smoke, load, stress, soak), traffic distribution and acceptance criteria.

Load Profiles

Type	VUs	Duration	Objective
Smoke Test	1-5	1 min	Validate scripts and test environment
Load Test	100-500	30 min	Normal production load
Stress Test	500-2000	15 min	Find breaking point
Spike Test	0→1000→0	10 min	Sudden spikes (flash sale, payroll day)
Soak Test	200-300	4-8 hours	Memory leaks, gradual degradation
Breakpoint Test	Ramp up	Until failure	Absolute maximum capacity

Realistic Traffic Distribution

Endpoint	Traffic	Think Time	Pacing
`POST /cob/{txid} (create charge)`	40%	1-3s	Random
`GET /cob/{txid} (query charge)`	35%	0.5-1s	Constant
`GET /pix (list received)`	15%	2-5s	Random
`PUT /pix/{e2eid}/devolucao (refund)`	8%	5-10s	Random
`Webhook callbacks (simulated)`	2%	N/A	Async

Acceptance Criteria

Error Rate < 1%

P95 Latency < 2s

Throughput ≥ 500 TPS

Recovery < 60s

CPU/Memory < 80%

Run Soak Tests (4h+) regularly to detect memory leaks and gradual degradation that do not appear in short tests.

Service Virtualization

Mock server for BACEN APIs, stateful stubs and fault injection.

Test Environment Architecture


┌─────────────────────────────────────────────────────────────────┐
│                    Ambiente de Testes Isolado                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────┐     ┌─────────────────┐     ┌─────────────────┐   │
│  │  Testes │────▶│  Mock Server    │────▶│  Webhook        │   │
│  │  E2E    │     │  (API BACEN)    │     │  Simulator      │   │
│  └─────────┘     └─────────────────┘     └─────────────────┘   │
│       │                  │                       │              │
│       │          ┌───────┴───────┐               │              │
│       │          ▼               ▼               │              │
│       │    ┌──────────┐   ┌──────────┐           │              │
│       │    │ Stateful │   │  Fault   │           │              │
│       │    │ Stubs    │   │ Injection│           │              │
│       │    └──────────┘   └──────────┘           │              │
│       │                                          │              │
│       └──────────────────────────────────────────┘              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Virtualization allows testing without dependency on the real BACEN environment

Simulation Scenarios

Scenario	Behavior	Use Case
Happy Path	`Standard 2xx responses`	Agile development, basic tests
Timeout Simulation	`Delay 16s → 504 Gateway Timeout`	Resilience and circuit breaker testing
Rate Limiting	`429 after N requests/min`	Validate exponential backoff/retry
Partial Failure	`50% random errors`	Chaos engineering, fallback logic
Webhook Delay	`Callback after 30min`	Polling vs push, reconciliation
Certificate Error	`Simulated mTLS failure`	Certificate error handling

Stateful mocks allow simulating complete flows (create charge → receive payment → process webhook) without real integration.

Synthetic Data

Generation of valid txid, e2eid, CPF/CNPJ without real data (LGPD).

Fields and Generation Rules

Field	Type	Rule
`txid`	String [26-35]	[a-zA-Z0-9]{26,35} unique per receiver CNPJ
`endToEndId (e2eid)`	String [32]	E + ISPB(8) + DATE(8) + SEQ(11) + CTRL(5)
`chave (CPF)`	String [11]	Valid CPF with correct check digit
`chave (CNPJ)`	String [14]	Valid CNPJ with correct check digit
`chave (Email)`	String [max 77]	user{uuid}@testdomain.pix.test
`chave (Phone)`	String [14]	+5511999{random(6)} - E.164 format
`valor.original`	Decimal [16,2]	Random 0.01-999999.99 (log-normal distribution)
`devedor.nome`	String [max 200]	Faker.name() locale pt-BR

Example: PIX Data Generationtypescript

import { faker } from '@faker-js/faker/locale/pt_BR';

// txid: 26-35 caracteres alfanuméricos
const txid = faker.string.alphanumeric({ length: 32 });

// CPF válido com dígito verificador
const cpf = generateValidCPF();

// endToEndId no formato BACEN
const e2eid = `E${ispb}${dateStr}${seq}${ctrl}`;

// Valor com distribuição realista
const valor = faker.finance.amount({ min: 0.01, max: 999999.99 });

LGPD Compliance

• Zero real data: Synthetic data contains no PII from real individuals
• Non-reversibility: Impossible to reconstruct original data from synthetic data
• Full isolation: Test environments fully segregated from production

CI/CD Pipeline

Quality gates per stage: linting, contract tests, DAST, load tests.

Quality Pipeline


┌──────────┐   ┌──────────┐   ┌─────────────┐   ┌──────────┐   ┌────────────┐
│ Pre-     │──▶│  Build   │──▶│ Integration │──▶│ Staging  │──▶│ Production │
│ commit   │   │          │   │             │   │          │   │            │
└──────────┘   └──────────┘   └─────────────┘   └──────────┘   └────────────┘
     │              │               │                │               │
     ▼              ▼               ▼                ▼               ▼
 ┌────────┐   ┌──────────┐   ┌───────────┐   ┌──────────┐   ┌────────────┐
 │Linting │   │ Unit     │   │ Smoke     │   │Regressivo│   │ Canary     │
 │OpenAPI │   │ Contract │   │ Tests     │   │ Security │   │ Monitoring │
 │ Schema │   │ Tests    │   │ E2E       │   │ Load     │   │ Sintético  │
 └────────┘   └──────────┘   └───────────┘   └──────────┘   └────────────┘

Quality gates at each stage prevent regressions in production

GitHub Actions: Pipeline PIXyaml

name: PIX API Quality Gates
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI Schema
        run: npx @stoplight/spectral lint openapi.yaml

      - name: Contract Tests
        run: npx prism proxy openapi.yaml --errors

      - name: Functional Tests
        run: npm run test:pix-api

      - name: Security Scan (OWASP)
        run: npm run security:scan

      - name: Performance Baseline
        run: npm run perf:smoke

Orchestrating contract testing, DAST, and load testing in separate pipelines creates maintenance overhead and fragmented results across tools.

Voidr runs all quality gates in a single workflow and reports consolidated results per PR.

Ver como funciona: Automação de Testes

Checklist

Verification list for infrastructure, tests, security and compliance.

Infrastructure

0/6

Functional Tests

0/6

Security Tests

0/7

Performance

0/5

Data & Compliance

0/5

Use this checklist as an implementation guide. Progress is automatically saved in your browser.

Next Step

Automate PIX API testing and monitoring with AI

AI Agent

AI Agent for PIX APIs

Generates test cases from the OpenAPI spec, runs on every PR, and automatically updates tests when the API changes. Runs in your cloud.

Generation from OpenAPI

Automatic test updates

Execution on every PR

Schedule a demo

PIX PSP Receiver API

Scope and Requirements

APIs Covered in this Playbook

PIX API v2.9.0 — Security Requirements

Applicable Regulations

Functional Tests

Immediate Charge (/cob)

Received PIX (/pix)

Negative Test Cases (Expected Errors)

Security Tests

OWASP API Security Top 10

OAuth 2.0 + mTLS Validation

Injection Vectors for Testing

Webhook Security

Synthetic Monitoring

Recommended Monitoring Scenarios

Regulatory SLAs (PIX Security Manual)

Performance Tests

Load Profiles

Realistic Traffic Distribution

Acceptance Criteria

Service Virtualization

Simulation Scenarios

Synthetic Data

Fields and Generation Rules

LGPD Compliance

CI/CD Pipeline

Checklist

Infrastructure

Functional Tests

Security Tests

Performance

Data & Compliance

Next Step

AI Agent for PIX APIs

What does
a production failure cost?

PIX PSP Receiver API

Scope and Requirements

APIs Covered in this Playbook

PIX API v2.9.0 — Security Requirements

Applicable Regulations

Functional Tests

Immediate Charge (/cob)

Received PIX (/pix)

Negative Test Cases (Expected Errors)

Security Tests

OWASP API Security Top 10

OAuth 2.0 + mTLS Validation

Injection Vectors for Testing

Webhook Security

Synthetic Monitoring

Recommended Monitoring Scenarios

Regulatory SLAs (PIX Security Manual)

Performance Tests

Load Profiles

Realistic Traffic Distribution

Acceptance Criteria

Service Virtualization

Simulation Scenarios

Synthetic Data

Fields and Generation Rules

LGPD Compliance

CI/CD Pipeline

Checklist

Infrastructure

Functional Tests

Security Tests

Performance

Data & Compliance

Next Step

AI Agent for PIX APIs

What doesa production failure cost?

What does
a production failure cost?