Documentação oficial

A infraestrutura
por trás das vendas.

Referência técnica para implementação, configuração e operação do sistema de checkout e marketplace.

Arquitetura de componentes

Estrutura baseada em Ports & Adapters para desacoplamento de infraestrutura.

graph TD subgraph "Core (Services)" CS[Checkout Service] RS[Recipient Service] SS[Settings Service] end subgraph "Adapters (Infrastructure)" PA[Pagar.me API] DB[PostgreSQL / sqlc] TW[Temporal Worker] end H[Handlers / API] --> CS H --> RS CS -.-> PA CS -.-> DB CS -.-> TW

API Handlers

Valida tokens JWT e coordena as chamadas aos serviços.

Core Services

Lógica de checkout, splits e gestão de recebedores.

Temporal Worker

Workflows resilientes para processamento assíncrono.

Ciclo de vida de uma ordem

Sincronização entre a intenção de compra, o gateway e o banco de dados.

sequenceDiagram autonumber participant App as Backend participant API as CheckoutPP participant PG as Pagar.me App->>API: POST /checkout (JWT) API->>API: Valida Assinatura API->>PG: Create Order PG-->>API: Response (paid) API->>API: Efetiva Splits & DB API-->>App: OK (200)

Configuração (ENVs)

Variáveis necessárias para o funcionamento do servidor.

Variável	Descrição	Exemplo
DATABASE_URL	URL de conexão PostgreSQL.	`postgres://...`
SETTINGS_ENCRYPTION_KEY	Chave AES-256 para o banco.	Gerada via `keygen`

CLI Reference

Gestão total através do binário server.

Comandos essenciais

./bin/server keygen

Gera uma nova chave mestra de encriptação.

./bin/server store create "id"

Cria uma nova store no banco com segredos automáticos.

Segurança & JWT

Assinatura via HS256 utilizando o segredo da store.

{
  "iss": "ID_DA_STORE",
  "external_id": "ORD_123",
  "amount": 15000,
  "customer": { "email": "[email protected]", "name": "John" },
  "order": {
    "amount": 15000,
    "items": [...]
  }
}