Links de pagamento
Referência
A ValidaPay oferece duas formas de gerar uma página de pagamento hospedada sem escrever checkout transparente: o link de pagamento, reutilizável, e a sessão de pagamento, de uso único. Este guia explica quando usar cada um e o que muda por trás de cada rota.
Link ou sessão de pagamento
Link de pagamento (POST /v1/checkouts, identificador pl_) cria uma página configurável, reutilizável e não vinculada a um cliente específico. É a URL certa para divulgar uma oferta em vários canais e deixar qualquer cliente pagar por ela.
Sessão de pagamento (POST /v1/checkout-sessions, identificador cs_) cria um acesso temporário e individual a um price já cadastrado, com os dados do cliente pré-preenchidos. É a URL certa para gerar um link nominal por cliente no momento da contratação.
Comparativo
| Aspecto | Link de pagamento | Sessão de pagamento |
|---|---|---|
| Endpoint de criação | POST /v1/checkouts | POST /v1/checkout-sessions |
| Prefixo do identificador | pl_ (ou SANDBOX_pl_) | cs_ (ou SANDBOX_cs_) |
| Reuso | Reutilizável: a mesma URL pode ser paga por clientes diferentes, várias vezes | Pensada para uso único, por um cliente específico |
| Cliente pré-preenchido | Não | Opcional, via customer no corpo da requisição |
| Criar produto/preço inline | Sim, com product no corpo (mesma validação de Criar Produto) | Não: exige um priceId já cadastrado |
| Expiração | Não expira sozinho: fica active até você desativar | Expira sozinho 30 dias após a criação, se não for usada |
| Depois de pago | Continua active e reutilizável | No cartão aprovado o status vira completed na hora; no Pix e no boleto a sessão fica active até o pagamento ser confirmado, para o comprador poder reabrir o link e pagar o código já emitido |
| Atualização | PUT /v1/checkouts/:id | Não existe endpoint de atualização |
| Consulta | GET /v1/checkouts/:id, autenticado, valida o dono | GET /v1/checkout-sessions/:id, público |
Criar um link ou uma sessão
Em ambos os endpoints, é obrigatório informar um priceId de um preço já cadastrado. Só o link de pagamento aceita, como alternativa, um objeto product inline (com prices dentro), que passa pela mesma validação de Criar Produto e cria produto e preço na hora.
Resposta do link
{
"id": "pl_xxx",
"url": "https://app.validapay.com.br/pagamento/pl_xxx",
"priceId": "price_xxx"
}Resposta da sessão
{
"id": "cs_abc123",
"url": "https://app.validapay.com.br/pagamento/cs_abc123",
"priceId": "price_abc123"
}Na sessão, o objeto opcional customer pré-preenche nome, e-mail, documento, telefone e endereço no checkout. Um items[] opcional permite sobrescrever o item principal por uma lista de priceId e quantity.
Formas de pagamento e Pix Automático
allowedPaymentMethods aceita pix, creditcard, boleto e pix_automatico. No link de pagamento o campo é obrigatório; na sessão é opcional e, se omitido, a sessão usa o padrão do price.
PENDING. O valor mínimo por cobrança é R$ 4,99.Atualizar link de pagamento
PUT /v1/checkouts/:id altera só os campos enviados: priceId (troca o preço vinculado), descontos, limite de parcelas, cores e os links de termos de serviço e política de privacidade. Não existe endpoint equivalente para a sessão de pagamento, que é imutável após criada.
Enviando applyBrandingToAllPrices: true, a API propaga primaryColor, secondaryColor, fontColor e showProductImage para o produto e para todo outro checkout ativo que use um price do mesmo produto.
Consultar status
GET /v1/checkouts/:id é autenticado e valida que o checkout pertence à conta do token. O status do link é active, inactive (desativado, por exemplo ao arquivar o produto) ou completed.
GET /v1/checkout-sessions/:id é público, pensado para a própria página de pagamento consultar os dados. O status da sessão é active, completed (já paga) ou expired (30 dias sem uso).
Quando a sessão tem um Pix ou um boleto emitido e ainda não pago, a resposta traz também chargeId, transactionId e o bloco pix ou boleto com o código já gerado. É isso que permite reabrir o link e continuar o mesmo pagamento, em vez de esperar o código anterior expirar para gerar outro.
O que a API permite
| Operação | Descrição |
|---|---|
| Criar link de pagamento | priceId existente ou product inline; formas de pagamento, cores e order bumps configuráveis. |
| Listar links de pagamento | Lista paginada, com filtro por status e busca textual. |
| Buscar link de pagamento | Detalhes completos de um checkout, autenticado. |
| Atualizar link de pagamento | Troca de preço, parcelamento, aparência e propagação de branding. |
| Criar sessão de pagamento | Acesso de uso único a um price, com cliente pré-preenchido. |
| Buscar sessão de pagamento | Consulta pública do status e dos itens de uma sessão. |
Erros comuns
| code | Status | Quando acontece |
|---|---|---|
INVALID_DATA | 400 | Corpo não passa na validação Zod ao criar um link ou uma sessão. |
INVALID_PRODUCT_DATA | 400 | O objeto product enviado inline no link de pagamento não passa na validação de produto. Não se aplica à sessão, que não aceita product inline. |
PRICE_NOT_FOUND | 404 | priceId informado não existe, ao criar ou atualizar um link, ou ao criar uma sessão. |
PRICE_INACTIVE | 400 | O price informado existe mas está inativo, por exemplo porque foi removido do produto. Vale para o price principal e para os itens enviados em items. |
PRODUCT_NOT_FOUND | 404 | O price existe, mas o produto vinculado a ele não foi encontrado. |
PIX_AUTOMATICO_PJ_ONLY | 400 | allowedPaymentMethods inclui pix_automatico e a conta autenticada não é PJ. |
PIX_AUTOMATICO_MIN_AMOUNT | 400 | allowedPaymentMethods inclui pix_automatico e o valor do price é menor que R$ 4,99. |
CHECKOUT_NOT_FOUND | 404 | :id não corresponde a nenhum link de pagamento, ao buscar ou atualizar. |
FORBIDDEN | 401 | O link, a sessão ou o preço referenciado pertence a outra conta. |
SESSION_NOT_FOUND | 404 | :id não corresponde a nenhuma sessão de pagamento. |
SESSION_EXPIRED | 400 | A sessão encontrada já passou dos 30 dias de validade sem ser usada. |