# SwitchPay — API v2

> Com esta API você cria cobranças (cartão, Pix e boleto), divide o valor de cada venda entre contas (split), consulta transações e recebe avisos automáticos (webhooks) quando um pagamento muda de situação. Contrato 2.0.1.

## Primeiro Pix

Do zero até um Pix pago no sandbox, em 4 passos. Nenhum dinheiro roda.

**1. Pegue sua chave de teste.** A SwitchPay te entrega uma chave que começa com `swp_test_`.
Guarde numa variável de ambiente:

```bash
export SWP_KEY="swp_test_xxxxxxxxxxxxxxxxxxxxxxxx"
```

**2. Crie a cobrança.** Uma chamada só. O `confirm: true` faz ela criar e já gerar o Pix:

```bash
curl -X POST https://api.sandbox.switchpay.app.br/v2/payment-intents \
  -H "Authorization: Bearer $SWP_KEY" \
  -H "Idempotency-Key: pedido-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1500,
    "paymentMethod": "PIX",
    "confirm": true,
    "referenceId": "pedido-0001",
    "buyer": {
      "name": "Maria Souza",
      "document": "12345678909",
      "email": "maria@exemplo.com",
      "phone": { "country": "55", "area": "11", "number": "987654321" }
    }
  }'
```

`amountCents: 1500` é R$ 15,00 (sempre centavos). O `Idempotency-Key` é o id do pedido do seu
lado: se a chamada cair e você repetir com a mesma chave, não gera cobrança em dobro.

**3. Pegue o QR Code na resposta.** Dois campos importam:

| Campo | Pra quê |
|---|---|
| `transactionId` | Id da cobrança (`trx_...`). Guarde no seu pedido. |
| `transaction.paymentDetails.pix.qrCode` | O "copia e cola" que você mostra pro cliente. A imagem vem em `qrCodeImageBase64`. |

A transação nasce `PENDING`, esperando o pagamento.

**4. Simule o pagamento.** No sandbox ninguém paga de verdade; você avisa a API que o Pix foi pago:

```bash
curl -X POST https://api.sandbox.switchpay.app.br/v2/sandbox/transactions/SEU_TRANSACTION_ID/pay \
  -H "Authorization: Bearer $SWP_KEY"
```

A transação volta `PAID`. Pronto: primeiro Pix do começo ao fim.

**E agora?**

- **Saber do pagamento sem perguntar:** cadastre uma URL em `POST /v2/webhooks` e receba o
  aviso `transaction.paid` na hora. Veja **Webhooks**.
- **Dividir o valor da venda:** mande `splitRules` no passo 2. Veja **Split**.
- **Boleto:** igual ao Pix, com `paymentMethod: "BOLETO"` e o endereço do comprador.
- **Cartão:** tem um passo a mais, pra o número do cartão nunca passar pelo seu servidor. Veja
  **Cartão: cofre e cifra**.
- **Produção:** mesmas chamadas, trocando o endereço por `https://api.switchpay.app.br` e a
  chave por uma `swp_live_`. A rota de simular pagamento não existe lá.

## Endpoints

- POST /v2/payment-intents — Criar intenção de pagamento
- GET /v2/payment-intents/{id} — Consultar intenção
- POST /v2/payment-intents/{id}/confirm — Confirmar intenção (cobrar)
- POST /v2/payment-intents/{id}/cancel — Cancelar intenção não confirmada
- GET /v2/transactions — Listar transações
- GET /v2/transactions/{id} — Consultar transação
- GET /sdk.js — Biblioteca do Hosted Fields (cofre)
- GET /hosted-fields — Página do campo do cartão (iframe do cofre)
- GET /keys — Chaves públicas de cifra do cartão (cofre)
- POST /tokenize — Tokenizar cartão (cofre)
- POST /v2/webhooks — Cadastrar URL de webhook
- GET /v2/webhooks — Listar URLs cadastradas
- DELETE /v2/webhooks/{id} — Remover URL de webhook
- POST /v2/payment-links — Criar link de pagamento (em breve)
- GET /v2/payment-links/{id} — Consultar link (em breve)
- POST /v2/payment-links/{id}/cancel — Cancelar link (em breve)
- POST /v2/sandbox/transactions/{id}/pay — Simular pagamento (só sandbox)
- POST /v2/sandbox/transactions/{id}/fail — Simular falha ou cancelamento (só sandbox)

## Documentação

- [Guias e referência (HTML)](https://docs.switchpay.app.br/v2): documentação completa, navegável
- [Especificação OpenAPI 3.1 (YAML)](https://docs.switchpay.app.br/openapi-v2.yaml): a mesma referência em formato máquina
- [Referência completa em texto](https://docs.switchpay.app.br/llms-full.txt): todo o conteúdo em markdown puro, ideal para LLMs