Presentes com significado, no seu site

Como o dinheiro funciona

O bday.fm funciona como o seu fornecedor de presentes e o seu banco: de cada presente pago, a divisão é sempre esta, para qualquer site:

A sua taxa de retenção é regra sua. O que você cobra dos seus criadores (10%, 20%, o que for), as comissões por indicação e as promoções ficam no seu site. O bday.fm não calcula nem guarda nada disso. Exemplo, com retenção de 10% num presente de R$ 10,00: o criador recebe R$ 9,00 de você, R$ 0,60 fica com você e R$ 0,40 é a taxa do bday.fm.

O valor aparece em bday.fm/carteira como “Repasse de criador (parceiro)”. Na Fábrica de presentes, cada presente criado por um usuário seu custa R$ 10,00 (Pix direto ao bday.fm) e 20% (R$ 2,00) entra no seu saldo como “Comissão de parceiro”.

• Retenção do bday.fm: hoje, 0 dias entre o pagamento e o saque. Enquanto estiver retido, o valor já aparece no saldo mas ainda não pode ser sacado (é a proteção contra devolução do Pix).
• Saque pelo seu site: pelo Painel bday ou pela API de saque, sem entrar no bday.fm. O saque sai só da carteira daquele site.
• Saque: você saca o seu saldo em dinheiro, para a chave Pix da sua conta (presa ao cadastro por segurança). O pedido chega para o bday.fm e o dinheiro cai em até 48 horas úteis. É preciso ter a identidade verificada.
• Seus usuários: pagar os criadores do seu site, os impostos e as regras internas é responsabilidade do seu site.
• Devolução: se um Pix for devolvido, você recebe o webhook gift.refunded e o valor é revertido do seu saldo, mesmo que você já tenha sacado (aí o saldo fica negativo até ser coberto). Desfaça o crédito do criador no seu site.

Virar parceiro

Qualquer site pode pedir adesão. Você precisa de uma conta no bday.fm (é ela que recebe o saldo) e faz a solicitação em três passos em bday.fm/parceiro:

1. O site: nome, endereço (https) onde o modal será instalado e uma descrição do site, do público e do tipo de conteúdo que ele publica.
2. Termos e privacidade: os endereços (https) dos termos de uso e da política de privacidade do seu site, mais o aceite dos termos de parceria.
3. Recebimento: saldo na sua carteira bday.fm com saque por Pix, e um e-mail de contato para os avisos.

O time do bday.fm avalia o pedido. Se for aprovado, as chaves e o segredo do webhook são criados sozinhos e o endereço do receptor já vem preenchido no seu domínio. Se não for, você recebe o motivo, pode ajustar o que for preciso e solicitar de novo, quantas vezes quiser.

Vários sites na mesma conta

Uma conta do bday.fm pode ter quantos sites quiser (até 10 pedidos ao mesmo tempo). Cada site é uma parceria à parte: é avaliado, aprovado, suspenso e configurado sozinho, com as próprias chaves, criadores e endereço de webhook. E cada site tem a sua carteira separada: saldo, extrato e saque próprios. O dinheiro de um site nunca se mistura com o de outro nem com a conta pessoal (presentes recebidos no bday.fm). O mesmo domínio não pode estar em duas parcerias.

Tudo isso fica em Ajustes (menu do seu nome, no canto superior direito) → Parcerias e lives: candidatar um novo site, acompanhar pedidos, reenviar um pedido recusado e abrir o painel de cada site ou o extrato consolidado.

O que é avaliado

• O site tem termos de uso e política de privacidade próprios, públicos e acessíveis.
• O conteúdo e o público descritos estão de acordo com a lei brasileira e com as políticas do bday.fm.
• O domínio informado é seu. O modal só abre nos domínios aprovados (o do site, com e sem www, mais até 4 extras que você informar).

Começo rápido

Com o pedido aprovado, abra bday.fm/parceiro e vá em Integração. Tudo já está preenchido para o seu site: chave pública, chave de teste, segredo do webhook e o endereço do receptor.

1. Coloque o botão no seu site

<script src="https://bday.fm/embed.js" data-key="pk_live_SUA_CHAVE" async></script>

<button data-bday-gift
        data-creator-ref="ID_DO_CRIADOR"
        data-creator-name="Nome do criador"
        data-creator-avatar="https://.../foto.jpg">
  Enviar presente
</button>

data-creator-ref é o id do criador no seu sistema. Ele volta para você no webhook, para você saber quem creditar.

2. Instale o receptor do webhook

É uma rota no seu servidor que confere a assinatura e recebe o aviso. O painel entrega o código pronto (Node, Next.js e PHP), e há um exemplo em Python mais abaixo. A única parte sua é somar o valor ao saldo do criador. Guarde o segredo numa variável de ambiente (BDAY_WEBHOOK_SECRET), nunca no código.

3. Teste sem gastar nada

No painel, mude o alternador para Teste, use o snippet com a chave pk_test_... e envie um presente: em vez de cobrar um Pix, o modal mostra “Simular pagamento aprovado”, e o seu receptor recebe o webhook de verdade. Veja Modo de teste.

4. Vá para produção

Troque a chave de teste pela chave real (pk_live_...) e pronto. Confira o checklist.

Modo de teste

O modo de teste percorre exatamente o mesmo caminho do pagamento real (estados, webhook assinado, criador, overlay), sem cobrar Pix e sem mexer em nenhum saldo. É o jeito de terminar a integração sem gastar dinheiro e sem aparecer para o público.

Como “pagar” um presente de teste

• No modal ou no link do criador: o botão Simular pagamento aprovado aparece no lugar do QR Code.
• No painel: em Transações (modo Teste), abra o presente e clique em Simular estorno para receber o gift.refunded.
• Pela API (com sk_test_): POST /api/v1/gifts/{id}/simulate com {"event": "paid"} ou {"event": "refunded"}.

Modal de presentes

O embed.js abre uma janela por cima da sua página. O fã escolhe o presente (com arte, animação, descrição, raridade e valor), informa só o nome e um recado e paga por Pix, tudo sem sair do seu site. O e-mail é exigido pelo Pix e nunca é enviado ao parceiro.

Botão sem JavaScript

Por JavaScript

BdayGifts.open({
  creatorRef: 'ID_DO_CRIADOR',
  creatorName: 'Nome do criador',
  creatorAvatar: 'https://.../foto.jpg',       // opcional
  onSuccess: function (d) {
    // d.transactionId, d.creatorRef, d.giftId, d.giftName, d.amountCents
  },
  onClose: function () {}                       // opcional
});

BdayGifts.close();                              // fecha por código
BdayGifts.init({ key: 'pk_live_SUA_CHAVE' });  // alternativa ao data-key do script

Requisitos

• Domínios: o modal só abre em domínios aprovados no seu pedido. Em outro site, o navegador bloqueia.
• Política de segurança (CSP): se o seu site usa CSP, libere script-src https://bday.fm e frame-src https://bday.fm.
• Celular: o modal ocupa a tela toda. Nenhum ajuste é necessário.
• Segurança: a chave pública (pk_...) pode ficar no HTML. Ela só abre o modal e nunca movimenta nada sozinha.

Criadores e link de presente

Cada criador do seu site ganha, sem você montar nada:

• Link de presente (https://bday.fm/c/abc123xyz9): a mesma tela do modal, em página inteira. Serve para a bio, o chat da live (por exemplo, um comando !presente) ou um QR Code na tela. Funciona até para quem não tem o modal instalado.
• QR Code e cartaz desse link, para a tela da live e para imprimir. Veja QR Code e cartaz.
• Três fontes para o OBS (https://bday.fm/overlay/ov_...): o alerta de presente, a barra de meta em tempo real e o QR Code fixo na tela.

Como o criador é cadastrado

• Sozinho: no primeiro presente pago, o criador já aparece no painel com os dois links.
• Pela API: cadastre antes do primeiro presente e mostre os links no painel do seu site.
• No painel: aba Criadores e live, seção “Cadastrar criador”.

curl -X PUT https://bday.fm/api/v1/creators/ID_DO_CRIADOR \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nome do criador", "avatar_url": "https://.../foto.jpg"}'

A resposta traz todos os endereços do criador (gift_page_url, overlay_url, goal_overlay_url, qr_overlay_url, qr_code_url e poster_url). O nome e a foto só mudam por aqui (o modal, por ser público, nunca altera um criador já cadastrado).

Overlay de live (OBS)

É uma das três fontes da live (as outras são a barra de meta e o QR Code). Ela faz o presente aparecer na transmissão: o presente animado, na cor da raridade, com “Ana enviou Lua de Presente”, o recado e um aviso sonoro. Vários presentes seguidos entram numa fila. O fundo é transparente.

Configurar no OBS (leva 1 minuto)

1. Em Fontes, clique em + e escolha Navegador.
2. Em URL, cole o overlay_url do criador.
3. Largura 1280 e altura 720 (ou o tamanho da sua cena).
4. Marque Controlar áudio via OBS se quiser ajustar o aviso sonoro na mesa de áudio.
5. Para posicionar, acrescente ?preview=1 ao endereço: um alerta de exemplo aparece a cada 10 segundos. Remova o ?preview=1 antes de entrar ao vivo.

É uma página web comum: qualquer programa de live com “fonte de navegador” (OBS Studio, Streamlabs e similares) consegue exibi-la.

Ajustes pelo endereço

Exemplo: https://bday.fm/overlay/ov_...?pos=top&vol=0.3&min=500

Meta em tempo real

Uma barra que mostra, na própria live, quanto já foi arrecadado de uma meta (“Novo microfone: R$ 1.000”). Ela enche a cada presente pago, com o valor subindo na tela, e fica dourada com uma comemoração quando a meta é batida.

Como definir

• No painel: Criadores e live → Preparar live → Meta: título e valor em reais.
• Pela API: PUT /api/v1/creators/{ref}/goal.

Regras

• Conta o valor pago pelos fãs (o gross_cents do presente), só dos presentes pagos depois que a meta começou.
• Se um Pix é devolvido, o valor sai da barra sozinho: o progresso é sempre calculado dos presentes pagos, nunca guardado.
• Cada criador tem uma meta ativa por vez. Definir outra encerra a atual e a barra recomeça do zero. Encerrar tira a barra da live.
• Valor de R$ 1,00 a R$ 1.000.000,00 e título de 2 a 80 caracteres.
• No modo de teste, a meta usa só presentes de teste.

Colocar no OBS

Uma fonte de navegador com o goal_overlay_url do criador (largura 1280, altura 720). Sem meta ativa, nada aparece na tela. Acrescente ?preview=1 para ver uma meta de exemplo que enche sozinha e posicionar a barra.

QR Code e cartaz

O público aponta o celular para o QR Code, escolhe o presente e paga por Pix, sem digitar endereço. Cada criador tem o QR Code do próprio link de presente em três formatos:

• Imagem (qr_code_url, por exemplo https://bday.fm/c/abc123xyz9/qr): um SVG que escala sem perder nitidez. No painel você baixa em SVG ou PNG.
• Na tela da live (qr_overlay_url): uma fonte de navegador do OBS que fixa o QR Code num canto, com o nome do criador e o link escrito.
• Cartaz para imprimir (poster_url): uma folha A4 com o QR Code grande, para eventos, lojas e vídeos.

Parâmetros da imagem

Ajustes do QR Code na live

Fábrica de presentes

Seus usuários criam presentes com a cara deles: mandam uma foto (eles mesmos, o pet, um bordão) e a IA transforma num presente 3D animado, no mesmo padrão do catálogo. Eles escolhem o nome e o preço.

Regras

• Preço fixo: R$ 10,00 por presente, pago por Pix direto ao bday.fm. 20% vai para o saldo do site e o resto paga a geração. É igual para todos os sites.
• Exclusivo: o presente nasce privado. Só aquele usuário, no seu site, pode recebê-lo (modal, link de presente, overlay e POST /api/v1/gifts).
• Liberar para todos é para sempre: se o usuário liberar, o presente passa a valer para toda a rede (bday.fm e todos os sites parceiros). Ele não volta a ser privado, fica sempre ativo e não pode ser arquivado. É preciso o aceite explícito.
• Deu errado, refaz de graça: se a criação falhar, o usuário ganha uma criação para refazer, sem pagar de novo.
• Quem recebe fica com o valor: quando alguém manda o presente, vale a divisão normal (96% para o saldo do site onde ele foi enviado).

Abrir a Fábrica para um usuário

Chame do seu servidor, com a chave secreta, quando o usuário clicar em “Criar presente”. Se o criador ainda não existir no bday.fm, mande creator_name que ele é cadastrado junto.

curl -X POST https://bday.fm/api/v1/fabrica/sessions \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"creator_ref": "ID_DO_USUARIO", "creator_name": "Nome", "email": "usuario@exemplo.com", "return_url": "https://seusite.com/painel"}'

{
  "object": "fabrica_session",
  "id": "fses_...",
  "livemode": true,
  "url": "https://bday.fm/fabrica/fs_live_...",
  "expires_at": "2026-11-01T22:00:00.000Z",
  "creator": { "ref": "ID_DO_USUARIO", "name": "Nome" },
  "price_cents": 1000,
  "partner_share_cents": 200
}

Abra a url numa aba ou dentro do seu site. O link vale por algumas horas e só serve para aquele usuário: peça um novo a cada vez. email é opcional (o Pix pede; sem ele, a janela pergunta).

<iframe src="URL_DA_SESSAO" style="width:100%;height:860px;border:0" allow="clipboard-write"></iframe>

Presentes e compras pela API

Lista os presentes criados (do mais novo para o mais antigo). status: queued, drawing, animating, ready ou failed. gift_id é o id que vai no modal e em POST /api/v1/gifts.

Muda name, description, price_cents e active. Para liberar para todos: {"public": true, "accept_public_terms": true} (só com o aceite do usuário; não tem volta).

As compras da Fábrica: status (pending, paid, expired, refunded), amount_cents e partner_cents (o que entrou no seu saldo).

Só com sk_test_: simula o pagamento. No modo de teste nada é cobrado nem gerado: o presente fica pronto na hora com uma arte de exemplo, e não pode ser liberado.

Relatórios e extrato

Tudo o que aconteceu com os presentes, organizado no painel do parceiro e disponível em CSV. Cada tela tem o alternador de site (e, com mais de um, “Todos os sites”) e o de Real/Teste.

Relatórios

• Resumo do período: presentes, valor recebido, o que entrou no seu saldo, a taxa do bday.fm, apoiadores, presente médio, maior presente e devoluções.
• Evolução por dia em gráfico, e os rankings de criadores, presentes, apoiadores e, com vários sites, sites.
• Período: 7, 30 ou 90 dias, este mês ou datas à sua escolha (até 366 dias), em horário de Brasília, e filtro por criador.
• Um presente devolvido fica no período em que foi pago e aparece à parte, fora dos totais.
• Os apoiadores são agrupados pelo nome que o fã informou (“Beto” e “beto” são a mesma pessoa), já que o fã não precisa ter conta.

Extrato

• Cada lançamento no seu saldo vindo dos sites: repasse dos presentes, comissão da Fábrica de presentes e devoluções, um por lançamento, com site, criador, apoiador e presente.
• A situação de cada crédito: em retenção (até a data de liberação), disponível ou anulado pela devolução.
• Totais do período (repasses, comissões da Fábrica, devoluções e líquido) e o saldo da conta, que é exatamente o da Carteira.
• Só dinheiro real: o modo de teste nunca gera lançamento.

Transações

A lista de presentes com o detalhe de cada um (a divisão do valor e o histórico de entrega do webhook), com exportação em CSV respeitando o site, o período e o criador escolhidos.

Para conciliar no seu próprio sistema, use a API: GET /api/v1/gifts?paid_since=....

Webhooks

A cada presente pago (e a cada devolução), o bday.fm faz um POST assinado para o seu servidor. É por aqui que você credita o criador. O mesmo endereço também recebe os avisos da Fábrica de presentes, dos saques do site e das versões novas da API.

Endereço

• Já vem preenchido no seu domínio (https://seusite.com/bday/webhook): você não cria subdomínio, DNS nem certificado. Só coloca o receptor nessa rota.
• Precisa ser https, ter nome de domínio (não IP) e estar no seu domínio aprovado ou num subdomínio dele.
• Não seguimos redirecionamentos. Se a rota redireciona (por exemplo, para uma tela de login), a entrega falha. Deixe a rota pública.
• Responda com qualquer 2xx em até 8 segundos. Faça o trabalho pesado depois de responder.

No painel, o botão Verificar instalação envia um aviso ping e mostra, em português, o que o seu servidor respondeu.

Cabeçalhos

Eventos

{
  "id": "cmu9x2k3a0001abc",
  "type": "gift.confirmed",
  "livemode": true,
  "created_at": "2026-09-20T15:04:05.000Z",
  "data": {
    "transaction_id": "cmu9x2k3a0000xyz",
    "paid_at": "2026-09-20T15:04:05.000Z",
    "giver": { "name": "Maria" },
    "recipient": { "ref": "ID_DO_CRIADOR", "name": "Nome do criador" },
    "message": "Adorei a live de hoje!",
    "gift": {
      "id": "gi_lua",
      "name": "Lua de Presente",
      "description": "Uma lua para iluminar o seu dia.",
      "rarity": "lendario",
      "category": "premium",
      "emoji": "🌙",
      "image_url": "https://bday.fm/api/img/presentes/gi_lua.webp",
      "animation_url": "https://bday.fm/api/img/presentes/gi_lua.mp4"
    },
    "amounts": {
      "currency": "BRL",
      "gross_cents": 12000,
      "creator_cents": 11520,
      "partner_commission_cents": 0,
      "platform_cents": 480
    }
  }
}

O gift.refunded tem o mesmo formato, com "type": "gift.refunded" e o campo extra data.refunded_at. O ping traz apenas data.message.

Como conferir a assinatura

Sem conferir, qualquer pessoa que descubra o seu endereço poderia forjar “presentes” e você creditaria dinheiro que não existe. Faça sempre:

1. Leia X-Bday-Signature e separe t (timestamp) e v1 (assinatura).
2. Use o corpo bruto, exatamente como chegou (antes de qualquer JSON.parse ou reformatação).
3. Calcule HMAC-SHA256 com o seu segredo (whsec_...) sobre o texto t + "." + corpo, em hexadecimal.
4. Compare com v1 em tempo constante (timingSafeEqual, hash_equals, compare_digest).
5. Recuse se o t for mais velho que 5 minutos (protege contra reenvio de uma mensagem antiga).

const crypto = require('crypto');

// Registre esta rota ANTES de app.use(express.json()): a assinatura vale para o corpo exato.
app.post('/bday/webhook', express.raw({ type: '*/*' }), async (req, res) => {
  const raw = req.body.toString('utf8');
  const h = Object.fromEntries((req.get('X-Bday-Signature') || '').split(',').map(p => p.split('=')));
  const esperado = crypto.createHmac('sha256', process.env.BDAY_WEBHOOK_SECRET)
    .update(h.t + '.' + raw).digest('hex');
  const valida = h.v1 && esperado.length === h.v1.length &&
    crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(h.v1)) &&
    Math.abs(Date.now() / 1000 - Number(h.t)) < 300;
  if (!valida) return res.sendStatus(401);

  const ev = JSON.parse(raw);
  if (ev.type !== 'ping') await tratarEvento(ev);
  res.sendStatus(200);
});

async function tratarEvento(ev) {
  // ev.id: guarde para não processar duas vezes.
  // ev.livemode === false: presente de TESTE, não credite saldo real.
  const criadorId = ev.data.recipient.ref;
  const centavos = ev.data.amounts.creator_cents;
  const sinal = ev.type === 'gift.refunded' ? -1 : 1;
  // TODO: some (sinal * centavos) ao saldo do criador criadorId.
}

// app/bday/webhook/route.ts
import crypto from 'crypto';

export async function POST(req: Request) {
  const raw = await req.text();
  const h = Object.fromEntries((req.headers.get('x-bday-signature') || '').split(',').map(p => p.split('=')));
  const esperado = crypto.createHmac('sha256', process.env.BDAY_WEBHOOK_SECRET!)
    .update(h.t + '.' + raw).digest('hex');
  const valida = h.v1 && esperado.length === h.v1.length &&
    crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(h.v1)) &&
    Math.abs(Date.now() / 1000 - Number(h.t)) < 300;
  if (!valida) return new Response(null, { status: 401 });

  const ev = JSON.parse(raw);
  if (ev.type !== 'ping') await tratarEvento(ev);
  return new Response(null, { status: 200 });
}

async function tratarEvento(ev: any) {
  // ev.id: guarde para não processar duas vezes.
  // ev.livemode === false: presente de TESTE, não credite saldo real.
  const criadorId = ev.data.recipient.ref;
  const centavos = ev.data.amounts.creator_cents;
  const sinal = ev.type === 'gift.refunded' ? -1 : 1;
  // TODO: some (sinal * centavos) ao saldo do criador criadorId.
}

<?php
$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_BDAY_SIGNATURE'] ?? ''), $h);
$esperado = hash_hmac('sha256', ($h['t'] ?? '') . '.' . $raw, getenv('BDAY_WEBHOOK_SECRET'));
if (!isset($h['v1']) || !hash_equals($esperado, $h['v1']) || abs(time() - (int)($h['t'] ?? 0)) > 300) {
  http_response_code(401); exit;
}

$ev = json_decode($raw, true);
if ($ev['type'] !== 'ping') {
  // $ev['id']: guarde para não processar duas vezes.
  // $ev['livemode'] === false: presente de TESTE, não credite saldo real.
  $criadorId = $ev['data']['recipient']['ref'];
  $centavos = $ev['data']['amounts']['creator_cents'];
  $sinal = $ev['type'] === 'gift.refunded' ? -1 : 1;
  // TODO: some ($sinal * $centavos) ao saldo do criador $criadorId.
}
http_response_code(200);

import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)

def assinatura_valida(raw: bytes, cabecalho: str, segredo: str) -> bool:
    try:
        partes = dict(p.split("=", 1) for p in cabecalho.split(","))
        ts = int(partes["t"])
    except (ValueError, KeyError):
        return False
    esperado = hmac.new(segredo.encode(), str(ts).encode() + b"." + raw, hashlib.sha256).hexdigest()
    return abs(time.time() - ts) <= 300 and hmac.compare_digest(esperado, partes.get("v1", ""))

@app.post("/bday/webhook")
def bday_webhook():
    raw = request.get_data()   # o corpo exato, sem reformatar
    if not assinatura_valida(raw, request.headers.get("X-Bday-Signature", ""), os.environ["BDAY_WEBHOOK_SECRET"]):
        abort(401)
    ev = request.get_json()
    if ev["type"] != "ping":
        # ev["id"]: guarde para não processar duas vezes.
        # ev["livemode"] is False: presente de TESTE, não credite saldo real.
        criador_id = ev["data"]["recipient"]["ref"]
        centavos = ev["data"]["amounts"]["creator_cents"]
        sinal = -1 if ev["type"] == "gift.refunded" else 1
        # TODO: some (sinal * centavos) ao saldo do criador criador_id.
    return "", 200

Vetor de teste

Para conferir a sua implementação sem esperar um presente, use estes valores. O resultado do seu cálculo precisa ser idêntico:

segredo   whsec_exemplo_123
t         1700000000
corpo     {"id":"evt_exemplo","type":"ping"}
v1        4548b70b240017ffc45598e01898a6e4f00a9d792c0102a2fb6c49ccf022e386

(A verificação de horário, que recusa mensagens com mais de 5 minutos, falhará para esse t antigo: teste só o cálculo do HMAC.)

Reentregas e idempotência

• Se o seu servidor não responder 2xx, o bday.fm tenta de novo com espera crescente: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h, num total de 8 tentativas (cerca de 2 dias). Depois disso o evento fica como “Falhou” e você pode reenviá-lo pelo painel (Transações → abrir a transação → Reenviar webhook).
• O mesmo evento pode chegar mais de uma vez. Guarde o id do evento (ou o par transaction_id + type) e ignore o que já processou.
• Cada presente gera no máximo um gift.confirmed e um gift.refunded.
• Se o seu servidor ficou fora do ar, concilie pela API: GET /api/v1/gifts?paid_since=....

API de servidor (v1)

Para o seu servidor cadastrar criadores, conciliar presentes e (no modo de teste) simular pagamentos. Endereço base: https://bday.fm. Especificação completa: openapi.json.

Autenticação

Crie uma chave secreta no painel (aba API). Ela aparece uma única vez: copie na hora. Envie no cabeçalho:

Authorization: Bearer sk_live_SUA_CHAVE

• sk_live_... vê e altera dados reais. sk_test_... só enxerga o modo de teste.
• Nunca coloque a chave secreta no navegador, em app mobile ou em repositório público. Se vazar, revogue no painel e crie outra.
• Você pode ter até 5 chaves ativas por modo (útil para trocar sem parada) e revogar cada uma sozinha.

Confere a chave e devolve as regras vigentes. É o melhor primeiro teste.

curl https://bday.fm/api/v1/me -H "Authorization: Bearer sk_test_SUA_CHAVE"

{
  "site_name": "Meu Site",
  "livemode": false,
  "split": { "creator_percent": 96, "partner_percent": 0, "platform_percent": 4 },
  "hold_days": 0,
  "fees": { "platform_percent": 4, "net_percent": 96 },
  "fabrica": { "price_cents": 1000, "partner_share_percent": 20, "partner_share_cents": 200 },
  "api_version": "1.2.0"
}

split.creator_percent é o que entra no seu saldo (o nome vem da primeira versão da API e foi mantido para não quebrar integrações). Prefira fees.net_percent.

Os presentes disponíveis, com arte, animação, descrição, raridade e preço. Só entram presentes virtuais e pagos.

{
  "object": "list",
  "data": [
    {
      "id": "gi_lua", "name": "Lua de Presente", "description": "...", "rarity": "lendario",
      "category": "premium", "emoji": "🌙", "price_cents": 12000, "currency": "BRL",
      "image_url": "https://bday.fm/api/img/presentes/gi_lua.webp",
      "animation_url": "https://bday.fm/api/img/presentes/gi_lua.mp4"
    }
  ],
  "has_more": false
}

Cadastra ou atualiza um criador (idempotente). {ref} é o id dele no seu sistema: letras, números e . _ : @ -, até 80 caracteres. Corpo: name (obrigatório, até 80) e avatar_url (opcional, https).

curl -X PUT https://bday.fm/api/v1/creators/lia_01 \
  -H "Authorization: Bearer sk_test_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lia", "avatar_url": "https://cdn.exemplo.com/lia.jpg"}'

{
  "ref": "lia_01",
  "name": "Lia",
  "avatar_url": "https://cdn.exemplo.com/lia.jpg",
  "livemode": false,
  "gift_page_url": "https://bday.fm/c/k3j9x2m8ab",
  "overlay_url": "https://bday.fm/overlay/ov_Xk3...",
  "goal_overlay_url": "https://bday.fm/overlay/ov_Xk3.../meta",
  "qr_overlay_url": "https://bday.fm/overlay/ov_Xk3.../qr",
  "qr_code_url": "https://bday.fm/c/k3j9x2m8ab/qr",
  "poster_url": "https://bday.fm/c/k3j9x2m8ab/cartaz",
  "created_at": "2026-09-20T15:00:00.000Z"
}

Consulta um criador (mesmo formato acima). 404 se não existir naquele modo.

Lista os criadores, dos mais novos para os mais antigos. Parâmetros: limit (1 a 100, padrão 25) e starting_after (o ref do último criador da página anterior). A resposta tem data e has_more.

Gera um novo overlay_url (e, junto, os de meta e QR Code da live) e desativa o anterior na hora. Devolve o criador.

Define a meta do criador. Se já havia uma ativa, ela é encerrada e a barra recomeça do zero: só conta o que for pago depois. Corpo: title (2 a 80 caracteres) e target_cents (inteiro, de 100 a 100000000).

curl -X PUT https://bday.fm/api/v1/creators/ID_DO_CRIADOR/goal \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"title": "Novo microfone", "target_cents": 100000}'

{
  "id": "cmu9x2k3a0007abc",
  "title": "Novo microfone",
  "target_cents": 100000,
  "current_cents": 35000,
  "remaining_cents": 65000,
  "percent": 35,
  "reached": false,
  "supporters": 4,
  "started_at": "2026-09-21T18:00:00.000Z",
  "reached_at": null,
  "last": { "giver": "Maria", "gift": "Lua de Presente", "amount_cents": 12000, "paid_at": "2026-09-21T18:40:00.000Z" },
  "widget_url": "https://bday.fm/overlay/ov_Xk3.../meta"
}

Devolve a meta ativa com o progresso de agora (mesmo formato acima), ou 404 se o criador não tem meta. É o que você chama para mostrar a barra também no seu site.

Encerra a meta ativa: a barra some da live. 404 se não havia meta.

Lista presentes para conciliar, do mais novo para o mais antigo.

curl "https://bday.fm/api/v1/gifts?status=paid&paid_since=2026-09-20T00:00:00Z&limit=50" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE"

Consulta um presente. O id é o mesmo transaction_id do webhook. Formato em Objeto presente.

Só com sk_test_. Simula o que o Pix faria: {"event": "paid"} paga o presente de teste e {"event": "refunded"} o devolve. Em ambos os casos o webhook assinado é enviado ao seu receptor.

curl -X POST https://bday.fm/api/v1/gifts/ID_DO_PRESENTE/simulate \
  -H "Authorization: Bearer sk_test_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"event": "paid"}'

Saldo, extrato e saque

Cada site tem a sua carteira. Com a chave secreta do site, o seu servidor lê o saldo, o extrato discriminado e pede saques, sem ninguém entrar no bday.fm. Tudo vale só para o site da chave.

{
  "object": "balance",
  "livemode": true,
  "currency": "BRL",
  "site": { "id": "...", "name": "Meu Site", "url": "https://meusite.com" },
  "total_cents": 159200,
  "held_cents": 19200,
  "available_cents": 140000,
  "pending_withdrawals_cents": 1000
}

held_cents é o que ainda está em retenção (0 dias depois do pagamento). available_cents é o que dá para sacar agora. pending_withdrawals_cents são saques pedidos e ainda não pagos (já descontados).

O extrato do site, do mais novo para o mais antigo. Filtros: from e to (data ISO), type (um ou mais, separados por vírgula), limit (até 5000) e format=csv (planilha pronta, separada por ponto e vírgula).

curl -X POST https://bday.fm/api/v1/withdrawals \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 50000, "idempotency_key": "saque-2026-11-01-01"}'

• O dinheiro vai para a chave Pix da conta (travada por segurança) e cai em até 48 horas úteis.
• Sai só da carteira do site. Se faltar saldo, a resposta é 402 insufficient_balance com available_cents.
• Regras: saque mínimo da plataforma, até 2 saques por semana por site, 2 grátis por mês e depois uma taxa fixa por saque (o painel mostra os valores atuais).
• idempotency_key é obrigatória: repetir a mesma chave devolve o mesmo saque, sem pedir de novo.
• A conta precisa ter a identidade confirmada e a chave Pix cadastrada (uma vez só, em bday.fm/carteira). Sem isso: verificacao_pendente ou sem_chave_pix.
• Com sk_test_ nada é sacado: a resposta simula um saque pago.

Os saques do site. status: requested, processing, paid, failed ou rejected (nos dois últimos o valor voltou para o saldo). Você também recebe os webhooks withdrawal.*.

Painel bday no seu admin

Uma janela pronta, do bday.fm, para abrir dentro do admin do seu site: saldo, extrato com filtro e CSV, saque, vendas da Fábrica, forma do alerta da live e novidades da API. Ela se atualiza sozinha: quando o bday.fm melhora o painel, o seu admin já mostra.

curl -X POST https://bday.fm/api/v1/panel/sessions -H "Authorization: Bearer sk_live_SUA_CHAVE"

{ "object": "panel_session", "livemode": true, "url": "https://bday.fm/painel-parceiro/pp_live_...", "expires_at": "..." }

Chame do seu servidor quando um administrador do seu site abrir a área financeira e coloque a url num iframe (ou abra numa aba). O link vale por 2 horas: peça um novo a cada vez.

<iframe src="URL_DO_PAINEL" style="width:100%;height:900px;border:0"></iframe>

Manifesto e botão “Atualizar API bday”

O manifesto é um retrato de tudo o que o bday.fm oferece agora: versão da API, taxas, Fábrica, formas de alerta, eventos de webhook e novidades. Ele é público e não precisa de chave. Com a chave secreta, vem também a configuração do seu site.

{
  "api_version": "1.2.0",
  "updated_at": "2026-11-01T12:00:00.000Z",
  "docs_url": "https://bday.fm/parceiros/docs",
  "openapi_url": "https://bday.fm/api/v1/openapi.json",
  "fees": { "platform_percent": 4, "net_percent": 96, "hold_days": 0 },
  "fabrica": { "enabled": true, "price_cents": 1000, "partner_share_percent": 20, "partner_share_cents": 200 },
  "alerts": { "styles": [ { "id": 1, "name": "Centro da tela" }, { "id": 2, "name": "Cartão no canto" } ] },
  "webhook_events": [ "gift.confirmed", "gift.refunded", "fabrica.purchase.paid", "..." ],
  "changelog": [ { "version": "1.2.0", "date": "2026-11-01", "items": [ "..." ] } ]
}

O botão no admin do seu site

O código da integração roda no seu servidor e só você pode mudá-lo. O que o botão faz é buscar o manifesto, guardar as regras (taxa, preço da Fábrica, forma do alerta) no seu site e mostrar o que há de novo. A Fábrica, o modal e o overlay são do bday.fm e se atualizam sozinhos.

// Node: rota chamada pelo botão "Atualizar API bday" do seu admin
app.post('/admin/bday/atualizar', async (req, res) => {
  const r = await fetch('https://bday.fm/api/v1/manifest', {
    headers: { Authorization: 'Bearer ' + process.env.BDAY_SECRET_KEY }
  });
  const m = await r.json();
  await config.salvar('bday', {
    versao: m.api_version,
    taxa: m.fees.platform_percent,             // hoje 4
    fabrica_preco: m.fabrica.price_cents,       // hoje 1000
    forma_alerta: m.site ? m.site.alert_style : 1
  });
  res.json({ ok: true, versao: m.api_version, novidades: m.changelog[0] });
});

<?php // PHP
$ch = curl_init('https://bday.fm/api/v1/manifest');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('BDAY_SECRET_KEY')]]);
$m = json_decode(curl_exec($ch), true);
salvar_config('bday_versao', $m['api_version']);
salvar_config('bday_taxa', $m['fees']['platform_percent']);
salvar_config('bday_fabrica_preco', $m['fabrica']['price_cents']);

Para nem precisar clicar: trate o webhook api.updated chamando a mesma rotina. Ele chega quando sai uma versão nova, com data.api_version e a lista de novidades.

Objeto presente

É o mesmo formato na API (GET /api/v1/gifts) e dentro de data nos webhooks (onde id aparece como transaction_id).

Valores são sempre inteiros em centavos (nunca decimais), em BRL.

Erros e limites

Toda falha da API v1 tem o mesmo formato:

{ "error": { "code": "invalid_request", "message": "avatar_url precisa ser um endereço https válido (até 300 caracteres)." } }

Segurança

• Confira a assinatura de todo webhook e recuse mensagens com mais de 5 minutos.
• Credite só pelo webhook (ou pela API), nunca pelo onSuccess do navegador.
• Segredos em variáveis de ambiente: whsec_... e sk_... nunca vão no código nem no navegador. Se um vazar, gere outro no painel.
• Seja idempotente: guarde o id do evento e ignore repetidos.
• Escape nome do fã e recado antes de exibir.
• Trate o overlay_url como segredo e troque se vazar.
• Não pedimos o e-mail do fã. O que você recebe é só nome, recado e presente.

Ir para produção

1. O receptor confere a assinatura e responde 2xx (o botão Verificar instalação do painel passa).
2. Você já testou um presente de teste ponta a ponta e viu o gift.confirmed e o gift.refunded chegarem.
3. O receptor ignora eventos repetidos e trata livemode: false sem creditar saldo real.
4. O snippet do botão usa a chave real (pk_live_...).
5. A sua chave secreta real (sk_live_...) está só no servidor.
6. O criador colou o overlay_url no OBS e viu o alerta de exemplo (?preview=1).
7. Sua conta bday.fm tem a identidade verificada e a chave Pix cadastrada, para poder sacar.

Perguntas frequentes

Preciso de CNPJ?

Não. Basta ter uma conta no bday.fm, que é onde o seu saldo é recebido e sacado por Pix.

O fã precisa ter conta no bday.fm?

Não. Ele escolhe o presente, informa o nome como quer aparecer (e, se quiser, um recado) e paga. O e-mail é pedido só porque o Pix exige, e nunca é enviado ao seu site.

O criador precisa ter conta no bday.fm?

Não. O criador só existe no seu site: o valor dele cai no seu saldo e você o credita lá. Quem precisa de conta no bday.fm é o site: é nela que fica o saldo.

Posso escolher quais presentes aparecem?

O catálogo é o mesmo para todos os parceiros: o modal mostra todos os presentes virtuais pagos dele, incluindo os que usuários criaram na Fábrica e liberaram para todos. Além disso, cada criador vê os presentes exclusivos que criou na Fábrica: eles aparecem só no modal, no link e na live dele.

A taxa do bday.fm muda de um site para outro?

Não. É 4% para todos os sites parceiros e lives. O que muda de site para site é a sua taxa de retenção, que é regra sua e fica no seu site.

Meus usuários podem criar os próprios presentes?

Sim, pela Fábrica de presentes. Cada presente custa R$ 10,00 (Pix direto ao bday.fm) e 20% entra no seu saldo. O presente nasce exclusivo do usuário que criou.

Como fico sabendo das novidades da API?

Pelo webhook api.updated e pelo manifesto. O jeito mais simples é um botão “Atualizar API bday” no admin do seu site.

O que acontece se o fã pedir a devolução do Pix?

Você recebe o gift.refunded e o valor sai do seu saldo. Desfaça o crédito do criador no seu site. Se você já tiver sacado, o saldo fica negativo até ser coberto; por isso vale segurar o repasse aos seus criadores pelo prazo que achar seguro.

O overlay funciona com Streamlabs, Meld e outros?

Ele é uma página web comum, então qualquer programa de live que tenha “fonte de navegador” consegue exibi-lo. O passo a passo acima é o do OBS Studio.

Posso ter mais de um site na mesma conta?

Sim, até 10 pedidos ao mesmo tempo. Cada site é uma parceria à parte, com chaves, criadores e webhook próprios, e com a carteira própria: saldo, extrato e saque separados, sem misturar com os outros sites nem com a conta pessoal. Peça em Ajustes → Parcerias e lives → Adicionar outro site.

Como mostro a meta e o QR Code na minha live?

No painel, em Criadores e live, clique em Preparar live no criador. Lá estão os endereços das três fontes do OBS (alerta, meta e QR Code), com “ver exemplo”, e a definição da meta. Veja Meta em tempo real e QR Code e cartaz.

Onde vejo o extrato do dinheiro que entrou?

No painel, na aba Extrato (por site ou de todos os sites juntos), com cada repasse, comissão da Fábrica e devolução ligados ao presente. O saldo é o mesmo da sua Carteira. Veja Relatórios e extrato.

Quantos criadores posso ter?

Não há limite de criadores.

Onde vejo tudo o que aconteceu?

No painel, em Transações: lista, detalhe de cada presente, histórico de entrega do webhook e exportação em CSV. Você também recebe um e-mail a cada presente confirmado.

Preciso de ajuda com a integração.

Escreva para contato@bday.fm contando o endereço do seu site e, se possível, o que apareceu no botão Verificar instalação.

Novidades

1 de novembro de 2026 · API 1.2.0

• Carteira separada por site: cada site tem saldo, extrato e saque próprios, mesmo com vários sites na mesma conta.
• Saldo, extrato e saque pela API: /api/v1/balance, /api/v1/statement (com CSV) e /api/v1/withdrawals, mais os webhooks withdrawal.*.
• Painel bday para o admin do seu site (POST /api/v1/panel/sessions): o site faz tudo sem entrar no bday.fm.

1 de novembro de 2026 · API 1.1.0

• Taxa única de 4%: 96% de cada presente entra no saldo do site. A comissão separada deixou de existir (partner_commission_cents agora é sempre 0).
• Fábrica de presentes: seus usuários criam presentes 3D a partir de uma foto, por R$ 10,00, e 20% entra no seu saldo. Rotas /api/v1/fabrica/* e webhooks fabrica.*.
• Manifesto da API (GET /api/v1/manifest) e webhook api.updated, para o botão “Atualizar API bday”.
• GET /api/v1/me ganhou fees, fabrica e api_version (mudança compatível).
• Presentes criados e liberados para todos ficam disponíveis para toda a rede, no catálogo e no modal.

21 de setembro de 2026

• Ajustes no menu da conta: central com o pedido de parceria, os sites da conta e o acesso ao painel e ao extrato.
• Vários sites por conta: cada site é uma parceria à parte, com o saldo da conta em comum.
• Meta em tempo real para a live, com a API /api/v1/creators/{ref}/goal.
• QR Code do link de presente (imagem SVG, fonte do OBS e cartaz para imprimir).
• Relatórios e extrato organizados por período, criador, presente, apoiador e site.
• O objeto do criador na API ganhou os campos goal_overlay_url, qr_overlay_url, qr_code_url e poster_url (mudança compatível).

20 de setembro de 2026

• Modo de teste: chaves pk_test_ e sk_test_, simulação de pagamento e estorno, sem cobrança e sem mexer em saldo.
• API de servidor v1 com chave secreta: /me, /catalog, /creators, /gifts e /simulate, mais a especificação OpenAPI.
• Criadores, link de presente e overlay de live para OBS.
• Webhooks: novo campo livemode no corpo. Mudança compatível: quem ignora campos desconhecidos não precisa mexer em nada.

19 de setembro de 2026

• Lançamento do programa de parceiros: modal de presentes, webhooks assinados e painel do parceiro.