Checkouts

Criar Checkout

POST/v1/checkouts

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

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

Autenticação

bearerAuthorizationstring · header · obrigatório

Envie no header:

Authorization: Bearer {{token}}

Cria uma página de pagamento configurável com produtos, formas de pagamento aceitas, cupons e aparência personalizada.

Criar payment link (oferta)

Scopes: checkouts/write. Link reutilizável, sem cliente pré-preenchido. Obrigatório priceId ou product.

Campo	Obrig.	Tipo	Descrição
`priceId`	✅*	string	ID do preço
`product`	✅*	object	Produto + preços inline (alternativa)
`allowedPaymentMethods`	✅	string[]	`pix` `creditcard` `boleto`
`successUrl`/`cancelUrl`/`redirectAfterPaymentUrl`	❌	string	URLs
`maxInstallments`	❌	number	1–12
`freeInstallments`	❌	number	1–12 (default 1)
`passFeesToCustomer`	❌	boolean	default false
`primaryColor`/`secondaryColor`/`fontColor`	❌	string	hex
`showProductImage`	❌	boolean	default true
`orderBumps`	❌	array	Produtos adicionais

Body

application/json

Content-Type:application/json

{
  "priceId": "price_xxx",
  "allowedPaymentMethods": [
    "pix",
    "creditcard",
    "boleto"
  ],
  "successUrl": "https://meusite.com/obrigado",
  "cancelUrl": "https://meusite.com/cancelado",
  "redirectAfterPaymentUrl": "https://meusite.com/redirect",
  "successMessage": "Obrigado pela compra!",
  "maxInstallments": 12,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "checkoutName": "Oferta Black Friday",
  "primaryColor": "#7C3AED",
  "secondaryColor": "#EDE9FE",
  "fontColor": "#1F2937",
  "showProductImage": true,
  "metadata": {},
  "orderBumps": [
    {
      "priceId": "price_yyy",
      "label": "Adicionar suporte premium",
      "displayMode": "checkbox"
    }
  ]
}

Schema

Field	Type	Required	Description
priceId	string	-	-
allowedPaymentMethods[3]	array	-	-
successUrl	string	-	-
cancelUrl	string	-	-
redirectAfterPaymentUrl	string	-	-
successMessage	string	-	-
maxInstallments	number	-	-
freeInstallments	number	-	-
passFeesToCustomer	boolean	-	-
checkoutName	string	-	-
primaryColor	string	-	-
secondaryColor	string	-	-
fontColor	string	-	-
showProductImage	boolean	-	-
metadata	object	-	-
orderBumps[1]	array	-	-

Headers

Name	Type	Value	Required
Content-Type	-	application/json	Optional

← Anterior

Baixar Boleto

Listar Checkouts

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

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "priceId": "price_xxx",
  "allowedPaymentMethods": [
    "pix",
    "creditcard",
    "boleto"
  ],
  "successUrl": "https://meusite.com/obrigado",
  "cancelUrl": "https://meusite.com/cancelado",
  "redirectAfterPaymentUrl": "https://meusite.com/redirect",
  "successMessage": "Obrigado pela compra!",
  "maxInstallments": 12,
  "freeInstallments": 1,
  "passFeesToCustomer": false,
  "checkoutName": "Oferta Black Friday",
  "primaryColor": "#7C3AED",
  "secondaryColor": "#EDE9FE",
  "fontColor": "#1F2937",
  "showProductImage": true,
  "metadata": {},
  "orderBumps": [
    {
      "priceId": "price_yyy",
      "label": "Adicionar suporte premium",
      "displayMode": "checkbox"
    }
  ]
})
};

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

Response Examples

200200

{
  "id": "pl_xxx",
  "url": "https://app.validapay.com.br/pagamento/pl_xxx",
  "priceId": "price_xxx"
}

← Anterior

Baixar Boleto

Listar Checkouts