Subcontas

Atualizar subconta

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

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.

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

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

Schema

accountNumberstringobrigatório

Número da subconta. Precisa estar vinculada à sua conta principal

dailyWithdrawalLimitnumberopcional

Limite diário de saque da subconta, em reais

withdrawalPixKeystringopcional

Chave Pix de destino dos saques da subconta. `null` remove

masterFeeobjectopcional

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

Headers

Content-Typetextopcional

application/json

← Anterior

Listar subcontas

Taxa padrão das novas subcontas

const url = 'https://sandbox.validapay.com.br/v1/accounts/subaccounts';

const options = {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "accountNumber": "4960589",
    "dailyWithdrawalLimit": 3000,
    "withdrawalPixKey": "saques@empresa.com",
    "masterFee": {
        "pix": {
            "type": "percentage",
            "amount": 0.5
        },
        "boleto": {
            "type": "fixed",
            "amount": 2
        }
    }
})
};

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

Response Examples

200▾

JSON

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

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

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-06T18:20:00.000Z"
  }
}

← Anterior

Listar subcontas

Taxa padrão das novas subcontas