Developers

Saques (Payouts)

A PaysClub permite que criadores, coprodutores e afiliados solicitem saques do saldo disponível. Cada perfil tem seu próprio endpoint de balance + withdrawal, e a chave PIX é cadastrada no perfil do usuário.

Pré-requisito: a chave PIX precisa estar cadastrada (POST /api/profile/pix) e verificada antes que qualquer saque seja processado. A API retorna 403 com mensagem clara se ainda não estiver.

Cadastrar/atualizar chave PIX

PATCH/api/profile/pix

Atualiza a chave PIX do usuário autenticado. Ao mudar a chave, o flagpix_verified é resetado pra false e precisa ser re-aprovado antes de novos saques.

Body

pix_keystringobrigatório

Chave PIX (1 a 140 caracteres)

pix_key_typeenumobrigatório

Um de: cpf, cnpj, email, phone, random

Exemplo
curl -X PATCH https://app.paysclub.com/api/profile/pix \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "pix_key": "12345678900",
    "pix_key_type": "cpf"
  }'

# 200 OK
{ "success": true, "pix_verified": false }

Saldo do criador

O saldo disponível do criador é calculado descontando automaticamente:

Cálculo
available = paid_total
          − refunded_total
          − withdrawn_total      (saques pending+approved+paid)
          − coproducer_owed      (splits ainda não sacados)
          − affiliate_owed       (commissions ainda não sacadas)
O criador não consegue sacar a parte que pertence a coprodutores ou afiliados. Cada perfil saca o que é dele com sua própria chave PIX.

Solicitar saque (criador)

POST/api/withdrawals

Body

tenant_iduuidobrigatório

ID do tenant

amountnumberobrigatório

Valor do saque (mínimo R$ 20,00)

Exemplo
curl -X POST https://app.paysclub.com/api/withdrawals \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "tenant_id": "550e8400-...", "amount": 100.00 }'

# Possíveis erros
# 400 — "Cadastre uma chave Pix antes de solicitar saque"
# 403 — "Sua chave Pix está aguardando verificação"
# 403 — "Sua chave Pix foi rejeitada: <motivo>"
# 409 — "Você já tem um saque pendente"
# 400 — "Saldo insuficiente"

Saldo + saque do coprodutor

GET/api/coproducers/balance

Retorna o saldo do coprodutor logado, agregado de todos os splits que ele participa.

Resposta
{
  "available": 450.00,
  "earned_total": 1200.00,
  "refunded_total": 50.00,
  "withdrawn": 700.00
}
POST/api/coproducers/withdraw

Body

amountnumberobrigatório

Valor do saque

Exemplo
curl -X POST https://app.paysclub.com/api/coproducers/withdraw \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 200.00 }'

# 200 OK
{ "success": true, "withdrawal_id": "...", "balance_before": 450.00 }

Saldo + saque do afiliado

GET/api/affiliates/balance
Resposta
{
  "available": 90.00,
  "paid_total": 150.00,
  "rejected_total": 10.00,
  "pending_count": 2,
  "withdrawn": 60.00
}
POST/api/affiliates/withdraw
Exemplo
curl -X POST https://app.paysclub.com/api/affiliates/withdraw \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50.00 }'

# 200 OK
{ "success": true, "withdrawal_id": "...", "balance_before": 90.00 }

Estados de um saque

State machine
pending  → solicitação recebida, em análise
approved → aprovado, transferência em processamento
paid     → PIX efetuado com sucesso
rejected → rejeitado (motivo retornado no campo "admin_note" da resposta)