Bots de vendas (Discord e outros)

Bots de vendas no Discord, no Telegram e no WhatsApp costumam pedir "o token do gateway" para gerar o Pix, esperar o pagamento e entregar o produto. A SuyPay foi pensada para esse uso: uma chave, um Pix, a imagem do QR Code e um aviso quando pagar, passando pela conta mais barata e seguindo por outra se uma cair.

1. Crie uma chave só para o bot

Em Desenvolvedores → Chaves e MCP → Criar chave, escolha Só cobranças. Essa chave:

• cria cobranças e vê só as que ela mesma criou (pelo id ou em GET /v1/payments, que lista só as dela);
• não lista os seus clientes, não devolve dinheiro, não saca e não mexe em contas ou webhooks.

Se o bot for de outra pessoa (um bot público ou comprado numa comunidade), use sempre essa chave. Se ela vazar, o pior que dá para fazer com ela é gerar cobranças para você receber. Revogue em um clique quando quiser.

Atenção: nunca cole uma chave Completa num bot de terceiros. E nunca cole as chaves do Mercado Pago, Asaas ou outra conta diretamente num bot: elas devolvem dinheiro e às vezes sacam.

2. Crie o Pix quando alguém comprar

curl https://api.suypay.com/v1/payments \
  -H "Authorization: Bearer suy_live_..." \
  -H "Idempotency-Key: pedido-discord-81723" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount": 2990,
    "description": "VIP 30 dias",
    "customer": { "name": "fulano#1234" },
    "expires_in_minutes": 30,
    "metadata": { "discord_user": "123456789012345678", "guild": "987654321", "produto": "vip-30" }
  }'

Use o id do pedido do bot na Idempotency-Key: se o bot repetir a chamada (queda, clique duplo), a SuyPay devolve o mesmo Pix em vez de criar outro.

A resposta traz tudo que o bot mostra:

Se a venda precisar de CPF, e-mail ou celular para alguma conta, mande em customer. Sem eles, a SuyPay usa as contas que não pedem; se nenhuma servir, a resposta diz qual dado falta.

3. Saiba quando pagou

O jeito certo é o webhook: cadastre o endereço do bot, assine payment.succeeded e confira a assinatura SuyPay-Signature. Os metadata voltam no aviso, então o bot sabe quem comprou o quê.

Tem mais de um bot na mesma empresa? Ao criar o endereço em Webhooks, escolha Só da chave do bot: cada um recebe apenas os avisos das cobranças que ele criou (only_source: "key:key_..." pela API).

Se o bot não tiver um endereço público, consulte a cobrança a cada 5 a 10 segundos enquanto ela estiver aberta:

curl https://api.suypay.com/v1/payments/pay_... -H "Authorization: Bearer suy_live_..."

Entregue o produto só com status: "succeeded". Pare de consultar quando o status for failed ou canceled (venceu).

Exemplo com discord.js

const suypay = (rota, corpo, chave) =>
  fetch(`https://api.suypay.com/v1${rota}`, {
    method: corpo ? 'POST' : 'GET',
    headers: {
      Authorization: `Bearer ${process.env.SUYPAY_KEY}`,
      'Content-Type': 'application/json',
      ...(chave ? { 'Idempotency-Key': chave } : {}),
    },
    body: corpo && JSON.stringify(corpo),
  }).then((r) => r.json())

// dentro do comando /comprar
const pedido = `${interaction.id}`
const pix = await suypay('/payments', {
  method: 'pix', amount: 2990, description: 'VIP 30 dias', expires_in_minutes: 30,
  customer: { name: interaction.user.username },
  metadata: { discord_user: interaction.user.id, produto: 'vip-30' },
}, pedido)

if (pix.status === 'failed') return interaction.reply({ content: pix.failure_reason, ephemeral: true })

await interaction.reply({
  ephemeral: true,
  content: 'Pix copia e cola:\n```' + pix.next_action.qr_code + '```',
  embeds: [{ title: 'Pague R$ 29,90 com Pix', image: { url: pix.next_action.qr_code_url }, url: pix.payment_url }],
})

Para quem vende bots

Se você desenvolve um bot de vendas e quer oferecer a SuyPay como gateway, peça ao seu cliente só duas coisas: a chave Só cobranças e (opcional) o segredo do webhook. Funciona igual para todas as contas que ele conectar na SuyPay, e ele troca de conta sem mexer no bot.

Erros comuns

Um bot para várias empresas

Se você desenvolve um bot que outras lojas usam, não peça a chave de cada uma. Crie um app em Configuração → OAuth e deixe cada loja autorizar o bot com um clique. Veja OAuth para apps.

Bots com carteira (saldo)

Muitos bots de vendas têm uma "carteira". Há dois tipos, e a SuyPay atende os dois:

Saldo do comprador (ele recarrega e depois gasta no bot): a recarga é uma cobrança Pix normal com metadata como { "tipo": "recarga", "discord_user": "..." }. Quando chegar payment.succeeded, o bot soma o valor no saldo que ele mesmo guarda. Use o id do evento para não somar duas vezes. Funciona com a chave Só cobranças.

Saldo do vendedor (um bot com vários vendedores, e o dono do bot fica com uma comissão): cada vendedor vira uma subconta e cada venda manda a parte dele com splits. O dinheiro fica na conta de pagamento, não no bot:

1. Conecte uma conta que tenha subcontas (Pagar.me, Asaas, Woovi, Wyvi Pay ou Pagmaster).
2. Ao cadastrar um vendedor, crie a subconta (POST /v1/subaccounts) e guarde o id dele no bot. Dá para guardar o id do Discord em metadata.
3. Em cada venda, mande splits: [{ "subaccount_id": "sub_...", "percentage": 90 }]. A conta principal fica com o resto e paga as taxas.
4. O saldo do vendedor é GET /v1/subaccounts/:id/balance, e o saque (POST /v1/subaccounts/:id/withdrawals) só vai para a chave Pix dele, salva na criação.

Isso exige uma chave Completa, guardada só no servidor do dono do bot: chaves Só cobranças não dividem vendas, porque split é dinheiro indo para outra pessoa. Não use os saques normais para pagar vendedores: eles só vão para as chaves Pix salvas da sua empresa.