> ## 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. # Transfer Subaccount Balance > Move saldo entre a subconta e a conta principal, nos dois sentidos. É uma operação contábil: nenhum PIX é enviado e o dinheiro real não sai da carteira da sua conta. Muda apenas a quem o valor está atribuído. `to_master` debita a subconta (exige saldo suficiente; a checagem é atômica, duas transferências concorrentes não deixam saldo negativo). `to_subaccount` credita a subconta a partir do pool NÃO ATRIBUÍDO da conta principal (sacável da carteira menos o que as subcontas já detêm: o `unattributedCents` do `GET /v1/wallet`): aporte atribui dinheiro que existe, não cria. Sem lastro é `400`; corrida entre duas transferências pelo mesmo lastro desfaz a perdedora com `409` (repita). `between_subaccounts` move direto desta subconta para outra da mesma conta, informada em `toSubaccountId`, sem passar pela conta principal. Exige saldo suficiente na origem (o valor retido por disputa fica na origem) e destino ativo. O extrato ganha um lançamento em cada subconta, com o mesmo `transferId`. Não depende de lastro: o total atribuído às subcontas não muda. `amountCents` é número JSON inteiro de 1 a 100000000000 (R$ 1 bilhão). String, decimal ou acima do teto: `400`, sem coerção. Idempotência: mande `idempotencyKey` NO CORPO (esta API não usa header de idempotência). A repetição devolve `200` com a transferência original e `idempotentReplay` true, em vez de mover o valor duas vezes. Para pagar um cliente de verdade, transfira `to_master` e faça um saque normal em `POST /v1/payouts` com a chave PIX dele. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/subaccounts/{id}/transfer 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/subaccounts/{id}/transfer: post: tags: - Subcontas summary: Transfer Subaccount Balance description: >- Move saldo entre a subconta e a conta principal, nos dois sentidos. É uma operação contábil: nenhum PIX é enviado e o dinheiro real não sai da carteira da sua conta. Muda apenas a quem o valor está atribuído. `to_master` debita a subconta (exige saldo suficiente; a checagem é atômica, duas transferências concorrentes não deixam saldo negativo). `to_subaccount` credita a subconta a partir do pool NÃO ATRIBUÍDO da conta principal (sacável da carteira menos o que as subcontas já detêm: o `unattributedCents` do `GET /v1/wallet`): aporte atribui dinheiro que existe, não cria. Sem lastro é `400`; corrida entre duas transferências pelo mesmo lastro desfaz a perdedora com `409` (repita). `between_subaccounts` move direto desta subconta para outra da mesma conta, informada em `toSubaccountId`, sem passar pela conta principal. Exige saldo suficiente na origem (o valor retido por disputa fica na origem) e destino ativo. O extrato ganha um lançamento em cada subconta, com o mesmo `transferId`. Não depende de lastro: o total atribuído às subcontas não muda. `amountCents` é número JSON inteiro de 1 a 100000000000 (R$ 1 bilhão). String, decimal ou acima do teto: `400`, sem coerção. Idempotência: mande `idempotencyKey` NO CORPO (esta API não usa header de idempotência). A repetição devolve `200` com a transferência original e `idempotentReplay` true, em vez de mover o valor duas vezes. Para pagar um cliente de verdade, transfira `to_master` e faça um saque normal em `POST /v1/payouts` com a chave PIX dele. operationId: transferSubaccountBalance parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - direction - amountCents properties: direction: type: string enum: - to_master - to_subaccount - between_subaccounts description: >- Sentido da transferência. `between_subaccounts` exige `toSubaccountId`. toSubaccountId: type: string description: >- Subconta de destino. Obrigatório, e só usado, em `between_subaccounts`. Precisa ser da mesma conta e diferente da subconta do caminho. amountCents: type: integer minimum: 1 maximum: 100000000000 description: >- Valor em centavos. Número JSON inteiro: string e decimal são recusados com 400. description: type: string maxLength: 200 description: Texto livre que aparece no extrato. idempotencyKey: type: string maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ description: >- Chave de idempotência OPCIONAL, enviada no CORPO (não existe header de idempotência nesta API). Com ela, repetir a mesma requisição devolve 200 com a transferência original e idempotentReplay true, em vez de mover o valor de novo. Vira o refId do lançamento com o prefixo idem_. Escopo: a subconta. Sem a chave, cada requisição é uma transferência nova. example: direction: to_master amountCents: 30000 description: Comissão da plataforma idempotencyKey: fechamento-2026-07-cliente-42 responses: '200': description: >- Repetição de uma transferência já registrada com o mesmo idempotencyKey. Nada foi movido de novo: o corpo descreve a transferência ORIGINAL e traz idempotentReplay true. content: application/json: schema: type: object properties: transferId: type: string subaccountId: type: string direction: type: string enum: - to_master - to_subaccount - between_subaccounts toSubaccountId: type: string toBalanceCents: type: integer amountCents: type: integer balanceCents: type: integer idempotentReplay: type: boolean example: transferId: idem_fechamento-2026-07-cliente-42 subaccountId: sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90 direction: to_master amountCents: 30000 balanceCents: 15900 idempotentReplay: true '201': description: Transferência registrada. content: application/json: schema: type: object properties: transferId: type: string subaccountId: type: string direction: type: string enum: - to_master - to_subaccount - between_subaccounts toSubaccountId: type: string description: Só em `between_subaccounts`. A subconta que recebeu. toBalanceCents: type: integer description: >- Só em `between_subaccounts`. Saldo da subconta de destino após a transferência. amountCents: type: integer balanceCents: type: integer description: Saldo da subconta após a transferência. example: transferId: tr_1a2b3c4d5e6f7a8b9c0d1e2f subaccountId: sacc_a1b2c3d4e5f60718293a4b5c6d7e8f90 direction: to_master amountCents: 30000 balanceCents: 15900 '400': description: >- Direção inválida, `amountCents` fora do contrato (string, decimal, zero, negativo ou acima do teto), subconta desativada recebendo entrada, saldo insuficiente no `to_master` ou no `between_subaccounts`, `toSubaccountId` ausente, malformado ou igual à origem, ou `to_subaccount` sem lastro no pool não atribuído da carteira (o corpo traz `unattributedCents` com o disponível). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Insufficient unattributed master balance '404': description: Subconta inexistente ou de outra conta. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Transferência concorrente disputou o mesmo lastro e esta foi desfeita. Nada foi creditado: repita a chamada. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Erro interno. 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_). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.