Primeira integração

​

Pré-requisitos

• Conta em app.wovepay.com
• Backend ou ferramenta que faça HTTP (curl, Postman, seu servidor)
• URL HTTPS pública para webhooks (em dev, use ngrok ou similar)

​

1. Criar a chave de API

1. Acesse Integrações → API
2. Clique em Nova chave
3. Preencha:
   • Descrição: ex. Produção ERP
   • Escopo / permissões: comece com Escrita ou Leitura + payment-pix/create e webhooks/create
4. Copie o wp_live_... — ele aparece uma única vez

export WovePay_API_KEY=wp_live_SUA_CHAVE

​

2. Testar autenticação

curl https://api.wovepay.com/v1/account/balance \
  -H "X-API-Key: $WovePay_API_KEY"

{
  "success": true,
  "message": "OK",
  "data": {
    "currency": "BRL",
    "availableAmount": 0,
    "pendingAmount": 0
  },
  "requestId": "req_..."
}

​

3. Criar uma cobrança PIX

curl -X POST https://api.wovepay.com/v1/payment-pix/create \
  -H "X-API-Key: $WovePay_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1,
    "description": "Teste integração",
    "coverFee": false,
    "externalReference": "pedido-001"
  }'

​

4. Cadastrar webhook

curl -X POST https://api.wovepay.com/v1/webhooks/create \
  -H "X-API-Key: $WovePay_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.suaempresa.com/WovePay/webhook",
    "events": ["payment.paid", "payment.created", "payment.pix.expired"]
  }'

​

5. Confirmar o pagamento

1. Sua URL recebe POST com evento payment.paid
2. Valide x-WovePay-signature com o whsec_...
3. Use data.externalReference para marcar o pedido como pago no seu sistema

​

Checklist de produção

• Chave com permissões mínimas (não use full sem necessidade)
• WovePay_API_KEY em secret manager, nunca no repositório
• Webhook com HTTPS e validação HMAC
• Idempotência pelo id da entrega webhook
• externalReference em toda cobrança para reconciliação
• Tratamento de 429 (100 req/min por chave)

​

Próximos passos