> ## 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.

# Criar cobrança

> Gera uma cobrança (BKY-) por Pix (Copia e Cola, que também vira QR Code), cartão de crédito (link da página de pagamento) ou cripto (valor na moeda e endereço).

Escopo da forma de pagamento: `payments:write` no Pix, `card:write` no cartão e `crypto:write` em cripto (sem ele, `403 FORBIDDEN`). A cobrança nasce `pending`; quando o pagamento é confirmado, vira `paid` e o webhook `payment.paid` avisa. Sem pagamento até a validade, vira `expired` (no Pix, ainda assim é creditada se o Pix cair depois). Veja antes [as formas disponíveis](https://docs.wyzecash.com.br/referencia/cobrancas/formas-de-pagamento.md) para a conta.

**Idempotency-Key** `string` *required*

8 a 128 caracteres, única por pedido (um UUID ou o número do pedido). Repetir com os mesmos dados devolve a mesma cobrança; com dados diferentes, `422 IDEMPOTENCY_KEY_REUSED`.

**amount** `integer` *required*

Valor em centavos. Abaixo do mínimo da conta: `BELOW_MINIMUM`; fora da faixa aceita no momento: `BELOW_PROVIDER_MINIMUM` ou `ABOVE_PROVIDER_MAXIMUM`.

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

Forma de pagamento: `pix` (Copia e Cola e QR Code), `card` (cartão de crédito à vista, a partir de R$ 5,00, link válido por 30 minutos) ou `crypto` (a partir de R$ 2,00, válido por 10 minutos). Forma indisponível no momento: `422 METHOD_UNAVAILABLE`.

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

Só com `method: "crypto"`: `ltc` (padrão), `btc`, `eth`, `sol`, `trx`, `doge`, `ada` ou `matic`. Fora da lista: `INVALID_CRYPTO_CURRENCY`; enviada em outra forma: `VALIDATION`.

**description** `string`

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

**expiresInMinutes** `integer`

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

**customerId** `string`

UUID de um cliente seu. Cliente de outra conta ou excluído: `422 INVALID_CUSTOMER`.

**subaccountId** `string`

`sacc_...` ou `externalId` de uma subconta: quando paga, a venda é creditada a ela (menos a tarifa e a sua comissão). Desativada: `422 SUBACCOUNT_INACTIVE`; se ela for desativada depois, a venda fica com você.

**split** `object[]`

Divide a venda entre até 10 subcontas, no lugar de `subaccountId` (os dois juntos: `422 INVALID_SPLIT`). Cada item é `{ "subaccountId": "sacc_... ou externalId", "amount": centavos }`; a soma pode ser menor que o valor (o resto fica com você), nunca maior. A mesma subconta duas vezes, parte sem valor ou mais de 10: `422 INVALID_SPLIT`. Quando paga, cada subconta recebe a parte dela menos a sua comissão e a tarifa da WyzeCash na proporção da parte. Estorno e MED tiram de cada uma na mesma proporção.

**tracking** `object`

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

## Resposta

**id** `string`

Código da cobrança (`BKY-` + 12).

**status** `string`

`pending`, `paid`, `expired` ou `refunded`.

**statusTitle** `string`

Texto em português: Entrada pendente, paga (Pix recebido, Cartão aprovado ou Cripto recebida), Entrada expirada, Estornada.

**method** `string`

`pix`, `card` ou `crypto`.

**methodTitle** `string`

Pix, Cartão de crédito ou Cripto.

**amount** `integer`

Valor cobrado.

**fee** `integer`

Tarifa descontada quando paga (`0` antes).

**refundedAmount** `integer`

Quanto já foi estornado ao pagador.

**description** `string | null`

A descrição enviada.

**txid** `string`

Identificador do Pix, o mesmo que consta no QR Code.

**copyPaste** `string | null`

Pix: o código Copia e Cola (BR Code). Gere o QR Code a partir dele. `null` no cartão e na cripto.

**paymentUrl** `string | null`

Cartão: o link da página segura de pagamento, para mandar ao cliente ou abrir num botão. `null` nas outras formas.

**crypto** `object | null`

Cripto: o que o cliente precisa para pagar. `null` nas outras formas.

**propriedades**

**currency** `string`

Moeda (`btc`, `ltc`...).

**currencyTitle** `string`

Nome da moeda, ex.: `Bitcoin (BTC)`.

**amount** `string`

Valor exato na moeda, em texto (sem arredondar).

**address** `string`

Endereço da carteira que recebe.

**card** `object | null`

Cartão aprovado: `brand` (bandeira) e `last4` (final). `null` antes do pagamento e nas outras formas.

**availableAt** `string | null`

Cartão: quando o valor sai da retenção e entra no saldo disponível (15 dias depois da aprovação, D+15).

**released** `boolean`

Cartão: se o valor já entrou no saldo disponível.

**expiresAt** `string`

Validade (ISO 8601).

**paidAt** `string | null`

Hora do pagamento.

**customer** `object | null`

Cliente ligado.

**propriedades**

**id** `string`

UUID do cliente.

**name** `string | null`

Nome.

**payer** `object | null`

Quem pagou, como o banco informou. `null` antes do pagamento.

**propriedades**

**name** `string | null`

Nome do pagador.

**document** `string | null`

CPF sempre mascarado (`***.456.789-**`) ou CNPJ.

**institution** `string | null`

Banco do pagador.

**subaccountId** `string | null`

A subconta da venda (`sacc_...`), quando há uma só.

**split** `object[] | null`

A divisão: `{ subaccountId, name, amount }` de cada subconta. `null` sem divisão.

**createdAt** `string`

Criação (ISO 8601).

```bash cURL theme={null}
curl -X POST https://api.wyzecash.com.br/v1/payments \
  -H "Authorization: Bearer bk_live_..." \
  -H "Idempotency-Key: pedido-1842" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "method": "pix",
    "description": "Pedido 1842",
    "expiresInMinutes": 30
  }'

# Cartão: "method": "card" (a resposta traz o paymentUrl)
# Cripto: "method": "crypto", "cryptoCurrency": "btc" (a resposta traz crypto)
# Divisão: "split": [{ "subaccountId": "vendedor-42", "amount": 10000 }, { "subaccountId": "vendedor-77", "amount": 4000 }]
```

```javascript JavaScript theme={null}
const res = await fetch("https://api.wyzecash.com.br/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BUKIO_API_KEY}`,
    "Idempotency-Key": "pedido-1842",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 15000, description: "Pedido 1842", expiresInMinutes: 30 }),
});
const charge = await res.json();
console.log(charge.id, charge.copyPaste);
```

```python Python theme={null}
import os, requests

res = requests.post(
    "https://api.wyzecash.com.br/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['BUKIO_API_KEY']}",
        "Idempotency-Key": "pedido-1842",
    },
    json={"amount": 15000, "description": "Pedido 1842", "expiresInMinutes": 30},
)
charge = res.json()
print(charge["id"], charge["copyPaste"])
```

```php PHP theme={null}
<?php
$ch = curl_init("https://api.wyzecash.com.br/v1/payments");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BUKIO_API_KEY"),
        "Idempotency-Key: pedido-1842",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode(["amount" => 15000, "description" => "Pedido 1842", "expiresInMinutes" => 30]),
]);
$charge = json_decode(curl_exec($ch), true);
echo $charge["id"], " ", $charge["copyPaste"];
```

```json 200 theme={null}
{
  "id": "BKY-7KQ2M9XP4RZT",
  "status": "pending",
  "statusTitle": "Entrada pendente",
  "method": "pix",
  "methodTitle": "Pix",
  "amount": 15000,
  "fee": 0,
  "refundedAmount": 0,
  "description": "Pedido 1842",
  "txid": "7kq2m9xp4rzt1a2b3c4d5e6f",
  "copyPaste": "00020126580014br.gov.bcb.pix...6304ABCD",
  "paymentUrl": null,
  "crypto": null,
  "card": null,
  "expiresAt": "2026-10-08T15:30:00.000Z",
  "paidAt": null,
  "customer": null,
  "payer": null,
  "subaccountId": null,
  "split": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}
```

```json 422 theme={null}
{
  "error": { "code": "BELOW_MINIMUM", "message": "O valor mínimo da cobrança é R$ 1,00." },
  "requestId": "req_01JA..."
}
```


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