---
title: "Transferência interna entre subcontas e a casa (sem PIX)"
method: POST
path: "/saldo/transferir"
tags: ["Conta"]
---

# Transferência interna entre subcontas e a casa (sem PIX)

`POST /saldo/transferir`

## Request

- Base URL: `https://api.luniumpay.com`
- URL: `https://api.luniumpay.com/saldo/transferir`
- Auth: API key in header `X-API-Key`

Move saldo DISPONÍVEL entre um cliente final (`customer_ref`) e a casa (`"casa"` = a própria chave), ou entre dois clientes, sem passar pelo PIX. Uso típico: cobrar a sua taxa do cliente (cliente → casa), bonificar ou devolver (casa → cliente). O congelado (retenção de 24h / MED) não se move. Subconta na carência do primeiro depósito não transfere (423 — só chaves com carência contratual). Idempotente por `external_id`. Dispara o evento `saldo.transferido`.

## Request body

- object
  - `from_customer_ref` string, required: `customer_ref` de origem, ou `"casa"`.
  - `to_customer_ref` string, required: `customer_ref` de destino, ou `"casa"`.
  - `amount_cents` integer, required
  - `descricao` string: Aparece no extrato das duas pontas.
  - `external_id` string: Identificador idempotente de até 64 caracteres. Mantenha o mesmo identificador e todos os parâmetros nos retries. A comparação de divergência varia por rota; não use o replay para alterar uma operação. 409 external_id_divergente sinaliza conflito detectado.

## Response `200`

Replay idempotente (`idempotente: true`).

## Other responses

- `201`: Transferida.
- `400`: `valor_invalido` · `origem_igual_destino` · `custodia_desligada`.
- `409`: `saldo_insuficiente` (com `disponivel_cents`/`bloqueado_cents`) · `external_id_divergente`.
- `423`: `carencia_primeiro_deposito` na subconta de origem.

---

[API](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil.md) · [All operations](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/llms.txt) · [OpenAPI document](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/revisions/0b5a340fa9dd?raw)