Checkout Transparente

Referência

Checkout Transparente é a forma de cobrar sem sair da sua própria tela: você coleta os dados do comprador na sua interface e envia direto para a API, em vez de redirecionar para uma página de pagamento hospedada pela ValidaPay. Um único endpoint atende os quatro métodos, e o campo paymentMethod decide o restante do comportamento.

Como funciona

•As quatro cobranças (PIX, Pix Automático, Boleto e Cartão) usam a mesma rota, POST /v1/charges. Não existem rotas separadas por método.
•Toda cobrança precisa de um produto (items com priceId) ou de um valor avulso (amount), nunca os dois ao mesmo tempo.
•Em conta sandbox (accountNumber começando com SANDBOX_), pix, boleto e cartão são simulados sem chamar nenhum provedor externo. Cartão em sandbox é sempre aprovado na hora.
•Cartão é síncrono: a cobrança já nasce aprovada ou recusada na própria resposta. PIX, Pix Automático e Boleto nascem pendentes e são confirmados depois, quando o banco do pagador processa o pagamento.

Campos comuns aos quatro métodos

Os campos específicos de cada método (como card ou boletoInstructions) estão documentados na página de cada endpoint. Estes valem para os quatro:

Campo	Descrição
`paymentMethod`	Obrigatório. Define o fluxo: pix, pix_automatico, boleto ou creditcard.
`customer`	Obrigatório: name, email e documentNumber (CPF ou CNPJ). address é opcional, exceto quando a conta tem nota fiscal configurada.
`items ou amount`	Envie items com priceId para um produto cadastrado, ou amount para uma cobrança avulsa. Nunca os dois.
`externalId`	Chave de idempotência do pedido. Reenviar o mesmo valor recusa a segunda tentativa com 409 DUPLICATE_CHARGE.
`externalTxid`	Identifica a loja, o caixa ou o vendedor responsável pela cobrança. Não interfere na idempotência.
`metadata`	Aceito no corpo, mas não é gravado na cobrança nem volta no webhook desta rota. Use externalId para correlacionar com o seu pedido.
`card, tokenId ou paymentMethodId`	Só para creditcard: informe um dos três com os dados do cartão (bruto ou já tokenizado).
`boletoInstructions, dueDate, boletoDueDays`	Só para boleto: personalizam multa, juros, desconto e vencimento.

Resposta por método de pagamento

Todas as respostas de sucesso trazem success, customerId e chargeId. O que muda é o bloco extra:

paymentMethod	HTTP	Bloco específico
`pix`	200	pix: { emv, qrCode }
`pix_automatico`	200	pix: { emv, recurrencyId }, sem qrCode
`boleto`	200	boleto: { digitableLine, barCode, dueDate, pdfUrl }
`creditcard (aprovado)`	200	nenhum bloco extra: só success, customerId e chargeId
`creditcard (recusado)`	402	success: false, status: "CHARGE_FAILED", error: { message }

JSON

{
  "success": true,
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "chargeId": "cha_1774530966959_frgj3ptax",
  "pix": {
    "emv": "00020126330014br.gov.bcb.pix...6304ABCD",
    "qrCode": "data:image/png;base64,iVBORw0KGgo..."
  }
}

JSON

{
  "success": true,
  "customerId": "cus_1770483634516_pwj5e9k4f",
  "chargeId": "cha_1774530966959_frgj3ptax",
  "boleto": {
    "digitableLine": "23793.38128 60007.827136 95000.063305 9 84410000010000",
    "barCode": "23799844100000100003381260007827139500006330",
    "dueDate": "2026-07-30",
    "pdfUrl": "https://api.validapay.com.br/v1/charges/cha_1774530966959_frgj3ptax/boleto.pdf"
  }
}

Não confunda com Cobrança Imediata (POST /v1/charges/pix): naquele endpoint o QR Code vem solto na raiz da resposta (emv, qrCode), sem nenhum objeto pix. Cada rota tem seu próprio formato de resposta: confira sempre a página do endpoint específico antes de escrever o parser da sua integração.

Cartão recusado (402)

Uma recusa de cartão não usa o envelope padrão { error: { message, code, details, timestamp } } dos demais erros da API. É uma resposta de negócio com status 402:

JSON

{
  "success": false,
  "status": "CHARGE_FAILED",
  "error": {
    "message": "Saldo insuficiente no cartão"
  }
}

chargeId não vem nesse corpo: a cobrança falha antes de ser exposta na resposta. Para rastrear a tentativa, use o externalId que você enviou, ou consulte o evento payment.failed disparado no seu webhook.

Idempotência e metadata

•externalId funciona como chave de idempotência. Reenviar a mesma cobrança com o mesmo valor é recusado com 409 DUPLICATE_CHARGE, trazendo o chargeId da cobrança original em error.details.chargeId.
•Se dois envios com o mesmo externalId chegarem quase ao mesmo tempo, o segundo pode receber 409 DUPLICATE_IN_PROGRESS enquanto o primeiro ainda está sendo processado. Tente de novo em instantes.
•metadata é aceito no corpo, mas não é gravado na cobrança nem volta no webhook desta rota. Use externalId para correlacionar com o seu pedido.

JSON

{
  "error": {
    "message": "Cobrança duplicada: já existe uma cobrança para este pedido",
    "code": "DUPLICATE_CHARGE",
    "details": { "chargeId": "cha_1784065113577_5dw2oyfic" },
    "timestamp": "2026-07-14T21:39:36.322Z"
  }
}

Requisitos do Pix Automático

•Conta PJ (CNPJ). Fora do sandbox, uma conta PF recebe PIX_AUTOMATICO_PJ_ONLY; em conta sandbox essa checagem não é aplicada.
•Valor mínimo de R$ 4,99 por cobrança, inclusive no sandbox.
•items com um price de recorrência (WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL ou YEARLY). Não aceita amount avulso.
•Enquanto o banco do pagador não confirma a adesão, a assinatura fica com status PENDING.

Erros comuns

Fora da recusa de cartão (acima), os demais erros seguem o envelope padrão { error: { message, code, details, timestamp } }.

code	Status	Quando acontece
`INVALID_DATA`	400	Corpo não passou na validação: campo obrigatório ausente, formato inválido, ou creditcard sem card/tokenId/paymentMethodId.
`PRICE_NOT_FOUND`	404	O priceId de algum item não existe.
`PRODUCT_NOT_FOUND`	404	O produto associado ao price não existe.
`ITEMS_REQUIRED`	400	Nem items nem amount foram enviados.
`DUPLICATE_CHARGE`	409	O externalId já foi usado em outra cobrança. details.chargeId traz o identificador da cobrança original.
`PIX_AUTOMATICO_PJ_ONLY`	400	paymentMethod é pix_automatico e a conta não é PJ. Não se aplica em conta sandbox.
`PIX_AUTOMATICO_MIN_AMOUNT`	400	Valor da cobrança abaixo de R$ 4,99 com paymentMethod pix_automatico. Vale também no sandbox.
`CARD_TOKENIZATION_FAILED`	400	Não foi possível validar os dados de card informados (fora do sandbox).
`ADDRESS_REQUIRED`	400	A conta tem nota fiscal configurada e customer.address não foi enviado.

Webhooks relacionados

Cartão dispara a confirmação de forma síncrona, junto com a própria resposta. PIX, Pix Automático e Boleto ficam pendentes e são confirmados depois, quando o pagamento chega:

•payment.success: Pagamento confirmado. O payload difere entre cobrança avulsa via Pix direto e cobrança vinculada a uma assinatura.
•payment.failed: Tentativa de pagamento falhou. Schema próprio: não carrega a base de assinatura e usa `accountId`.
•payment.overdue: Ciclo vencido sem pagamento. A assinatura passa a `DEFAULT` quando estava `ACTIVE`, ou a `PAST_DUE` quando estava `PENDING` ou `TRIALING`.

Ver todos os eventos de webhook

Perguntas frequentes

Por que o campo pix muda de formato dependendo do método?▾

pix devolve pix.emv e pix.qrCode (o QR Code já em base64). pix_automatico devolve pix.emv e pix.recurrencyId, sem qrCode. Um boleto híbrido (que também aceita pagamento via Pix) ganha um boleto.pix aninhado com emv, transactionId e transactionIdentification: um objeto diferente do pix da raiz, sem qrCode nem recurrencyId. Confira sempre a seção "Resposta por método de pagamento" acima antes de assumir o formato.

O que acontece se eu reenviar a mesma cobrança com o mesmo externalId?▾

A segunda tentativa é recusada com 409 DUPLICATE_CHARGE antes de qualquer cobrança ser gerada de novo. O corpo do erro traz o chargeId da cobrança original em error.details.chargeId, então você pode consultá-la em vez de criar uma nova.

Cartão recusado é um erro do meu lado (exceção HTTP)?▾

Não é uma exceção: é uma resposta de negócio com HTTP 402 e success: false. Trate como um resultado possível do fluxo de pagamento, não como uma falha de integração. O evento payment.failed também é disparado para o seu webhook nesse momento.

Por que o metadata que enviei não aparece na cobrança nem no webhook?▾

Essa rota aceita o campo mas não persiste. Use externalId para correlacionar a cobrança com o seu pedido interno. Hoje, metadata só é persistido em POST /v1/charges/pix (Cobrança Imediata), um endpoint diferente do Checkout Transparente.

Pix Automático funciona em qualquer conta?▾

Fora do sandbox, só em contas PJ (CNPJ); uma conta PF recebe PIX_AUTOMATICO_PJ_ONLY. Em conta sandbox essa checagem não é aplicada, então dá para testar o fluxo completo com uma conta de teste PF. O valor mínimo de R$ 4,99 por cobrança vale nos dois ambientes.

Próximos passos

Gerar cobrança PIX Gerar cobrança Pix Automático Gerar cobrança Boleto Gerar cobrança Cartão Simular pagamentos: como confirmar uma cobrança pendente no sandbox

Essa página foi útil?