PequiPay API – Documentação para Desenvolvedores

🚀 PequiPay API v1

API REST para processamento de pagamentos. Aceite Pix, cartão de crédito e boleto no seu e-commerce em minutos.

Base URL: https://pequipay.com/api/v1

Quick Start

Crie sua primeira cobrança em 3 passos:

# 1. Obtenha sua API Key no dashboard
# 2. Crie uma cobrança Pix
curl -X POST https://pequipay.com/api/v1/charges \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "payment_method": "pix",
    "description": "Pedido #1234",
    "customer": {
      "name": "João Silva",
      "email": "[email protected]",
      "document": "123.456.789-00"
    }
  }'

# 3. Exiba o QR Code Pix para o cliente pagar

🔐 Autenticação

Todas as requisições devem incluir o header Authorization com sua Secret Key:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tipo	Formato	Uso
`pk_live_xxx`	Public Key	Frontend (checkout.js)
`sk_live_xxx`	Secret Key	Backend (API calls)

⚠️ Nunca exponha sua Secret Key no frontend. Use apenas no servidor.

⚠️ Erros

A API retorna erros em formato JSON consistente:

{
  "error": {
    "code": "validation_error",
    "message": "Missing required fields: amount",
    "fields": ["amount"]
  }
}

HTTP Code	Significado
200	Sucesso
201	Criado com sucesso
400	Requisição inválida
401	Não autenticado
422	Erro de validação
429	Rate limit excedido
500	Erro interno

Criar Cobrança

Cria uma nova cobrança para o cliente efetuar pagamento.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`amount`	float	✅	Valor em reais (ex: 150.00)
`payment_method`	string		`pix`, `credit_card`, `boleto`, `debit`
`description`	string		Descrição da cobrança
`customer.name`	string		Nome do pagador
`customer.email`	string		E-mail do pagador
`customer.document`	string		CPF/CNPJ
`metadata`	object		Dados extras (até 50 campos)

Resposta (201)

{
  "charge": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "object": "charge",
    "amount": 150.00,
    "currency": "BRL",
    "status": "pending",
    "payment_method": "pix",
    "pix": {
      "qr_code": "data:image/svg+xml;base64,...",
      "qr_code_text": "00020126580014br.gov.bcb.pix...",
      "expiration": "2026-05-07T17:30:00"
    },
    "created_at": "2026-05-07T17:00:00"
  }
}

Consultar Cobrança

curl https://pequipay.com/api/v1/charges/a1b2c3d4-e5f6-... \
  -H "Authorization: Bearer sk_live_xxx"

Listar Cobranças

Query Param	Descrição
`page`	Página (default: 1)
`per_page`	Itens por página (max: 100)
`status`	Filtrar por status

Simular Pagamento (Sandbox)

Simula o pagamento de uma cobrança pendente. Disponível apenas em modo sandbox.

curl -X POST https://pequipay.com/api/v1/charges/a1b2c3d4.../pay \
  -H "Authorization: Bearer sk_live_xxx"

Cancelar Cobrança

Criar Estorno

curl -X POST https://pequipay.com/api/v1/refunds \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "charge_id": "a1b2c3d4-e5f6-...",
    "amount": 50.00,
    "reason": "Cliente solicitou estorno"
  }'

Consultar Saldo

{
  "balance": {
    "available": 8600.50,
    "pending": 1650.00,
    "total_received": 10750.50,
    "total_refunded": 500.00,
    "total_withdrawn": 1650.00,
    "currency": "BRL"
  }
}

Dados do Merchant

🔔 Webhooks

Receba notificações em tempo real quando eventos ocorrem nas suas cobranças. Configure a URL de webhook no dashboard.

Payload enviado

{
  "event": "charge.paid",
  "data": {
    "id": "a1b2c3d4-...",
    "amount": 150.00,
    "status": "paid",
    ...
  },
  "timestamp": "2026-05-07T17:00:00+00:00"
}

Eventos Disponíveis

Evento	Descrição
`charge.created`	Cobrança criada
`charge.paid`	Pagamento confirmado
`charge.failed`	Pagamento falhou
`charge.refunded`	Estorno processado
`charge.expired`	Cobrança expirou
`charge.cancelled`	Cobrança cancelada

Verificar Assinatura

Valide a autenticidade do webhook verificando o header X-PequiPay-Signature:

// PHP
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PEQUIPAY_SIGNATURE'];
$secret = 'whsec_seu_secret_aqui';

$expected = hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Webhook válido ✅
    $event = json_decode($payload, true);
    // Processar evento...
} else {
    http_response_code(403);
    // Assinatura inválida ❌
}