# Taxa padrão das novas subcontas

**Área:** Subcontas

Define a taxa da conta principal que toda subconta criada **a partir de agora** recebe automaticamente. Mesmo formato do `masterFee` de "Atualizar subconta": uma regra por método (`pix`, `boleto`), percentual sobre o valor bruto ou valor fixo em reais. Cartão não tem essa taxa.

`PUT /v1/accounts/subaccount-defaults`

**Base URL Produção:** `https://api.validapay.com.br`  
**Base URL Sandbox:** `https://sandbox.validapay.com.br`

**Scopes necessários:** `subaccounts/write`

- A taxa padrão é copiada para a subconta no momento em que ela é criada. Mudar o padrão depois não altera as subcontas já criadas.
- Subcontas que já existem não mudam. A taxa de cada subconta continua ajustável em "Atualizar subconta", inclusive para remover.
- `masterFee: null` remove a taxa padrão.
- A taxa padrão atual vem em `defaultMasterFee` na resposta de "Listar subcontas".
- Só o titular da conta principal altera: acesso de membro da equipe recebe `403 MASTER_FEE_OWNER_ONLY`.

Case de uso:

_Como conta principal, quero definir uma taxa padrão para as minhas subcontas, para que toda subconta nova já nasça cobrando a taxa da operação._

### Request body

```json
{
    "masterFee": {
        "pix": {
            "type": "fixed",
            "amount": 2
        },
        "boleto": {
            "type": "percentage",
            "amount": 1.5
        }
    }
}
```

### Campos do body

**Obrigatórios:** `masterFee`, `masterFee.pix.type`, `masterFee.pix.amount`, `masterFee.boleto.type`, `masterFee.boleto.amount`

| Campo | Descrição |
|---|---|
| `masterFee` | Taxa padrão das novas subcontas, por método. `null` remove; método omitido não paga taxa. Cartão não é aceito |
| `masterFee.pix.type` | `percentage` (sobre o valor bruto) ou `fixed` (valor em reais) |
| `masterFee.pix.amount` | Ponto percentual (0.5 = 0,5%, até 100) ou valor em reais com duas casas |
| `masterFee.boleto.type` | `percentage` ou `fixed` |
| `masterFee.boleto.amount` | Ponto percentual ou valor em reais |

**Opcionais**

| Campo | Descrição |
|---|---|
| `masterFee.pix` | Regra para cobranças Pix |
| `masterFee.boleto` | Regra para cobranças por boleto |

### Resposta 200: 200

```json
{
  "message": "Taxa padrão das novas subcontas atualizada",
  "masterFee": {
    "pix": {
      "type": "fixed",
      "amount": 2
    },
    "boleto": {
      "type": "percentage",
      "amount": 1.5
    }
  }
}
```


### Resposta 400: 400 INVALID_MASTER_FEE

```json
{
  "error": {
    "message": "O tipo da taxa do master deve ser percentage ou fixed",
    "code": "INVALID_MASTER_FEE",
    "details": [
      {
        "received": "both",
        "code": "invalid_enum_value",
        "options": [
          "percentage",
          "fixed"
        ],
        "path": [
          "pix",
          "type"
        ],
        "message": "O tipo da taxa do master deve ser percentage ou fixed"
      }
    ],
    "timestamp": "2026-11-08T12:00:00.000Z"
  }
}
```


### Resposta 403: 403 MASTER_FEE_OWNER_ONLY

```json
{
  "error": {
    "message": "Só o titular da conta master altera a taxa da subconta",
    "code": "MASTER_FEE_OWNER_ONLY",
    "details": null,
    "timestamp": "2026-11-08T12:00:00.000Z"
  }
}
```


---

Página: https://docs.validapay.com.br/referencia/put-taxa-padrao-das-novas-subcontas  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json