> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wyzecash.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cobranças

> Crie cobranças por Pix (QR Code e Copia e Cola), cartão de crédito (página de pagamento) ou cripto (endereço e valor na moeda), consulte a situação e saiba quem pagou.

Uma cobrança (`BKY-`) é o que o seu cliente paga, por **Pix**, **cartão de crédito** ou **cripto**. Ela nasce **pendente**, vira **paga** quando o pagamento é confirmado (você recebe `payment.paid`) ou **expira** se ninguém pagar até a validade. Cobrança não se cancela: sem pagamento, ela expira sozinha. A tarifa da forma de pagamento sai do valor recebido.

| Forma | `method` | O que o cliente recebe | Validade | Quando entra no saldo |
| - | - | - | - | - |
| Pix | `pix` (padrão) | `copyPaste`: o Pix Copia e Cola, que também vira QR Code | `expiresInMinutes` (5 min a 30 dias) | na hora |
| Cartão de crédito | `card` | `paymentUrl`: o link de uma página segura de pagamento, à vista | 30 minutos | 15 dias depois da aprovação, D+15 (fica "a liberar" até lá) |
| Cripto | `crypto` | `crypto`: a moeda, o valor nela e o endereço da carteira | 10 minutos | na hora em que a rede confirma, em reais |

> [!NOTE]
>
> Antes de mostrar as opções para o seu cliente, consulte [as formas disponíveis para a conta](https://docs.wyzecash.com.br/referencia/cobrancas/formas-de-pagamento.md) (`GET /v1/payments/methods`): cada uma vem com `available`, a faixa de valor e, na cripto, as moedas aceitas.

## Criar uma cobrança

[`POST /v1/payments`](https://docs.wyzecash.com.br/referencia/cobrancas/criar-cobranca) · escopo da forma: `payments:write` (Pix), `card:write` (cartão) ou `crypto:write` (cripto) · `Idempotency-Key` obrigatória

**amount** `integer` *required*

Valor em centavos. Abaixo do mínimo da conta: `BELOW_MINIMUM`. Fora da faixa aceita no momento (cartão a partir de R$ 5,00, cripto a partir de R$ 2,00): `BELOW_PROVIDER_MINIMUM` ou `ABOVE_PROVIDER_MAXIMUM`.

**method** `string` (default: pix)

Forma de pagamento: `pix`, `card` ou `crypto`. Forma indisponível para a conta no momento: `422 METHOD_UNAVAILABLE`.

**cryptoCurrency** `string` (default: ltc)

Só com `method: "crypto"`: a moeda em que o cliente paga. `ltc` (Litecoin, padrão), `btc`, `eth`, `sol`, `trx`, `doge`, `ada` ou `matic`. Moeda fora da lista: `INVALID_CRYPTO_CURRENCY`; enviada em outra forma: `VALIDATION`.

**description** `string`

Até 140 caracteres. Aparece no extrato e no webhook; no cartão, aparece também na página de pagamento.

**expiresInMinutes** `integer`

Só no Pix: validade do QR Code, de 5 minutos a 30 dias (43200). Sem o campo, vale a validade padrão da conta.

**customerId** `string`

UUID de um [cliente](https://docs.wyzecash.com.br/endpoints/clientes.md) seu: liga a cobrança a ele.

**subaccountId** `string`

`sacc_...` de uma [subconta](https://docs.wyzecash.com.br/endpoints/subcontas.md): quando paga, a venda é creditada a ela (menos a tarifa e a sua comissão). No cartão, o crédito na subconta acontece quando o valor é liberado.

**tracking** `object`

Rastreio para os plugins de marketing ligados no painel (UTMify, Meta Ads, Google Analytics): `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `src`, `sck`, `fbc`, `fbp`, `gaClientId`, `gaSessionId`, `ip`, `userAgent`, `pageUrl` (textos de até 500 caracteres). Nada disso vai para quem paga.

```bash Pix theme={null}
curl -X POST https://api.wyzecash.com.br/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: 6f1c2d9e-pedido-1842" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "method": "pix",
    "description": "Pedido 1842",
    "expiresInMinutes": 30,
    "customerId": "0d6c1a7e-5b7f-4f3e-9b2a-1c2d3e4f5a6b"
  }'
```

```bash Cartão theme={null}
curl -X POST https://api.wyzecash.com.br/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: 6f1c2d9e-pedido-1843" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15000, "method": "card", "description": "Pedido 1843" }'
```

```bash Cripto theme={null}
curl -X POST https://api.wyzecash.com.br/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: 6f1c2d9e-pedido-1844" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15000, "method": "crypto", "cryptoCurrency": "btc", "description": "Pedido 1844" }'
```

### Resposta

```json Pix theme={null}
{
  "id": "BKY-7KQ2M9XP4RZT",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "method": "pix",
  "methodTitle": "Pix",
  "amount": 15000,
  "fee": 0,
  "refundedAmount": 0,
  "description": "Pedido 1842",
  "txid": "7kq2m9xp4rzt...",
  "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
  "paymentUrl": null,
  "crypto": null,
  "card": null,
  "expiresAt": "2026-10-08T15:30:00.000Z",
  "paidAt": null,
  "customer": { "id": "0d6c1a7e-5b7f-4f3e-9b2a-1c2d3e4f5a6b", "name": "Ana Souza" },
  "payer": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}
```

```json Cartão theme={null}
{
  "id": "BKY-8RP3N2WQ5XZA",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "method": "card",
  "methodTitle": "Cartão de crédito",
  "amount": 15000,
  "fee": 0,
  "copyPaste": null,
  "paymentUrl": "https://app.wyzecash.com.br/pay/BKY-8RP3N2WQ5XZA",
  "crypto": null,
  "card": null,
  "availableAt": null,
  "released": false,
  "expiresAt": "2026-10-08T15:30:00.000Z",
  "paidAt": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}
```

```json Cripto theme={null}
{
  "id": "BKY-3TQ9V7KM2HPD",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "method": "crypto",
  "methodTitle": "Cripto",
  "amount": 15000,
  "fee": 0,
  "copyPaste": null,
  "paymentUrl": null,
  "crypto": {
    "currency": "btc",
    "currencyTitle": "Bitcoin (BTC)",
    "amount": "0.00041823",
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  },
  "expiresAt": "2026-10-08T15:10:00.000Z",
  "paidAt": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}
```

| Campo | O que é |
| - | - |
| `id` | código da cobrança (`BKY-`), use nas consultas e nos webhooks |
| `status`, `statusTitle` | `pending` Entrada pendente · `paid` Pix recebido, Cartão aprovado ou Cripto recebida · `expired` Entrada expirada · `refunded` Estornada |
| `method`, `methodTitle` | forma de pagamento: `pix` Pix, `card` Cartão de crédito, `crypto` Cripto |
| `amount` | valor cobrado (centavos) |
| `fee` | tarifa descontada quando paga (`0` antes do pagamento) |
| `refundedAmount` | quanto já foi estornado ao pagador (só no Pix) |
| `txid` | identificador da cobrança na rede de pagamento |
| `copyPaste` | Pix: o código Copia e Cola (BR Code). Gere o QR Code a partir dele. `null` no cartão e na cripto |
| `paymentUrl` | cartão: o link da página de pagamento. Mande para o cliente ou abra num botão "Pagar com cartão". `null` nas outras formas |
| `crypto` | cripto: `currency`, `currencyTitle`, `amount` (o valor exato na moeda, em texto, sem arredondar) e `address` (a carteira). `null` nas outras formas |
| `card` | cartão aprovado: `brand` (bandeira) e `last4` (final). `null` antes do pagamento |
| `availableAt`, `released` | cartão: quando o valor sai da retenção e entra no disponível, e se já entrou |
| `expiresAt`, `paidAt` | validade e hora do pagamento |
| `customer` | cliente ligado, se houver |
| `payer` | Pix: quem pagou, como o banco informou: `name`, `document` (CPF sempre mascarado, ex.: `***.456.789-**`) e `institution`. `null` antes do pagamento |

> [!TIP]
>
> **Pix:** mostre o `copyPaste` como QR Code **e** como texto com botão "Copiar": no celular, a maioria paga pelo Copia e Cola. **Cartão:** abra o `paymentUrl` num botão ou mostre como QR Code para quem está no computador. **Cripto:** mostre o endereço como QR Code e o valor com botão "Copiar"; avise que o valor tem de ser enviado exatamente e na rede da moeda.

### Cartão: valor a liberar

A venda no cartão é aprovada na hora (`payment.paid`, `statusTitle: "Cartão aprovado"`), mas o valor líquido fica **a liberar** até `availableAt` (15 dias depois da aprovação, D+15; o prazo da sua conta vem em `holdDays` nas [formas de pagamento](https://docs.wyzecash.com.br/referencia/cobrancas/formas-de-pagamento.md)) e só então entra no saldo disponível. No [saldo](https://docs.wyzecash.com.br/endpoints/saldo.md), ele aparece em `pending`; no extrato, a movimentação fica `pending` com o título "Venda no cartão" até liberar. O cartão é à vista e quem paga digita os dados numa página segura: nenhum dado de cartão passa pela WyzeCash nem pelo seu servidor.

### Cripto: valor na moeda

O valor em reais é convertido para a moeda na hora em que a cobrança é criada, e o cliente tem 10 minutos para enviar. Pagamento até 1% abaixo do valor pedido (diferença de câmbio ou taxa da rede) conta como pago; bem abaixo disso, não é creditado. O dinheiro entra no seu saldo em reais.

### Cobrança paga depois de expirar

Se o Pix cair depois da validade, a cobrança ainda é creditada e vira `paid` (você recebe `payment.paid`). Trate os dois eventos no seu sistema: `payment.expired` não é o fim da história.

## Consultar uma cobrança

[`GET /v1/payments/{id}`](https://docs.wyzecash.com.br/referencia/cobrancas/consultar-cobranca) · escopo `transactions:read`

```bash theme={null}
curl https://api.wyzecash.com.br/v1/payments/BKY-7KQ2M9XP4RZT \
  -H "Authorization: Bearer bk_live_..."
```

A resposta tem o mesmo formato da criação, com o `status` atual. Prefira o [webhook](https://docs.wyzecash.com.br/webhooks/cobrancas.md) para saber do pagamento; se precisar consultar em laço (uma tela de "aguardando pagamento"), consulte a cada 2 segundos ou mais, dentro do limite de 300 leituras por minuto.

## Listar cobranças

[`GET /v1/payments?limit=50&cursor=...`](https://docs.wyzecash.com.br/referencia/cobrancas/listar-cobrancas) · escopo `transactions:read`

```json theme={null}
{
  "items": [ { "id": "BKY-7KQ2M9XP4RZT", "status": "paid", "method": "pix", "...": "..." } ],
  "nextCursor": "WyIyMDI2LTEwLTA4VDE1OjAwOjAwLjAwMFoiLCIuLi4iXQ"
}
```

Da mais nova para a mais antiga, com [paginação por cursor](https://docs.wyzecash.com.br/convencoes.md#paginacao-por-cursor).

## Estornos

O estorno (total ou parcial, `EST-`) vale **só para cobranças pagas por Pix** e é feito **no painel**, com o código do app autenticador quando essa opção estiver ligada. Pela API você acompanha: a cobrança passa a mostrar `refundedAmount` (e `status: "refunded"` quando devolvida por inteiro) e o webhook `payment.refunded` avisa. Venda no cartão e pagamento em cripto não têm estorno pela WyzeCash (`422 REFUND_NOT_AVAILABLE`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.