Configurações

Atualizar configurações

Altera as configurações da assinatura: emissão e prazo das cobranças, formas de pagamento aceitas, repasse de taxas, nota fiscal, e-mails em cópia e instruções de boleto e Pix. Envie só os campos que quer mudar.

PATCH/v1/subscriptions/:subscriptionId

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

O que acontece com a cobrança: as mudanças valem para as próximas cobranças emitidas; cobranças já emitidas não mudam.

Quando o corpo traz instruções e configurações juntas, a resposta é a das configurações.

Authorizations

bearer

Authorization

string obrigatório

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

Escopos requeridos

subscriptions/write

Path Parameters

subscriptionIdstringobrigatório

ID da assinatura (ex: sub_xxx) - required

Body

application/json

Content-Type:application/json

JSON

{
    "issueDaysBeforeDue": 5, 
    "expirationAfterDueDate": 30, 
    "allowConcurrentCycles": false, 
    "passFeesToCustomer": false, 
    "nfConfigId": null, 
    "allowedPaymentMethods": ["creditcard", "pix", "boleto"], 
    "additionalEmails": ["financeiro@empresa.com"], 
    "boletoInstructions": { 
        "fine": 2.0, 
        "interest": 1.0 
    }
}

Schema

issueDaysBeforeDuenumberopcional

Dias antes do vencimento em que o boleto ou Pix é emitido (0 a 60). null volta ao padrão

expirationAfterDueDatenumberopcional

Dias depois do vencimento em que ainda pode ser paga (0 a 60)

Regra:0 a 60

allowConcurrentCyclesbooleanopcional

true: permite cobrar um ciclo novo com outro em aberto

passFeesToCustomerbooleanopcional

true: repassa as taxas do cartão ao cliente

nfConfigIdobjectopcional

Configuração de nota fiscal. null desliga a emissão

allowedPaymentMethodsarray[3]opcional

Formas de pagamento aceitas na fatura

Valores aceitos:creditcardpixboletopix_automatico

additionalEmailsarray[1]opcional

E-mails em cópia (até 5)

Regra:email

boletoInstructionsobjectopcional

Multa, juros e desconto do boleto. null remove

← Anterior

Aplicar desconto em uma cobrança

Cancelar assinatura

const url = 'https://sandbox.validapay.com.br/v1/subscriptions/:subscriptionId';

const options = {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "issueDaysBeforeDue": 5, 
    "expirationAfterDueDate": 30, 
    "allowConcurrentCycles": false, 
    "passFeesToCustomer": false, 
    "nfConfigId": null, 
    "allowedPaymentMethods": ["creditcard", "pix", "boleto"], 
    "additionalEmails": ["financeiro@empresa.com"], 
    "boletoInstructions": { 
        "fine": 2.0, 
        "interest": 1.0 
    }
})
};

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

Response Examples

200configurações▾

JSON

{
    "success": true, 
    "type": "SETTINGS_UPDATED", 
    "subscriptionId": "sub_xxx", 
    "settings": { 
        "issueDaysBeforeDue": 5, 
        "expirationAfterDueDate": 30, 
        "allowConcurrentCycles": false, 
        "passFeesToCustomer": false, 
        "nfConfigId": null, 
        "allowedPaymentMethods": ["creditcard", "pix", "boleto"], 
        "additionalEmails": [] 
    }
}

Campos da resposta

successboolean

true quando as configurações foram salvas

typestring

Configurações alteradas

subscriptionIdstring

ID da assinatura

settingsobject

Configurações depois da alteração

200instruções de boleto e Pix▾

JSON

{
    "success": true,
    "subscriptionId": "sub_xxx",
    "boletoInstructions": { "fine": 2.0, "interest": 1.0 } 
}

Campos da resposta

successboolean

subscriptionIdstring

boletoInstructionsobject

Instruções de boleto salvas

400sem campos▾

JSON

{
    "error": {
        "message": "Informe ao menos um campo: boletoInstructions, pixInstructions, issueDaysBeforeDue, expirationAfterDueDate, allowConcurrentCycles, passFeesToCustomer, nfConfigId, allowedPaymentMethods, additionalEmails",
        "code": "INVALID_DATA",
        "details": null,
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Aplicar desconto em uma cobrança

Cancelar assinatura