Cupons

Validar Cupom

POST/v1/coupons/validate

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

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

Authorizations

noauth

string obrigatório

Endpoint público, sem autenticação — pensado para ser chamado do frontend do próprio cliente para validar um código de cupom antes de aplicá-lo numa cobrança ou checkout.

Sempre responde 200. Quando o cupom não é válido, valid=false e reason traz o motivo (COUPON_NOT_FOUND, COUPON_INACTIVE, COUPON_NOT_STARTED, COUPON_EXPIRED, COUPON_EXHAUSTED, MIN_AMOUNT_NOT_MET, PRODUCT_NOT_ELIGIBLE, COUPON_NOT_APPLICABLE, COUPON_ALREADY_USED).

Quando válido, devolve os dados do cupom necessários para calcular o efeito no checkout: para discountType=PERCENTAGE ou FIXED, use discountValue (e maxDiscount) para calcular o desconto. Para discountType=EXTRA_PERIOD, não há desconto a aplicar no valor — mostre uma mensagem como "+N dia(s)/mês(es) grátis" e deixe o efeito para a próxima cobrança.

Body

application/json

Content-Type:application/json

JSON

{
  "code": "BEMVINDO10",
  "amount": 199.90,
  "productIds": ["price_1788364755079_psuecwgdc"],
  "chargeType": "RECURRING",
  "customerDocument": "12345678901"
}

Schema

codestringobrigatório

Código digitado pelo cliente

amountnumberopcional

Valor do pedido, usado para checar minAmount e calcular o desconto

productIdsarray[1]opcional

Price IDs do pedido, usados para checar restrição de produto

chargeTypestringopcional

Tipo da cobrança sendo montada (default RECURRING)

Valores aceitos:RECURRINGONE_TIME

customerDocumentstringopcional

CPF/CNPJ do cliente, usado para checar firstTimeOnly

← Anterior

Remover Cupom

Validar Cupom por ID

const url = 'https://sandbox.validapay.com.br/v1/coupons/validate';

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "code": "BEMVINDO10",
  "amount": 199.90,
  "productIds": ["price_1788364755079_psuecwgdc"],
  "chargeType": "RECURRING",
  "customerDocument": "12345678901"
})
};

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

Response Examples

200200 válido▾

JSON

{
  "valid": true,
  "coupon": {
    "code": "BEMVINDO10",
    "name": "Cupom de boas-vindas",
    "description": "10% na primeira cobrança",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "maxCycles": 3,
    "maxDiscount": 30.0,
    "validUntil": "2026-12-31T23:59:59.000Z",
    "appliesTo": "RECURRING",
    "firstTimeOnly": true
  }
}

200200 inválido▾

JSON

{
  "valid": false,
  "reason": "COUPON_EXPIRED"
}

← Anterior

Remover Cupom

Validar Cupom por ID