COMECE AQUI

Quickstart: Pix do zero em 3 passos

Fluxo completo: autenticar → criar cobrança Pix → exibir QR Code. Use o ambiente sandbox para testar antes de ir para produção.

1

Autenticar

Obter Bearer Token com OAuth2

2

Criar cobrança

POST /v1/charges com paymentMethod pix

3

Exibir resultado

Renderizar qrCode e emv da response

Base URL sandbox: https://sandbox.validapay.com.br — pagamentos não são reais nesse ambiente.

1

Autenticar

Use suas credenciais client_id e client_secret para obter um Bearer Token. Para criar cobrança Pix, o scope necessário é pix.cob/write.

POST https://oauth2-sandbox.validapay.com.br/auth/token
curl -X POST "https://oauth2-sandbox.validapay.com.br/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=pix.cob/write"
Response 200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Salve o access_token. Ele expira em 1 hora.

2

Criar cobrança Pix

Campos ✅ obrigatórios: paymentMethod, amount, title. O campo expiration é opcional — sem ele o QR Code não tem prazo de expiração. Formato das datas: YYYY-MM-DD.

POST https://sandbox.validapay.com.br/v1/charges
curl -X POST "https://sandbox.validapay.com.br/v1/charges" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "pix",
    "amount": 100.00,
    "title": "Pedido #12345",
    "description": "Camiseta azul P",
    "expiration": "2026-12-31",
    "customer": {
      "name": "João da Silva",
      "documentNumber": "12345678901",
      "email": "joao@email.com"
    }
  }'
CampoObrig.Formato / Observação
paymentMethod✅"pix"
amount✅Número em reais — ex: 100.00
title✅2 a 100 caracteres
expiration❌Formato YYYY-MM-DD — ex: "2026-12-31". Se omitido: sem expiração.
dueDate❌Formato YYYY-MM-DD. Vencimento (pagamento sem juros até essa data). Deve ser anterior a expiration.
customer❌Dados do pagador. Quando informar dueDate, inclua também name, documentNumber e cep.
3

Exibir QR Code ao cliente

A response retorna dois campos para exibir ao cliente:

Response 200 OK
{
  "chargeId": "cha_abc123",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "emv": "00020126580014br.gov.bcb.pix...",
  "metadata": {}
}

qrCode

Imagem do QR Code em base64 (data URI). Use diretamente em uma tag <img>:

<img src={charge.qrCode} alt="QR Code Pix" />

emv

Código Pix Copia e Cola (padrão EMV). Exiba em um botão de copiar para o cliente colar no app do banco.

navigator.clipboard.writeText(charge.emv)

Receber confirmação de pagamento

Configure um webhook para receber notificação assim que o cliente pagar. Você também pode consultar o status manualmente via GET /v1/charges/:chargeId.

POST ${SEU_WEBHOOK_URL} — payload recebido pela ValidaPay
{
  "event": "payment.success",
  "chargeId": "cha_abc123",
  "status": "PAID",
  "amount": 100.00,
  "paidAt": "2026-06-19T14:35:27Z"
}

Boas práticas

  • Nunca exponha seu access_token no frontend — faça as chamadas sempre pelo backend.
  • Valide a assinatura dos webhooks para garantir que vieram da ValidaPay.
  • Use externalTxid para evitar cobranças duplicadas em retentativas.
  • Troque a base URL para https://api.validapay.com.br quando for para produção.

Próximos Passos