Sua primeira cobrança

Da chave de API ao primeiro Pix recebido, em quatro passos.

1. Crie a chave de API

   No painel WyzeCash, abra Integrações e API › Chaves de API › Nova chave. Dê um nome, escolha as permissões (para este guia: payments:write, transactions:read e balance:read; para cobrar no cartão ou em cripto, também card:write ou crypto:write) e, se quiser, uma validade.

   A chave completa (bk_live_...) aparece uma única vez. Guarde num cofre de segredos do seu sistema; nunca no código nem no navegador.

   Chaves que sacam ou enviam Pix (withdrawals:write, pix:write) exigem o 2FA ligado na sua conta e pelo menos um IP liberado. Veja Autenticação.

2. Faça a primeira chamada

   curl https://bukio-backend-production.up.railway.app/v1/balance \
     -H "Authorization: Bearer bk_live_SEU_ID_SEU_SEGREDO"
   

   {
     "available": 0,
     "pending": 0,
     "blocked": 0,
     "medOwed": 0,
     "subaccounts": 0,
     "free": 0,
     "withdrawal": { "minPerTransaction": 100 },
     "updatedAt": null
   }
   
3. Crie uma cobrança Pix

   Mande um Idempotency-Key único por pedido (um UUID serve): se a conexão cair e você repetir, a WyzeCash devolve a mesma cobrança em vez de criar outra.

   curl -X POST https://bukio-backend-production.up.railway.app/v1/payments \
     -H "Authorization: Bearer bk_live_SEU_ID_SEU_SEGREDO" \
     -H "Idempotency-Key: pedido-1842" \
     -H "Content-Type: application/json" \
     -d '{ "amount": 15000, "description": "Pedido 1842", "expiresInMinutes": 30 }'
   

   {
     "id": "BKY-7KQ2M9XP4RZT",
     "status": "pending",
     "statusTitle": "Entrada pendente",
     "amount": 15000,
     "fee": 0,
     "refundedAmount": 0,
     "description": "Pedido 1842",
     "txid": "...",
     "copyPaste": "00020126580014br.gov.bcb.pix...",
     "expiresAt": "2026-10-08T15:30:00.000Z",
     "paidAt": null,
     "customer": null,
     "payer": null,
     "createdAt": "2026-10-08T15:00:00.000Z"
   }
   

   Mostre o copyPaste para quem vai pagar: como texto (Pix Copia e Cola) e como QR Code (qualquer biblioteca de QR Code gera a imagem a partir dessa string).

4. Saiba quando o Pix cair

   Cadastre a URL do seu servidor em Integrações e API › Webhooks. Quando a cobrança for paga, você recebe um POST com o evento payment.paid:

   {
     "id": "evt_01JA...",
     "type": "payment.paid",
     "created_at": "2026-10-08T15:04:12.318Z",
     "data": {
       "id": "BKY-7KQ2M9XP4RZT",
       "status": "paid",
       "amount": 15000,
       "fee": 50,
       "description": "Pedido 1842",
       "txid": "...",
       "expiresAt": "2026-10-08T15:30:00.000Z",
       "customerId": null,
       "paidAt": "2026-10-08T15:04:11.000Z",
       "endToEndId": "E12345678202610081504abcdef123456",
       "createdAt": "2026-10-08T15:00:00.000Z"
     }
   }
   

   Valide a assinatura antes de liberar o pedido (Validando a assinatura). Se preferir consultar em vez de esperar o aviso, GET /v1/payments/BKY-7KQ2M9XP4RZT devolve o status atual.

​

Próximos passos

Links de pagamento

Uma página de pagamento pronta, sem tela para programar.

Saques

Tire o saldo para a chave Pix que você mandar.

Eventos de webhook

O corpo de cada evento e o jeito certo de tratar.

Erros

Códigos estáveis e mensagens prontas para o usuário.