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

Antes de mostrar as opções para o seu cliente, consulte as formas disponíveis para a conta (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 · 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 seu: liga a cobrança a ele.

subaccountId · string

sacc_... de uma subconta: 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.

Pix

curl -X POST https://bukio-backend-production.up.railway.app/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"
  }'

​

Resposta

Pix

{
  "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"
}

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

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) e só então entra no saldo disponível. No saldo, 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} · escopo transactions:read

curl https://bukio-backend-production.up.railway.app/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 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=... · escopo transactions:read

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

Da mais nova para a mais antiga, com paginação 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).