# Atualizar subconta

**Área:** Subcontas

Atualiza uma subconta vinculada à sua conta principal. Informe ao menos um entre `dailyWithdrawalLimit`, `withdrawalPixKey` e `masterFee`.

`PUT /v1/accounts/subaccounts`

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

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

**Taxa da conta principal (`masterFee`):** valor que a sua conta recebe de cada cobrança paga da subconta, além da taxa ValidaPay. Uma regra por método (`pix`, `boleto`): percentual sobre o valor bruto ou valor fixo em reais. Cartão não tem essa taxa.

- A taxa é calculada e gravada na **criação** de cada cobrança. Mudar a configuração não altera cobranças já criadas.
- No pagamento, o valor é transferido da subconta para a sua conta e aparece no extrato das duas (`MASTER_FEE_IN` na conta principal).
- Cobrança em que taxa ValidaPay, taxa da conta principal e split somados passam do valor bruto **não é gerada** (`400 MASTER_FEE_EXCEEDS_NET_AMOUNT`).
- A configuração é recusada com `400 MASTER_FEE_EXCEEDS_SUBSCRIPTIONS` se alguma assinatura ativa da subconta deixaria de caber; `details.subscriptions` lista quais.
- Só o titular da conta principal altera a taxa: acesso de membro da equipe recebe `403 MASTER_FEE_OWNER_ONLY`.

Case de uso:

_Como conta principal, quero cobrar uma taxa sobre as vendas das minhas subcontas, para remunerar a operação que ofereço a elas._

### Request body

```json
{
    "accountNumber": "4960589",
    "dailyWithdrawalLimit": 3000,
    "withdrawalPixKey": "saques@empresa.com",
    "masterFee": {
        "pix": {
            "type": "percentage",
            "amount": 0.5
        },
        "boleto": {
            "type": "fixed",
            "amount": 2
        }
    }
}
```

### Campos do body

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

| Campo | Descrição |
|---|---|
| `accountNumber` | Número da subconta. Precisa estar vinculada à sua conta principal |
| `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 |
|---|---|
| `dailyWithdrawalLimit` | Limite diário de saque da subconta, em reais |
| `withdrawalPixKey` | Chave Pix de destino dos saques da subconta. `null` remove |
| `masterFee` | Taxa que a sua conta cobra de cada cobrança paga da subconta, por método. `null` remove; método omitido não paga taxa. Cartão não é aceito |
| `masterFee.pix` | Regra para cobranças Pix |
| `masterFee.boleto` | Regra para cobranças por boleto |

### Resposta 200: 200

```json
{
  "message": "Subconta atualizada com sucesso",
  "accountNumber": "4960589",
  "masterFee": {
    "pix": {
      "type": "percentage",
      "amount": 0.5
    },
    "boleto": {
      "type": "fixed",
      "amount": 2
    }
  }
}
```


### Resposta 400: 400 MASTER_FEE_EXCEEDS_SUBSCRIPTIONS

```json
{
  "error": {
    "message": "A taxa do master não cabe em 1 assinatura(s) ativa(s) da subconta: taxa Valida, taxa do master e split excedem o valor do ciclo",
    "code": "MASTER_FEE_EXCEEDS_SUBSCRIPTIONS",
    "details": {
      "total": 1,
      "subscriptions": [
        {
          "subscriptionId": "sub_1788279663277_8qjtrcyri",
          "paymentType": "BOLETO",
          "grossAmount": 9.9,
          "netAmount": 8.13,
          "masterFeeAmount": 10,
          "splitTotal": 0,
          "fits": false
        }
      ]
    },
    "timestamp": "2026-11-06T18:20: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-06T18:20:00.000Z"
  }
}
```


---

Página: https://docs.validapay.com.br/referencia/put-atualizar-subconta  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json