Payout From Subaccount
Envia PIX para fora debitando ESTA subconta. O dinheiro sai da carteira da conta principal (é ela que tem lastro), mas a atribuição é da subconta: o saldo dela é debitado antes, e se o banco recusar depois, o valor volta para ela, não para o caixa geral.
Motor idêntico ao do saque turbo de POST /v1/payouts com turbo: true. Os corpos de resposta são os mesmos, mais os casos próprios daqui (subconta inexistente, saldo da subconta, chave de idempotência já usada ou estornada).
amountCents é BRUTO. Ele é o valor debitado da subconta; a taxa de saque sai de dentro dele, e quem recebe a chave PIX fica com amountCents / 100 - fee. A resposta traz os três (amount, fee, netAmount) para conferência. Se depois da taxa sobrar menos de R$ 0,01, a chamada é recusada com 400.
Se a subconta tiver markup de saque (payoutFeePercent / payoutFeeFixedCents), ele sai ANTES de tudo: a subconta é debitada o amountCents cheio, o saque é criado pelo valor já sem o seu markup, e a diferença fica na carteira da conta principal sem nenhum movimento extra. Ou seja, o amount da resposta JÁ VEM sem o seu markup, e o fee dela é só a taxa da plataforma. O valor do markup você lê no extrato da subconta, no feeCents do lançamento payout. Markup que consome o valor inteiro é 400, com a taxa citada na mensagem.
Se o banco recusar depois, o estorno devolve à subconta o valor CHEIO, markup incluído: você não fica com a taxa de um saque que não aconteceu.
Valor mínimo: o piso que o administrador configurou para a conta (minAmount vem no corpo do 400 quando o valor fica abaixo dele). Sem piso configurado, o único mínimo é o físico acima. Teto: R$ 5.000,00 por operação.
Permissão: subcontas.sacar, e ela NUNCA é herdada. Chave criada antes desta permissão existir não a recebe de graça: ligue no painel, na própria chave. Sem ela, 403.
Somente chaves live. Chave de sandbox recebe 400: a subconta de teste não tem lastro, e sacar dela mandaria PIX de verdade.
Limite: 5 chamadas por hora por conta (ajustável pelo administrador), em contador PRÓPRIO. Ele não consome a cota de POST /v1/payouts. Chamadas recusadas não gastam cota.
Idempotência: mande idempotencyKey NO CORPO (esta API não usa header de idempotência). Formato [A-Za-z0-9_-], até 64 caracteres. A chave vira o refId do lançamento no extrato da subconta e fica guardada com ele, sem prazo de expiração: repetir a mesma chave meses depois continua sendo reconhecido como repetição. O escopo é a subconta, então a mesma chave pode ser usada em subcontas diferentes. Sem idempotencyKey, cada chamada é um saque novo, e um timeout que na verdade deu certo vira PIX em dobro.
Authorizations
Chave de API gerada no dashboard da PurinCash (ps_live_ ou ps_test_).
Path Parameters
ID da subconta (sacc_ + 32 hex).
Body
Valor BRUTO em centavos, debitado da subconta. Número JSON inteiro: string e decimal são recusados com 400. A taxa sai de dentro dele.
x >= 1Chave PIX de destino (CPF, CNPJ, e-mail, telefone ou aleatória).
200Chave de idempotência OPCIONAL, no CORPO. Guardada sem prazo, junto do lançamento no extrato da subconta.
64^[A-Za-z0-9_-]+$
