Comissão de plataforma

Uma plataforma que vende em nome de outros comerciantes (um marketplace de hotéis, uma montra de lojistas) recebe o pagamento na conta de cada comerciante, e fica com uma comissão no próprio pagamento, sem faturar à parte. O comerciante é dono do dinheiro e do saldo dele; a plataforma é outro comerciante do Vibra Pay, e a comissão entra no saldo dela.

Só com consentimento: o comerciante autoriza a plataforma no painel dele, em Plataformas, com o identificador dela (mer_...) e uma comissão máxima em percentagem (até 50%). Revoga quando quiser. A autorização vale no modo teste e no modo produção.

A plataforma cria a sessão com a chave de API do comerciante, como sempre, e acrescenta platform_fee: o identificador da plataforma e o valor, em unidades menores da moeda da sessão (em AOA, kwanzas inteiros).

curl -s "$VIBRA_API_URL/v1/checkout/sessions" \
  -H "Authorization: Bearer $CHAVE_DO_HOTEL" \
  -H "Idempotency-Key: reserva-8841" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500000,
    "currency": "AOA",
    "description": "Duas noites, quarto duplo",
    "platform_fee": {"platform": "mer_38IAs7qmknSwC1F9XYtR1b", "amount": 150000}
  }'

sessao, err := hotel.CheckoutSessions.Create(ctx, vibra.CheckoutSessionParams{
	Amount:      1500000,
	Currency:    "AOA",
	Description: "Duas noites, quarto duplo",
	PlatformFee: &vibra.PlatformFee{Platform: "mer_38IAs7qmknSwC1F9XYtR1b", Amount: 150000},
}, vibra.WithIdempotencyKey("reserva-8841"))

A sessão devolvida traz platform_fee (ou null, sem comissão). Numa sessão com kind subscription, a comissão fica guardada na subscrição e repete-se em cada renovação, incluindo as que o cartão paga sozinho.

Quando o pagamento se confirma, o mesmo movimento do livro credita a plataforma pela comissão e debita o comerciante, ao lado do bruto e da taxa. A taxa do Vibra Pay calcula-se sobre o bruto e é do comerciante. O net do payment.succeeded é o que fica ao comerciante: o bruto menos a taxa e menos a comissão.

{
  "type": "payment.succeeded",
  "data": {
    "object": {
      "id": "pay_...",
      "amount": {"amount": 1500000, "currency": "AOA"},
      "fee": {"amount": 37500, "currency": "AOA"},
      "net": {"amount": 1312500, "currency": "AOA"},
      "settlement": "balance",
      "platform_fee": {"platform": "mer_38IAs7qmknSwC1F9XYtR1b", "amount": 150000},
      "...": "..."
    }
  }
}

• A comissão segue a retenção do comerciante: fica no pendente da plataforma e passa a disponível no mesmo dia em que o líquido do comerciante passa.
• Num estorno, a comissão volta ao comerciante em proporção ao que se estornou (arredondada a favor dele), do saldo da plataforma, no mesmo movimento. Num estorno total volta toda, e nunca mais do que a plataforma recebeu.
• Os extratos dos dois mostram-na: ao comerciante, a comissão paga e a quem; à plataforma, a comissão recebida, com o pagamento de origem e o nome do comerciante.

A autorização confere-se outra vez quando o pagamento se confirma, e em cada renovação de uma subscrição. Revogada (ou revogada e dada outra vez com um máximo menor), o pagamento entra sem comissão, e o payment.succeeded diz platform_fee: null e platform_fee_skipped: