> ## Documentation Index > Fetch the complete documentation index at: https://docs.purincash.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/subaccounts/{id}/payout openapi: 3.1.0 info: title: PurinCash API version: 1.0.0 servers: - url: https://api.purincash.com 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/subaccounts/{id}/payout: post: tags: - Subcontas summary: Payout From Subaccount description: >- 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. operationId: payoutFromSubaccount parameters: - name: id in: path required: true schema: type: string description: ID da subconta (sacc_ + 32 hex). requestBody: required: true content: application/json: schema: type: object required: - amountCents - pixKey properties: amountCents: type: integer minimum: 1 description: >- 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. pixKey: type: string maxLength: 200 description: >- Chave PIX de destino (CPF, CNPJ, e-mail, telefone ou aleatória). idempotencyKey: type: string maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ description: >- Chave de idempotência OPCIONAL, no CORPO. Guardada sem prazo, junto do lançamento no extrato da subconta. example: amountCents: 25000 pixKey: fornecedor@exemplo.com.br idempotencyKey: repasse-2026-09-fornecedor-42 responses: '200': description: >- Saque enviado. `netAmount` é o que chegou na chave PIX: `amount` menos `fee`. Uma repetição com o mesmo `idempotencyKey` também responde 200, com `idempotentReplay` true e o corpo do saque ORIGINAL, sem enviar nada de novo. content: application/json: schema: type: object properties: success: type: boolean withdrawal: type: object properties: id: type: string code: type: string amount: type: number description: Valor bruto debitado, em reais. fee: type: number description: Taxa do saque, já descontada do bruto. netAmount: type: number description: O que chegou na chave PIX. status: type: string txId: type: string recipientName: type: string nullable: true recipientBankName: type: string nullable: true operationUuid: type: string nullable: true example: success: true withdrawal: id: 68c0a1b2c3d4e5f60718293a code: TURBO-7K1M amount: 250 fee: 1 netAmount: 249 status: completed txId: 553e8400-e29b-41d4-a716-436251480000 recipientName: Empresa Exemplo LTDA recipientBankName: Nubank operationUuid: null '202': description: >- O banco não respondeu a tempo. O PIX PODE ter saído, então o débito da subconta é mantido e o saque entra em verificação. NÃO repita a chamada: consulte o `code` devolvido. content: application/json: schema: type: object properties: error: type: string requiresReview: type: boolean contactSupport: type: boolean code: type: string '400': description: >- `amountCents` fora do contrato, chave PIX inválida, subconta desativada, saldo insuficiente na subconta (a mensagem traz o disponível e o quanto está bloqueado por MED dela), valor abaixo do piso configurado (o corpo traz `minAmount`), valor acima de R$ 5.000, sobra menor que R$ 0,01 depois da taxa, chave de sandbox, ou recusa definitiva do banco (aí vem `refunded` true e o saldo já voltou para a subconta). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'Saldo insuficiente na subconta. Disponível: R$ 120,00' '403': description: >- Chave sem a permissão `subcontas.sacar` (ela nunca é herdada: ligue no painel), conta sem chave PIX verificada, ou primeiro saque da conta, que passa por aprovação manual antes de os saques instantâneos serem liberados. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- This API key does not have the "Sacar de subconta" permission. This permission is never granted implicitly: edit the key in the dashboard and enable it. scope: subcontas.sacar '404': description: Subconta inexistente, de outra conta, ou de outro ambiente. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Já existe um saque em processamento para esta conta, as condições do saque mudaram entre o pedido e a execução, a mesma `idempotencyKey` chegou em duas chamadas simultâneas, ou a `idempotencyKey` pertence a um saque que terminou ESTORNADO. Neste último caso o corpo traz `reversed` true: nada foi enviado, e repetir exige uma chave nova (a antiga fica presa ao lançamento estornado no extrato). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- This idempotencyKey belongs to a payout that was reversed. Nothing was sent. Retry with a new key. idempotencyKey: repasse-2026-09-fornecedor-42 reversed: true '429': description: >- Limite de 5 por hora estourado, requisição duplicada em menos de 10 segundos, ou outro saque da mesma conta em andamento. Um 429 pode significar dinheiro em trânsito agora: espere e consulte o saque antes de tentar de novo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- Rate limit: too many subaccount payout requests. Try again later. '500': description: >- Erro interno. Quando acontece antes do envio, o débito da subconta é desfeito. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: >- Provedor de pagamento indisponível. O saldo já foi restaurado na subconta. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- Saque instantâneo desligado no momento, ou nenhum provedor de saque disponível. Nada foi debitado. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: error: type: string description: >- Mensagem de erro legivel. Trate pelo codigo HTTP; o texto pode mudar. securitySchemes: bearerAuth: type: http scheme: bearer description: Chave de API gerada no dashboard da PurinCash (ps_live_ ou ps_test_). ````