API PayTag v1 — Guia de Integração

You are a principal software engineer building a production-grade PayTag Payment Gateway integration.

Sources of truth:
- Official Documentation: https://paytag.pro/api-docs
- Production Base URL: https://paytag.pro/api/v1

Strict Integration Rules:
1. SECURITY: Keep PayTag secret keys (sk_live_ / sk_test_) strictly server-side. Load from environment variables (e.g. PAYTAG_SECRET_KEY). Never expose secret keys to the browser or frontend.
2. IDEMPOTENCY: Include a unique UUID v4 'Idempotency-Key' header on all POST mutation requests (creating PIX, credit card, or boleto payments) to prevent duplicate transactions.
3. AUTHENTICATION HEADERS:
   - X-PayTag-Public-Key: pk_live_...
   - X-PayTag-Secret-Key: sk_live_...
   - Content-Type: application/json
4. WEBHOOK HMACS: Validate incoming Webhook notifications against the 'X-PayTag-Signature' header (format 'sha256=') using HMAC SHA-256 calculation on raw body payload with your PAYTAG_WEBHOOK_SECRET. Strip 'sha256=' if present before comparison.
5. FULFILLMENT: Fulfill orders or grant user permissions ONLY when a webhook 'payment.approved' event is HMAC-verified or when server-side reconciliation confirms status via GET /api/v1/transactions/{tx_ref}.
6. NO UNDOCUMENTED FIELDS: Strictly stick to documented PayTag contract fields (amount in cents, description, method, buyer, card, boleto, pix, tx_ref, status).

PAYTAG API CONTRACTS:

1. Unified Payment Endpoint:
   POST /api/v1/payments
   Headers: X-PayTag-Public-Key, X-PayTag-Secret-Key, Idempotency-Key

   A) Create PIX Payment:
   Payload:
   {
     "amount": 12990,
     "description": "Order #1001",
     "method": "pix",
     "buyer": {
       "firstName": "João", "lastName": "Silva", "email": "joao@email.com", "doc": "12345678909", "phone": "11999999999",
       "address": { "postCode": "01001000", "street": "Rua Exemplo", "number": "100", "neighborhood": "Centro", "city": "São Paulo", "state": "SP" }
     },
     "external_reference": "order_1001"
   }
   Expected Response:
   {
     "success": true, "tx_ref": "TX-12345", "status": "pending", "method": "pix", "amount": 12990,
     "pix": { "qr_code": "00020126580014BR.GOV.BCB.PIX...", "qr_image": "data:image/png;base64,..." }
   }

   B) Create Credit Card Payment:
   Payload:
   {
     "amount": 25000, "description": "Order #1002", "method": "credit", "installments": 3,
     "buyer": {
       "firstName": "Maria", "lastName": "Souza", "email": "maria@email.com", "doc": "12345678909", "phone": "11999999999",
       "address": { "postCode": "01001000", "street": "Rua Exemplo", "number": "100", "neighborhood": "Centro", "city": "São Paulo", "state": "SP" }
     },
     "card": { "holderName": "MARIA SOUZA", "number": "4111111111111111", "expirationMonth": "12", "expirationYear": "2030", "cvv": "123" },
     "external_reference": "order_1002"
   }
   Expected Response:
   { "success": true, "tx_ref": "TX-12346", "status": "approved", "method": "credit", "amount": 25000, "card": { "last4": "1111", "brand": "visa" } }

2. Consult Transaction Status (Reconciliation):
   GET /api/v1/transactions/{tx_ref}
   Headers: X-PayTag-Public-Key, X-PayTag-Secret-Key
   Expected Response:
   { "tx_ref": "TX-12345", "status": "approved" | "pending" | "refused" | "refunded", "amount": 12990 }

3. Webhook Receiver Route & Signature Verification:
   Received Header: X-PayTag-Signature (e.g. 'sha256=1a2b3c...')
   Verification:
     rawSignature = signatureHeader.replace(/^sha256=/, '');
     expectedSignature = crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
     isValid = crypto.timingSafeEqual(Buffer.from(rawSignature), Buffer.from(expectedSignature));

TASK:
Write the complete, clean, modular, and fully working PayTag API integration module in my project language/framework including:
- PayTag HTTP Client / Service wrapper class.
- Controller to create PIX and Credit Card payments via POST /api/v1/payments.
- Webhook listener route with raw body HMAC SHA-256 verification and order fulfillment handler.

Generate the complete production code now.

Crie um serviço completo de integração da API PayTag v1 para Node.js com TypeScript e Express.

REQUISITOS OBRIGATÓRIOS:
1. Crie uma classe 'PayTagService' que lê PAYTAG_PUBLIC_KEY, PAYTAG_SECRET_KEY e PAYTAG_WEBHOOK_SECRET de process.env.
2. Chamadas POST para https://paytag.pro/api/v1/payments devem utilizar o header 'Idempotency-Key' gerado com crypto.randomUUID().
3. Envie 'method': 'pix' ou 'credit' no payload de POST /api/v1/payments com buyer.address completo (postCode, street, number, neighborhood, city, state) e buyer.doc.
4. Rota POST '/api/webhooks/paytag' usando express.raw({ type: 'application/json' }) para receber o raw body. Trate o header 'X-PayTag-Signature' (removendo 'sha256=' se presente) e valide HMAC SHA-256 com timingSafeEqual.
5. Se a assinatura for válida e o evento for 'payment.approved', execute a função idempotente 'fulfillOrder(external_reference, tx_ref)'.

Crie um módulo completo de integração da API PayTag v1 em Python usando FastAPI e httpx.

REQUISITOS OBRIGATÓRIOS:
1. Chaves de API carregadas via os.getenv("PAYTAG_SECRET_KEY") e os.getenv("PAYTAG_PUBLIC_KEY").
2. Header 'Idempotency-Key' com uuid.uuid4() em todas as requisições de cobrança POST /api/v1/payments.
3. Função de criação de cobrança PIX, Cartão e Boleto em POST /api/v1/payments enviando buyer.address e buyer.doc.
4. Rota de Webhook lendo request.body() bruto. Trate o header 'X-PayTag-Signature' (removendo o prefixo 'sha256=' se presente) e valide HMAC SHA-256 com hmac.compare_digest.
5. Processe a aprovação do pedido ao receber evento 'payment.approved'.

Crie uma integração profissional da API PayTag v1 para PHP 8.2+ / Laravel usando a facade Http e Jobs assíncronos.

REQUISITOS OBRIGATÓRIOS:
1. Configuração via config/paytag.php lendo env('PAYTAG_SECRET_KEY') e env('PAYTAG_PUBLIC_KEY').
2. Serviço 'PayTagClient' utilizando Http::withHeaders() injetando 'Idempotency-Key' => (string) Str::uuid() para POSTs em https://paytag.pro/api/v1/payments.
3. Controller de Checkout chamando POST /api/v1/payments com method ('pix', 'credit', 'boleto'), buyer.doc e buyer.address.
4. Controller de Webhook recebendo $request->getContent() bruto. Trate o header 'X-PayTag-Signature' (removendo 'sha256=' se presente) e valide hash_hmac('sha256', $rawBody, $secret) com hash_equals.
5. Ao validar 'payment.approved', insira um Job 'ProcessPayTagPaymentApproved' na fila para entrega do pedido.

# PayTag API Production Integration Rules for Cursor
- Base URL: https://paytag.pro/api/v1
- Secret Keys (sk_live_) are strictly SERVER-SIDE only. Never expose to client/frontend code.
- Payments Endpoint: POST /api/v1/payments (specify method: 'pix' | 'credit' | 'boleto').
- Required Headers on POST requests:
  - X-PayTag-Public-Key
  - X-PayTag-Secret-Key
  - Idempotency-Key (Must be a newly generated UUID v4 on every mutation request)
- Always verify Webhooks using HMAC SHA-256 over raw request body against 'X-PayTag-Signature' (strip 'sha256=' prefix before comparing).
- Fulfill orders/access ONLY from HMAC-verified webhook events ('payment.approved') or server-side GET /api/v1/transactions/{tx_ref} reconciliation.

# PayTag API Engineering Guidelines

## Principles
1. **Server-Side Security**: Secret API Keys (`sk_live_`) must be loaded from environment variables (`PAYTAG_SECRET_KEY`) on the server.
2. **Idempotency**: All POST creation endpoints require a unique `Idempotency-Key` (UUID v4) header.
3. **Webhook Verification**: Verify `X-PayTag-Signature` using `HMAC_SHA256(rawBody, PAYTAG_WEBHOOK_SECRET)` after removing any `sha256=` prefix.
4. **Order Fulfillment**: Fulfill orders only upon verified `payment.approved` webhook or `GET /api/v1/transactions/{tx_ref}` server reconciliation.

## Endpoints
- Base URL: `https://paytag.pro/api/v1`
- `POST /api/v1/payments` - Create Payment (method: 'pix', 'credit', 'boleto')
- `GET /api/v1/transactions/{tx_ref}` - Query transaction status
- `GET /api/v1/transactions` - List transactions with pagination
- `GET /api/v1/me` - Account profile and fee schedule