# Criar cobranças

Pix, boleto ou cartão, sempre do mesmo jeito: `POST /v1/payments`.

## Pix

```json
{
  "method": "pix",
  "amount": 4990,
  "customer": { "name": "Maria Silva" }
}
```

Mostre para o cliente o `next_action.qr_code` (copia e cola). Quando a conta manda a imagem do QR Code, ela vem em `next_action.qr_code_base64`. Em `next_action.qr_code_url` fica a imagem do QR Code num endereço público, pronta para um e-mail, um chat ou um [bot do Discord](https://docs.suypay.com/bots.md).

## Boleto

O boleto precisa do CPF ou CNPJ e do endereço do cliente:

```json
{
  "method": "boleto",
  "amount": 15900,
  "customer": {
    "name": "Carlos Souza",
    "email": "carlos@email.com",
    "document": "11144477735",
    "address": { "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "zip": "01310100" }
  }
}
```

O boleto vem em `next_action` sempre com os dois números, seja qual for a conta: `digitable_line` (a linha digitável formatada, `34191.79001 01043.510047 91020.150008 1 93460000026035`) e `barcode` (os 44 dígitos do código de barras). Algumas contas só mandam um deles; a SuyPay calcula o outro. Também vêm `url` (a página do boleto), `pdf` quando a conta tem e `due_date`.

A página de pagamento desenha o código de barras para o app do banco ler pela câmera, mostra a linha para copiar e o PDF para baixar.

## Cartão

O jeito recomendado é o [cartão salvo](https://docs.suypay.com/cards.md). O cliente digita o cartão nos campos da SuyPay, você salva e cobra com `card.id`. Esse cartão serve em **qualquer** conta conectada que aceite cartão salvo, com troca automática de conta se uma falhar, e também em [assinaturas](https://docs.suypay.com/card-subscriptions.md):

```json
{
  "method": "card",
  "amount": 25000,
  "card": { "id": "card_4Fh...", "installments": 3 },
  "customer": { "name": "Ana Lima", "document": "12345678909" }
}
```

Também dá para usar o formulário de cartão **da própria conta** (Stripe, Efí e outras) e mandar só o token dela:

```json
{
  "method": "card",
  "amount": 25000,
  "card": { "token": "tok_...", "installments": 3 },
  "customer": { "name": "Ana Lima", "document": "12345678909" }
}
```

> **Dica:** o token de uma conta só funciona na conta que o gerou. Com ele, crie uma [regra](https://docs.suypay.com/rules.md) que mande cartão sempre para essa conta, ou passe a usar o cartão salvo.

Em nenhum dos dois casos o número do cartão passa pelo seu site ou pela SuyPay.

## Todos os campos

| Campo | | |
|---|---|---|
| `method` | `pix`, `boleto` ou `card` | opcional: omita para o cliente escolher no link |
| `amount` | valor em centavos | obrigatório |
| `customer.name` | nome do cliente | obrigatório |
| `customer.document` | CPF ou CNPJ | boleto, cartão, Asaas e Efí |
| `customer.email` | e-mail | recomendado |
| `customer.address` | endereço | boleto |
| `customer.ip` | IP de quem está comprando | se não mandar, a SuyPay usa o IP de quem chamou a API |
| `description` | o que aparece para você | |
| `expires_in_minutes` | prazo do Pix ou, sem `method`, prazo para o cliente escolher no link | |
| `metadata` | informações suas (`{ "pedido": "1042" }`) | usado nas regras e copiado para a conta |
| `tracking` | UTMs e clique do anúncio (`utm_source`, `utm_campaign`, `fbclid`...) | vai para as [integrações](https://docs.suypay.com/integrations.md) |

## IP do comprador

Asaas, Appmax e Mercado Pago usam o IP de quem compra para barrar fraude no cartão. Se você cria a cobrança do seu servidor, mande o IP do cliente em `customer.ip`. Sem ele, a SuyPay usa o IP de quem chamou a API, que nesse caso é o do seu servidor.

```json
"customer": { "name": "Ana Lima", "document": "12345678909", "ip": "177.12.34.56" }
```

## Metadata

Até 50 chaves, cada uma com até 40 letras, e valores em texto de até 500 letras. A SuyPay guarda tudo na cobrança, usa nas [regras](https://docs.suypay.com/rules.md) e copia para a conta quando ela tem onde guardar:

| Conta | Onde aparece |
|---|---|
| Stripe | `metadata` do pagamento |
| Mercado Pago | `metadata` do pagamento |
| Efí (Pix) | informações adicionais do Pix |
| Woovi | informações adicionais da cobrança |
| Asaas, Appmax | não têm onde guardar (fica só na SuyPay) |

## Sem cobrança em dobro

Mande o cabeçalho `Idempotency-Key` com um código único do pedido. Se a mesma chamada for repetida, por exemplo numa falha de internet, a SuyPay devolve a mesma cobrança em vez de criar outra.

```bash
-H "Idempotency-Key: pedido-1042"
```