Subcontas

Taxa padrão das novas 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

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.

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

subaccounts/write

Body

application/json

Content-Type:application/json

JSON

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

Schema

masterFeeobjectobrigatório

Taxa padrão das novas subcontas, por método. `null` remove; método omitido não paga taxa. Cartão não é aceito

Headers

Content-Typetextopcional

application/json

← Anterior

Atualizar subconta

Listar cobranças

const url = 'https://sandbox.validapay.com.br/v1/accounts/subaccount-defaults';

const options = {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "masterFee": {
        "pix": {
            "type": "fixed",
            "amount": 2
        },
        "boleto": {
            "type": "percentage",
            "amount": 1.5
        }
    }
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200▾

JSON

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

400INVALID_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"
  }
}

403MASTER_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"
  }
}

← Anterior

Atualizar subconta

Listar cobranças