# Scalefy Integration Guide (for AI agents)

Integrate the Scalefy payment gateway API. Read this before writing code.

## Base facts

- Base URL: `https://api.scalefypay.com` (provided by your integration manager).
- Auth: `Authorization: Bearer <private_api_key>` on all server-side calls.
- Public token (browser SDK only): exchange once via `POST /api/v2/exchange-token`.
- Amounts: integers in **centavos** (`10000` = R$ 100,00). Minimum invoice: `100`. Minimum payout: `1000`.
- Full contract: `/openapi.json`. Docs: this site. Never invent fields.

## Golden paths

### Accept Pix (payin)

1. `POST /api/v2/invoices` with `method: "pix"`, `product_fisical`, `total_price_cents`, `payer` (name, cpf_cnpj, email, phone), `items` (quantity × unit_price).
2. Show `data.qr_code_pix` / `data.qr_code_base64` to the buyer.
3. Receive postback at `postback_url` (`type: order.paid`, `status: paid`) — verify HMAC before trusting it.
4. Success statuses: `paid`, `liquidated`, `externally_paid`.

### Accept card

1. Backend: `POST /api/v2/exchange-token` → send `public_token` to the browser.
2. Browser SDK: `createCh()` → `setBackendUrl()` → `setPublicToken()` → `await ch.encrypt(cardData)` → `result.token`.
3. Backend: `POST /api/v2/invoices` with `method: "credit_card"`, `card: { token, installment }`.
4. If `three_ds_url` is returned, redirect the buyer.

### Payout (Pix out)

1. `POST /api/v2/payout` with `amount` (≥ 1000), `type: "withdrawal"`, `pix_key` + `pix_key_type` (`cpf|cnpj|email|phone|random`), `postback_url`.
2. ALWAYS send `idempotency_key` (or `Idempotency-Key` header) — retrying without it can duplicate money movement.
3. Track via postback or `GET /api/v2/payout/{id}?by=tid`. Statuses: `processing`, `completed`, `paid`, `failed`, `rejected`.

### Webhooks

- Signed HMAC-SHA256: headers `X-Webhook-Timestamp` (unix) and `X-Signature` (`t=<ts>,v1=<hex>`).
- Signed string: `<timestamp>.<raw_body>` — verify against the raw body with the Webhook Secret, constant-time compare.
- Ack with HTTP `200`. Retries with exponential backoff (30s → 4h). Deduplicate by top-level `id`.
- Fulfill orders only from webhook-confirmed or reconciled state (`GET /api/v2/invoices/{id}`); redirects are UX only.

## Hard rules

- Create payments/payouts only from the backend. Card data only via browser SDK.
- Deduplicate webhooks by `id`.
- Invoice statuses are not a simple enum of two: handle the full map (see docs/payments/statuses).
- Use `external_reference` (invoices) as your stable write identifier.
- Never log card data or API keys.