Dashboard

Produtos

Criar Produto

Cria um novo produto ou serviço com nome, descrição, preço e configurações de recorrência.

POST/v1/products
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Os produtos criados ficam disponíveis no painel administrativo e podem ser utilizados tanto no checkout transparente (via API) quanto no checkout pro (link de pagamento).

Tipos de recorrência em prices[].recurrenceType:

  • ONE_TIME → Avulsa
  • WEEKLY → Semanal
  • MONTHLY → Mensal
  • QUARTERLY → Trimestral
  • SEMIANNUAL → Semestral
  • YEARLY → Anual

Case de uso:

Como SaaS, quero cadastrar meus planos como produtos com preços recorrentes, para que meus clientes possam assinar diretamente pelo checkout pro ou pela minha própria interface.

Authorizations

bearer

Authorization

string obrigatório

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

Escopos requeridos

products/write

Body

application/json

Content-Type:application/json
JSON
{
  "name": "Plano Premium",
  "description": "Acesso completo à plataforma",
  "type": "RECURRING",
  "statementDescriptor": "VALIDAPAY PREMIUM",
  "isActive": true,
  "metadata": {},
  "emitirNf": false,
  "nfConfigId": "nfc_1788364755079_psuecwgdc",
  "tipoNf": "B2C",
  "fiscal": {
    "descricaoServico": "Assinatura de plataforma",
    "codigoTributacaoNacionalIss": "010101",
    "codigoTributarioMunicipio": "0101",
    "tributacaoIss": 1,
    "tipoRetencaoIss": 1,
    "aliquota": 2.5,
    "ncm": "00000000",
    "cfop": "5102",
    "icms": 0,
    "pis": 0,
    "cofins": 0
  },
  "productUrlPurchased": "https://meusite.com/area-do-aluno",
  "sendEmail": ["recurrence.activated", "recurrence.payment.success", "recurrence.payment.failed", "trial.started"],
  "sendWhatsApp": ["+5511999998888"],
  "sendWebhook": ["https://meusite.com/webhook"],
  "contactCompanyName": "Minha Empresa LTDA",
  "contactEmail": "suporte@minhaempresa.com",
  "contactPhone": "+5511999998888",
  "contactPhoneIsWhatsapp": true,
  "contactWhatsappMessage": "Ola, preciso de ajuda com meu pedido",
  "messageRuler": [
    {
      "templateName": "LEMBRETE_VENCIMENTO_PROXIMO",
      "offsetDays": -3,
      "sendAtTime": "11:00"
    }
  ],
  "prices": [
    {
      "title": "Mensal",
      "amount": 99.9,
      "currency": "BRL",
      "recurrenceType": "MONTHLY",
      "recurrenceInterval": 1,
      "trialDays": 7,
      "compareAtPrice": 129.9
    },
    {
      "title": "Anual",
      "amount": 899.0,
      "currency": "BRL",
      "recurrenceType": "YEARLY",
      "recurrenceInterval": 1
    }
  ]
}

Schema

namestringobrigatório
Nome do produto
pricesarray[2]obrigatório
descriptionstringopcional
typestringopcional
RECURRING cobra todo ciclo, ONE_TIME cobra uma vez (default RECURRING)
Valores aceitos:RECURRINGONE_TIME
statementDescriptorstringopcional
max 22 caracteres
isActivebooleanopcional
metadataobjectopcional
Objeto livre, aceita as chaves e valores que você quiser
emitirNfbooleanopcional
Emite nota fiscal a cada cobrança deste produto (default false)
nfConfigIdstringopcional
Configuração fiscal usada na emissão; exige endereço do comprador
tipoNfstringopcional
Público da nota: consumidor final ou empresa
Valores aceitos:B2CB2B
fiscalobjectopcional
Dados fiscais do produto, usados na nota
productUrlPurchasedstringopcional
Link entregue ao comprador após o pagamento
Regra:uri
sendEmailarray[4]opcional
Eventos que disparam e-mail deste produto. Os eventos recurrence.*, subscription.*, invoice.*, pix.*, boleto.*, trial.started, oneoff.* e payment.failed avisam o comprador; new.sale e seller.* avisam você. recurrence.activated é o e-mail do primeiro pagamento aprovado da assinatura, e a partir do segundo ciclo vale subscription.renewed. Sem o campo, ou com a lista vazia, nenhum e-mail é enviado
Valores aceitos:recurrence.activatedrecurrence.payment.successrecurrence.pix.generatedrecurrence.boleto.generatedrecurrence.card.pendingsubscription.renewedsubscription.overdueinvoice.overduesubscription.canceledsubscription.canceled.boleto_pixtrial.startedrecurrence.payment.failedrecurrence.payment.refundedrecurrence.nf.issuedinvoice.reminder.10dinvoice.reminder.5dinvoice.reminder.1dinvoice.reminder.todaypix.reminder.10dpix.reminder.5dpix.reminder.1dpix.reminder.todayoneoff.payment.successoneoff.card.pendingoneoff.payment.refundedoneoff.nf.issuedpix.generatedboleto.generatedpayment.failednew.saleseller.subscription.renewedseller.charge.pending
sendWhatsApparray[1]opcional
Números avisados a cada venda deste produto
sendWebhookarray[1]opcional
URLs chamadas a cada venda deste produto
contactCompanyNamestringopcional
Nome exibido ao comprador no checkout e na nota
contactEmailstringopcional
E-mail de suporte exibido ao comprador
Regra:email
contactPhonestringopcional
Telefone de suporte exibido ao comprador
contactPhoneIsWhatsappbooleanopcional
Mostra o telefone de suporte como WhatsApp
contactWhatsappMessagestringopcional
Mensagem que o comprador envia ao clicar no WhatsApp
messageRulerarray[1]opcional
Régua de lembretes por WhatsApp antes e depois do vencimento
const url = 'https://sandbox.validapay.com.br/v1/products';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "name": "Plano Premium",
  "description": "Acesso completo à plataforma",
  "type": "RECURRING",
  "statementDescriptor": "VALIDAPAY PREMIUM",
  "isActive": true,
  "metadata": {},
  "emitirNf": false,
  "nfConfigId": "nfc_1788364755079_psuecwgdc",
  "tipoNf": "B2C",
  "fiscal": {
    "descricaoServico": "Assinatura de plataforma",
    "codigoTributacaoNacionalIss": "010101",
    "codigoTributarioMunicipio": "0101",
    "tributacaoIss": 1,
    "tipoRetencaoIss": 1,
    "aliquota": 2.5,
    "ncm": "00000000",
    "cfop": "5102",
    "icms": 0,
    "pis": 0,
    "cofins": 0
  },
  "productUrlPurchased": "https://meusite.com/area-do-aluno",
  "sendEmail": ["recurrence.activated", "recurrence.payment.success", "recurrence.payment.failed", "trial.started"],
  "sendWhatsApp": ["+5511999998888"],
  "sendWebhook": ["https://meusite.com/webhook"],
  "contactCompanyName": "Minha Empresa LTDA",
  "contactEmail": "suporte@minhaempresa.com",
  "contactPhone": "+5511999998888",
  "contactPhoneIsWhatsapp": true,
  "contactWhatsappMessage": "Ola, preciso de ajuda com meu pedido",
  "messageRuler": [
    {
      "templateName": "LEMBRETE_VENCIMENTO_PROXIMO",
      "offsetDays": -3,
      "sendAtTime": "11:00"
    }
  ],
  "prices": [
    {
      "title": "Mensal",
      "amount": 99.9,
      "currency": "BRL",
      "recurrenceType": "MONTHLY",
      "recurrenceInterval": 1,
      "trialDays": 7,
      "compareAtPrice": 129.9
    },
    {
      "title": "Anual",
      "amount": 899.0,
      "currency": "BRL",
      "recurrenceType": "YEARLY",
      "recurrenceInterval": 1
    }
  ]
})
};

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

Response Examples

200▾
JSON
{
  "productId": "prod_xxx",
  "name": "Plano Premium",
  "prices": [
    {
      "priceId": "price_xxx",
      "amount": 99.9,
      "checkoutUrl": "https://app.validapay.com.br/pagamento/pl_xxx"
    }
  ]
}
400▾
JSON
{
    "error": {
        "message": "O campo name é obrigatório",
        "code": "INVALID_PRODUCT_DATA",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Saldo subcontas

Próximo →

Listar Produtos