Pix

O Pix é a forma de pagamento mais rápida: o cliente paga pelo app do banco e a confirmação chega em segundos. Você pode cobrar Pix de duas formas:

No checkout (link fixo ou POST /v1/checkouts): a Valora mostra o QR Code ao cliente.
Direto pela API (POST /v1/payments): você recebe o QR Code e o copia e cola e mostra na sua própria tela.

Criar uma cobrança Pix pela API

cURL
Node.js
Python

curl https://api.valorapayments.com.br/v1/payments \
  -H "Authorization: Bearer $VALORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1001" \
  -d '{
    "method": "pix",
    "amount": "149.90",
    "description": "Pedido 1001",
    "external_reference": "pedido-1001",
    "expires_in": 1800
  }'

const res = await fetch("https://api.valorapayments.com.br/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VALORA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "pedido-1001",
  },
  body: JSON.stringify({
    method: "pix",
    amount: "149.90",
    description: "Pedido 1001",
    external_reference: "pedido-1001",
    expires_in: 1800,
  }),
});
const payment = await res.json();
// payment.pix.brcode  -> copia e cola
// payment.pix.qr_image -> QR Code (PNG em data URL)

import os, requests

res = requests.post(
    "https://api.valorapayments.com.br/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['VALORA_API_KEY']}",
        "Idempotency-Key": "pedido-1001",
    },
    json={
        "method": "pix",
        "amount": "149.90",
        "description": "Pedido 1001",
        "external_reference": "pedido-1001",
        "expires_in": 1800,
    },
)
payment = res.json()

Valor: em reais ou pelo produto

Envie um dos dois:

amount: valor em reais, como texto ou número, com até 2 casas ("149.90", 149.9).
product_id + quantity: a Valora calcula o valor pelo preço do produto. O cliente não consegue mudar o preço.

Na entrada, o valor vai em reais. Nas respostas, todo valor vem em centavos inteiros: "149.90" volta como 14990.

Validade

expires_in define quanto tempo o Pix vale, em segundos: de 60 (1 min) a 86400 (24 h). O padrão é 3600 (1 h). Depois disso, o pagamento muda para expired e você recebe payment.expired.

Exibir para o cliente

Campo	Uso
`pix.qr_image`	QR Code em PNG, pronto para `<img src="...">`
`pix.brcode`	código copia e cola
`expires_at`	prazo para mostrar um cronômetro

Ciclo de vida

Status	Significado	Evento
`requires_payment`	Pix criado, aguardando pagamento	—
`succeeded`	pago e confirmado	`payment.succeeded`
`expired`	o prazo acabou sem pagamento	`payment.expired`
`canceled`	cancelado por você antes do pagamento	`payment.canceled`
`partially_refunded` / `refunded`	parte ou todo o valor foi devolvido ao pagador	`payment.refunded`

Um Pix pago com valor diferente do cobrado, ou pago depois de cancelado, não vira crédito automaticamente. Ele fica marcado para análise da Valora e não libera o pedido.

Quem pagou

Depois da confirmação, pix.payer traz o nome e o documento mascarado de quem pagou, e pix.e2e_id traz o identificador da transação no Banco Central. Use para conciliar e para atender o cliente.

Cancelar um Pix

Enquanto o Pix está em requires_payment, você pode cancelar com POST /v1/payments/{payment_id}/cancel. O QR Code deixa de valer.

Saldo

O valor de um Pix confirmado entra no saldo disponível na hora, já descontada a taxa.

Começando

Recursos

Integrar

Frameworks

IA e agentes

Ajuda

Criar uma cobrança Pix pela API

Valor: em reais ou pelo produto

Validade

Exibir para o cliente

Ciclo de vida

Quem pagou

Cancelar um Pix

Saldo

Próximos passos

Devoluções

Idempotência