Checkouts

O checkout é a página de pagamento hospedada pela Valora em pay.valorapayments.com.br. O cliente informa os dados, escolhe a forma de pagamento e paga. Você não precisa construir formulário de cartão nem tela de QR Code. Existem duas formas de levar o cliente ao checkout:

Forma	Quando usar	Como criar
Link fixo	vender um produto por link (WhatsApp, Instagram, bio, e-mail)	no painel, em Checkouts
Checkout pela API	uma compra criada pelo seu sistema para um pedido específico	`POST /v1/checkouts`

Link fixo

O link fixo (https://pay.valorapayments.com.br/c/chk_...) aponta para um produto e serve para quantas vendas você quiser. Cada cliente que abre o link começa uma compra nova. No painel, você define o produto, a aparência da página e para onde o cliente volta depois de pagar ou desistir.

O link fixo não exige código. Para saber quando uma venda foi paga, cadastre um webhook ou acompanhe pelo painel.

Checkout pela API

Use quando o seu sistema já tem um pedido e quer que o cliente pague aquele pedido. O preço vem do produto e fica travado no momento da criação.

Crie a compra no seu servidor

curl https://api.valorapayments.com.br/v1/checkouts \
  -H "Authorization: Bearer $VALORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [{ "product_id": "prod_Ab12Cd34Ef56Gh78", "quantity": 1 }],
    "customer": { "name": "Ana Souza", "email": "ana@example.com" },
    "allowed_payment_method_types": ["pix", "card"],
    "success_url": "https://sualoja.com/pedido/1001/obrigado",
    "cancel_url": "https://sualoja.com/carrinho",
    "external_reference": "pedido-1001"
  }'

Redirecione o cliente

A resposta traz o checkout_url. Redirecione o cliente para ele:

{
  "id": "cs_Qw12Er34Ty56Ui78",
  "object": "checkout_session",
  "status": "open",
  "checkout_url": "https://pay.valorapayments.com.br/s/cs_Qw12Er34Ty56Ui78",
  "amount": { "subtotal": 14990, "total": 14990, "currency": "BRL" },
  "allowed_payment_method_types": ["pix", "card"],
  "payment_id": null,
  "external_reference": "pedido-1001",
  "expires_at": "2026-11-15T18:00:00.000Z"
}

Confirme pelo webhook

Quando o cliente paga, você recebe payment.succeeded. O pagamento traz o mesmo external_reference e o mesmo metadata que você enviou na compra.

Opções da compra

Campo	O que faz
`product_cart`	exatamente 1 item, com `product_id` de um produto ativo e `quantity` de 1 a 100
`customer`	`{ "customer_id": "cus_..." }` de um cliente salvo, ou `{ name, email, phone }` para preencher o formulário
`allowed_payment_method_types`	quais formas aparecem: `pix`, `card`, `boleto` (padrão: todas)
`success_url` / `cancel_url`	para onde o cliente volta depois de pagar ou desistir (HTTPS)
`expires_in`	validade do link em segundos, de 300 (5 min) a 86400 (24 h). Padrão: 24 h
`external_reference` / `metadata`	seus identificadores; seguem para o pagamento e para os webhooks

Os detalhes de cada campo estão em Criar um checkout.

Status da compra

Status	Significado
`open`	aguardando o cliente pagar
`processing`	pagamento em análise (por exemplo, cartão em análise antifraude)
`paid`	pago
`failed`	a tentativa falhou (cartão recusado, Pix com valor diferente)
`expired`	o prazo da compra acabou sem pagamento

Consulte a qualquer momento com GET /v1/checkouts/{session_id}. Mesmo assim, use o webhook como fonte da confirmação.

O que o checkout já faz por você

Validação dos dados

Confere CPF e CNPJ pelo dígito verificador, o número do cartão e a validade antes de enviar.

Proteção contra testes de cartão

O pagamento com cartão passa por verificação anti-robô e por limites de tentativas. Depois de 3 recusas na mesma compra, o cartão é bloqueado naquela compra e o cliente pode pagar por Pix ou boleto.

Troca de forma de pagamento

Gerou um Pix e mudou de ideia? O cliente volta e escolhe outra forma sem perder os dados.

Comprovante por e-mail

Quando o pagamento é confirmado, o cliente recebe um comprovante no e-mail informado.

Compra vencida

Num link fixo, uma compra vencida vira uma compra nova. Numa compra criada pela API, o cliente vê a tela de pagamento expirado e o link de volta para a sua loja.

Começando

Recursos

Integrar

Frameworks

IA e agentes

Ajuda

Link fixo

Checkout pela API

Opções da compra

Status da compra

O que o checkout já faz por você

Próximos passos

Formas de pagamento

Webhooks