> ## Documentation Index > Fetch the complete documentation index at: https://docs.purin.cash/llms.txt > Use this file to discover all available pages before exploring further. # Create Payout > Solicita um saque PIX ou LTC do saldo disponível. O débito do saldo é atômico. O valor máximo sacável é o campo withdrawable do GET /v1/wallet (balance - disputeBlocked - comprometido com subcontas): o saldo retido por disputas (MED) abertas ou perdidas não perdoadas não é sacável, e o valor já atribuído a subcontas também não sai pela conta principal (transfira to_master antes, ou saque pela subconta no painel). Pedidos acima do sacável são rejeitados com 400 (o campo available da resposta indica o valor sacável, e subaccountsCommitted aparece quando há valor comprometido). Saque PIX exige chave PIX verificada no dashboard (403 caso contrário). Saque LTC exige cryptoAmount e endereço LTC em formato válido, e sai NA HORA da carteira da loja, sem aprovação: status completed com txHash (a transação na rede), processing (enviando, ou transmitido sem confirmação da rede: não repita o pedido) ou pending (não saiu agora; nada foi transmitido e o envio tenta de novo sozinho). O mesmo saque LTC repetido em 10 segundos é recusado com 429. Rate limit de 10 solicitações por hora por conta (somando todas as chaves; 429 ao exceder). O sandbox aplica as MESMAS regras: valida o saldo simulado (400 com available quando não cabe), exige PIX verificado (403), DEBITA o saldo simulado e o saque aparece em GET /v1/payouts. Nada de dinheiro real se move. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/payouts openapi: 3.1.0 info: title: PurinCash API version: 1.0.0 servers: - url: https://api.purin.cash description: Produção security: - bearerAuth: [] tags: - name: Cartao description: Pagamentos no cartao de credito. - name: Cobrancas description: Cobrancas PIX avulsas com valor livre. - name: Entregas description: Conteudo entregue automaticamente apos o pagamento. - name: Disputas description: Contestacoes (MED) e envio de evidencias. - name: Pagamentos description: Pagamentos PIX e LTC vinculados ou nao a um produto. - name: Saques description: Saques em PIX, LTC e USDT. - name: Produtos description: Produtos de cobranca criados pela API. - name: Sandbox description: Simulacao de pagamentos e saldo de teste. - name: Splits description: Cobrancas divididas entre varias contas. - name: Loja description: Produtos da loja do Discord (somente leitura). - name: Subcontas description: Ledger de saldo por cliente do integrador. - name: Assinaturas description: PIX recorrente. - name: Carteira description: Saldo, retencoes e valores a liberar. paths: /v1/payouts: post: tags: - Saques summary: Create Payout description: >- Solicita um saque PIX ou LTC do saldo disponível. O débito do saldo é atômico. O valor máximo sacável é o campo withdrawable do GET /v1/wallet (balance - disputeBlocked - comprometido com subcontas): o saldo retido por disputas (MED) abertas ou perdidas não perdoadas não é sacável, e o valor já atribuído a subcontas também não sai pela conta principal (transfira to_master antes, ou saque pela subconta no painel). Pedidos acima do sacável são rejeitados com 400 (o campo available da resposta indica o valor sacável, e subaccountsCommitted aparece quando há valor comprometido). Saque PIX exige chave PIX verificada no dashboard (403 caso contrário). Saque LTC exige cryptoAmount e endereço LTC em formato válido, e sai NA HORA da carteira da loja, sem aprovação: status completed com txHash (a transação na rede), processing (enviando, ou transmitido sem confirmação da rede: não repita o pedido) ou pending (não saiu agora; nada foi transmitido e o envio tenta de novo sozinho). O mesmo saque LTC repetido em 10 segundos é recusado com 429. Rate limit de 10 solicitações por hora por conta (somando todas as chaves; 429 ao exceder). O sandbox aplica as MESMAS regras: valida o saldo simulado (400 com available quando não cabe), exige PIX verificado (403), DEBITA o saldo simulado e o saque aparece em GET /v1/payouts. Nada de dinheiro real se move. operationId: createPayout requestBody: required: true content: application/json: schema: type: object required: - amount - walletAddress properties: method: type: string enum: - pix - pix_code - ltc - usd default: pix description: >- Método do saque: "pix" para chave PIX, "pix_code" para pagar um código copia e cola (BR Code), "ltc" para Litecoin ou "usd" para USDT na rede BEP20 (converte o saldo BRL; a resposta do USD tem formato próprio, com o objeto withdrawal; veja o guia de Saques). Em "pix_code" o corpo muda: brCode passa a ser obrigatório no lugar de walletAddress, amount vira opcional (quem manda no valor é o código) e a taxa é SOMADA ao valor em vez de descontada dele: a resposta traz amount, fee e debited. Não disponível em sandbox. brCode: type: string description: >- Obrigatório quando method é "pix_code": o copia e cola completo do PIX. Quebras de linha são ignoradas, o resto vai íntegro (é o código que carrega o destino). Limites de R$ 1,00 a R$ 5.000,00 sobre o valor que o recebedor recebe. Exige o escopo saques.pix, chave PIX da conta verificada e a conta já ter feito o primeiro saque PIX (403 caso contrário). Código apontando para destino da própria plataforma é recusado com 400 e blocked true. confirmNotCoinbase: type: boolean description: >- Obrigatório e true quando method é "usd": confirma que o endereço de destino NÃO é de exchange que rejeita BEP20 (ex. Coinbase). Sem ele o saque USD devolve 400. amount: type: number minimum: 5 maximum: 999999.99 description: >- Valor do saque em BRL. O mínimo é o configurado para a SUA conta (R$ 5,00 por padrão; o erro de valor baixo devolve minAmount com o mínimo vigente). Máximo R$ 999.999,99. Para PIX, deve ser menor ou igual ao campo withdrawable do GET /v1/wallet (balance - disputeBlocked - comprometido com subcontas). No turbo o máximo é R$ 5.000,00 por saque. Em method "pix_code" o campo é OPCIONAL e só vale para QR estático sem valor: com valor fixo ou QR dinâmico quem manda é o código, e enviar um número diferente devolve 400 em vez de pagar (divergir do que sai é como aparece prejuízo silencioso). walletAddress: type: string maxLength: 100 description: >- Chave PIX (para method "pix") ou endereço LTC (para method "ltc"). Endereços LTC são validados por formato (legado L/M/3 ou bech32 ltc1...). cryptoAmount: type: number exclusiveMinimum: 0 description: >- Quantidade em LTC a sacar. Obrigatória quando method é "ltc". example: method: pix amount: 100 walletAddress: email@exemplo.com responses: '200': description: >- Só em method "pix_code": o pagamento do código foi enviado. O objeto payment traz os três números que precisam bater no seu financeiro: amount é o que o RECEBEDOR recebeu, fee é a taxa e debited é o que saiu da carteira (amount + fee). status "completed" = banco confirmou; "processing" = o PIX já saiu e a confirmação vem depois (trate como pago, não reenvie). content: application/json: schema: type: object properties: success: type: boolean payment: type: object properties: id: type: string description: Identificador interno do pagamento. code: type: string description: Código do pagamento (prefixo PAY-). amount: type: number description: O que o recebedor recebeu, em BRL. fee: type: number description: Taxa da plataforma, SOMADA ao valor (não descontada). debited: type: number description: O que saiu da carteira (amount + fee). status: type: string enum: - completed - processing endToEndId: type: - string - 'null' description: >- E2E do PIX, o mesmo que aparece no extrato de quem recebeu. null enquanto o banco não devolve. txId: type: - string - 'null' description: >- Identificador da transação, para rastreio com o suporte. merchantName: type: - string - 'null' description: Nome do recebedor confirmado pelo banco. recipientDocument: type: - string - 'null' description: >- Documento do recebedor confirmado pelo banco, quando informado. Vem completo, diferente do decode. isDynamic: type: boolean description: true quando o código era um QR dinâmico. example: success: true payment: id: 665f1a2b3c4d5e6f7a8b9c0d code: PAY-A1B2C3D4 amount: 100 fee: 1 debited: 101 status: completed endToEndId: E12345678202603181200abcdef01234 txId: 9f8e7d6c-5b4a-3928-1706-f5e4d3c2b1a0 merchantName: NOME DO RECEBEDOR recipientDocument: '12345678909' isDynamic: false '201': description: >- Saque criado. Trate pelo status: "pending" = entrou na fila de aprovação (o desfecho chega por webhook); "completed" = pago e confirmado; "processing" = o PIX JÁ saiu e só falta a confirmação do banco (trate como pago, não reenvie). Quando o envio foi imediato, a resposta traz method "pix_turbo", fee, netAmount e recipientName (o nome que o banco confirmou como dono da chave). No sandbox o retorno é simulado com status "completed" e inclui walletAddress. content: application/json: schema: type: object properties: id: type: string description: Código do saque (igual a code). code: type: string description: >- Código do saque: SAQ-API-... no comum, TURBO-... no envio imediato, SAQ-SBX-... no sandbox. method: type: string enum: - pix - ltc - pix_turbo description: Método do saque. pix_turbo quando o envio foi turbo. amount: type: number description: Valor do saque em BRL. cryptoAmount: type: number description: Quantidade em LTC (presente apenas quando method é "ltc"). txHash: type: - string - 'null' description: >- Saque LTC. A transação na rede, para conferir no explorer. null enquanto não saiu. walletAddress: type: string description: >- Chave/endereço informado, sempre MASCARADO (6 primeiros caracteres e ***), igual à listagem. Retornado apenas no sandbox. Dado sensível não volta inteiro em resposta nem em log. status: type: string enum: - pending - completed - processing description: >- Status inicial do saque. "pending" = aguardando aprovação (saque comum). "completed" = pago (turbo confirmado, saque LTC transmitido, ou sandbox). "processing" = turbo enviado, banco ainda não confirmou; o dinheiro JÁ saiu, não repita o request. No saque LTC, "processing" é envio em andamento ou transmitido sem confirmação da rede (não repita), e "pending" é envio que não saiu agora e tenta de novo sozinho. fee: type: number description: Taxa do turbo em BRL (só nas respostas turbo). netAmount: type: number description: Valor que chega ao recebedor após a taxa (só turbo). txId: type: - string - 'null' description: Id da transação no banco (só turbo). recipientName: type: - string - 'null' description: >- Nome do dono da chave, confirmado pelo banco (só turbo). Use para conferir que pagou a pessoa certa. turbo: type: boolean description: >- Em saques PIX vem sempre: true quando o envio foi imediato (turbo), false quando o saque entrou na fila de aprovação. A rota fica explícita, sem inferir do status. sandbox: type: boolean description: Indica se o saque foi criado no ambiente de teste. example: id: SAQ-API-A1B2C3D4 code: SAQ-API-A1B2C3D4 method: pix amount: 100 status: pending turbo: false sandbox: false '202': description: >- No envio imediato e no pix_code, e é o caso que exige cuidado. O banco não respondeu a tempo. O PIX PODE ter sido enviado, então o saldo NÃO é estornado (estornar poderia pagar duas vezes) e um verificação. NÃO repita o request; acompanhe o code em GET /v1/payouts (o do pix_code começa com PAY-). content: application/json: schema: type: object properties: error: type: string requiresReview: type: boolean contactSupport: type: boolean code: type: string turbo: type: boolean example: error: >- Saque em processamento. A transferência pode ter sido enviada mas não recebemos confirmação do banco. Passa por verificação antes de qualquer novo envio: não repita este saque. Se tiver dúvidas, fale com o suporte. Código: TURBO-A1B2C3D4 requiresReview: true code: TURBO-A1B2C3D4 '400': description: >- O pedido está errado e nada se moveu (ou o saldo já voltou, quando a resposta traz refunded true). Casos: amount acima do sacável (o campo available diz quanto cabe), abaixo do mínimo da conta (minAmount na resposta), method inválido, walletAddress ausente, endereço LTC em formato inválido, cryptoAmount ausente em saques LTC, subaccountId preenchido (null e vazio são ignorados; saque não debita ledger de subconta; transfira to_master antes ou use o saque de subconta do painel), ou o banco recusou a chave do recebedor: definitiveRejection true (bankErrorCode chave_invalida ou validacao) significa que repetir o mesmo request nunca vai funcionar; conserte a chave; o texto do banco vem em bankMessage. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro. available: type: number description: >- Saldo disponível, presente nos erros de saldo insuficiente. O valor sacável em BRL para PIX é (balance - disputeBlocked - comprometido com subcontas) ou saldo LTC para saques LTC. subaccountsCommitted: type: number description: >- Quanto do saldo pertence a subcontas (BRL), presente no erro de saldo insuficiente quando maior que zero. Esse valor sai pela subconta, não pela conta principal. minAmount: type: number description: >- Mínimo de saque da sua conta, presente no erro de valor abaixo do mínimo. bankMessage: type: string description: Texto exato que o banco devolveu (só turbo). bankErrorCode: type: string enum: - chave_invalida - validacao - indisponivel description: >- Motivo da recusa no envio imediato. chave_invalida e validacao acompanham definitiveRejection true (conserte o pedido); indisponivel acompanha o 502 (tente mais tarde). definitiveRejection: type: boolean description: >- true = nem retry nem aprovação manual resolvem; conserte o pedido (só turbo). refunded: type: boolean description: true = o saldo já foi restaurado (só turbo). code: type: string description: Código do saque recusado (só turbo). turbo: type: boolean description: Presente quando o erro veio do fluxo turbo. examples: saldo: summary: Saldo insuficiente value: error: Insufficient balance available: 1400.75 banco: summary: Recusa definitiva do banco (turbo) value: error: >- A chave PIX foi recusada pelo banco. Confira a chave do recebedor e tente de novo. Banco: Invalid Pix Key. Seu saldo foi restaurado. bankMessage: Invalid Pix Key bankErrorCode: chave_invalida definitiveRejection: true refunded: true code: TURBO-A1B2C3D4 turbo: true '401': description: Chave de API ausente ou inválida. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro. example: error: Unauthorized '403': description: >- Chave PIX não verificada. Complete a verificação no dashboard da PurinCash antes de solicitar saques PIX. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro. example: error: >- PIX not verified. Complete verification in the dashboard first. '409': description: >- Só no envio imediato. Já existe um envio em processamento para esta conta. Dinheiro pode estar em trânsito agora; espere e consulte GET /v1/payouts antes de tentar de novo. (Requests em sequência curta podem receber 429 pelo mesmo motivo.) content: application/json: schema: type: object properties: error: type: string turbo: type: boolean '429': description: >- Rate limit excedido. O máximo padrão é de 10 solicitações de saque por hora POR CONTA, somando todas as chaves (requisições com erro não contam para o limite). No envio imediato o limite próprio é de 5 por hora, e requests idênticos em sequência curta também recebem 429. Um 429 pode significar dinheiro em trânsito agora: espere e consulte GET /v1/payouts antes de repetir. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro. example: error: 'Rate limit: too many payout requests. Try again later.' '500': description: Erro interno. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro. example: error: Internal error '502': description: >- O envio imediato não pôde ser concluído e o saldo já voltou (refunded true, bankErrorCode "indisponivel"). Use o saque comum para este pagamento e tente o instantâneo mais tarde. content: application/json: schema: type: object properties: error: type: string bankErrorCode: type: string contactSupport: type: boolean definitiveRejection: type: boolean refunded: type: boolean code: type: string turbo: type: boolean '503': description: >- Turbo indisponível no momento (manutenção ou instabilidade), ou a configuração da conta não pôde ser lida para decidir a rota do envio. Nos dois casos nada foi debitado: repita a requisição. A resposta pode trazer turboDisabled true. content: application/json: schema: type: object properties: error: type: string turboDisabled: type: boolean turbo: type: boolean components: securitySchemes: bearerAuth: type: http scheme: bearer description: Chave de API gerada no dashboard da PurinCash (ps_live_ ou ps_test_). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.