# TroqPay API Summary

**TroqPay** is a Brazilian Pix payment API enabling charge collection, webhook payment tracking, balance reading, and withdrawal requests in production.

## Core Details

**Base URL:** `https://api.troqpay.com`

**Authentication:** Bearer token format with API keys:
- Test: `trq_test_<secret>`
- Production: `trq_live_<secret>` (requires `APPROVED` account status)

**Currency:** BRL (Brazilian Real) exclusively

**Hosted Checkout:** `https://pay.troqpay.com/pay/{checkoutId}`

## Key Endpoints

| Endpoint | Purpose | Requirements |
|----------|---------|--------------|
| POST /v1/checkouts | Create Pix charge | `CHECKOUT:CREATE` permission |
| GET /v1/checkouts/{id} | Retrieve checkout | Works without account approval if key has `CHECKOUT:READ` |
| GET /v1/balance | Read account balance | `BALANCE:READ` permission, approved account for production |
| POST /v1/withdrawals | Request withdrawal | Production only; requires approval, `Idempotency-Key`, `WITHDRAWAL:CREATE` |
| GET /v1/withdrawals/{id} | Check withdrawal status | `WITHDRAWAL:READ` permission |

## Payment Details

- **Checkout amounts:** integers in centavos (BRL cents)
- **Balance fields:** decimal strings in BRL
- **Customer data:** `phone` accepted in requests but not returned; `document` allows 3–32 characters (unvalidated)

## Webhooks

Events: `checkout.created`, `checkout.paid`, `checkout.expired`

Signature method: "HMAC-SHA256 of raw body in hex, delivered via `x-troqpay-signature` header"

Retry pattern: up to 5 attempts with escalating backoff (60s → 5m → 15m → 60m)

## SDK & Agents

JavaScript SDK: `@troqpay/sdk` for Node.js backends

Claude/Codex plugin exposes: `troqpay_create_checkout`, `troqpay_get_checkout`, `troqpay_get_balance`, plus withdrawal tools when enabled