Integre seu site ao
gateway GeralPay

Criar pagamento PIX

Endereço obrigatório na Fyntra

Use o campo payer.address (com dois “d”). Em produção, a Fyntra exige o endereço completo e o telefone com DDD. O sandbox não consulta a adquirente; uma simulação aprovada não confirma que os dados serão aceitos em produção.

{
  "method": "pix",
  "amount": "49.90",
  "external_reference": "pedido-1001",
  "description": "Pedido #1001",
  "payer": {
    "name": "Maria Silva",
    "email": "maria@email.com",
    "document": "52998224725",
    "phone": "11987654321",
    "address": {
      "street": "Avenida Paulista",
      "streetNumber": "1000",
      "zipCode": "01310100",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "country": "BR"
    }
  }
}

Dados retornados

{
  "sucesso": true,
  "mensagem": "Pagamento criado com sucesso.",
  "pagamento": {
    "referencia": "PIX-123456",
    "external_reference": "pedido-1001",
    "ambiente": "test",
    "status": "pending",
    "valor_bruto": 49.9,
    "taxa": 0,
    "valor_liquido": 49.9,
    "checkout_url": "https://geralpay.com/checkout?token=chk_7db91e4c...",
    "pix": {
      "copia_e_cola": "GERAL_PAY_SANDBOX_PIX-123456_..."
    }
  }
}

cURL

curl -X POST "https://geralpay.com/api/v1/payments" \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: pk_test_xxxxxxxxx" \
  -H "X-Secret-Key: $GERAL_SECRET_KEY" \
  -H "Idempotency-Key: pedido-1001-pix-1" \
  -d '{
    "method": "pix",
    "amount": "49.90",
    "external_reference": "pedido-1001",
    "description": "Pedido #1001",
    "payer": {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "document": "52998224725",
      "phone": "11987654321",
      "address": {
        "street": "Avenida Paulista",
        "streetNumber": "1000",
        "zipCode": "01310100",
        "neighborhood": "Bela Vista",
        "city": "Sao Paulo",
        "state": "SP",
        "country": "BR"
      }
    }
  }'

JavaScript no backend (Node.js)

const response = await fetch("https://geralpay.com/api/v1/payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Public-Key": process.env.GERAL_PUBLIC_KEY,
    "X-Secret-Key": process.env.GERAL_SECRET_KEY,
    "Idempotency-Key": "pedido-1001-pix-1"
  },
  body: JSON.stringify({
    method: "pix",
    amount: "49.90",
    external_reference: "pedido-1001",
    description: "Pedido #1001",
    payer: {
      name: "Maria Silva",
      email: "maria@email.com",
      document: "52998224725",
      phone: "11987654321",
      address: {
        street: "Avenida Paulista",
        streetNumber: "1000",
        zipCode: "01310100",
        neighborhood: "Bela Vista",
        city: "Sao Paulo",
        state: "SP",
        country: "BR"
      }
    }
  })
});

const data = await response.json();

if (!data.sucesso) {
  throw new Error(data.mensagem || "Erro ao criar PIX");
}

console.log(data.pagamento.pix.copia_e_cola);

Consultar o status pela referência

Use as mesmas chaves nos cabeçalhos para consultar o status, os valores, a origem e as datas da cobrança.

Cadastrar a URL de notificação

{
  "url": "https://loja.com/webhooks/geral-pay",
  "events": ["pagamento.aprovado"]
}

O cadastro habilita as notificações de cobranças criadas pela API e pelo painel. Guarde o secret retornado e responda com HTTP 2xx após validar e persistir o evento. O processamento das entregas depende do worker de webhooks.

Payload de pagamento aprovado

{
  "id": "evt_f4e159c5f8db7f4d6c6628ae",
  "event": "pagamento.aprovado",
  "created_at": "2026-07-26T15:42:18-03:00",
  "data": {
    "reference": "PIX-615312",
    "external_reference": "pedido-1001",
    "environment": "live",
    "status": "approved",
    "method": "pix",
    "amount": 49.90,
    "fee": 0,
    "net_amount": 49.90,
    "currency": "BRL",
    "description": "Pedido #1001",
    "origin": "api",
    "checkout_url": "https://geralpay.com/checkout?token=chk_7db91e4c...",
    "acquirer_reference": "abc123",
    "updated_at": "2026-07-26T15:42:18-03:00",
    "payer": {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "document": "52998224725",
      "phone": "11987654321"
    }
  }
}

Validar assinatura HMAC

Calcule HMAC-SHA256(timestamp + "." + corpo_json_bruto, secret) e compare com X-Geral-Signature no formato sha256=<hash>. O timestamp está em X-Geral-Timestamp.

$raw = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_GERAL_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_GERAL_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac(
  'sha256',
  $timestamp . '.' . $raw,
  $webhookSecret
);

if (abs(time() - (int) $timestamp) > 300 || !hash_equals($expected, $received)) {
  http_response_code(401);
  exit;
}

http_response_code(204);

Entregas com falha são repetidas em intervalos progressivos. Não há IP fixo garantido; valide sempre a assinatura HMAC.

Reenviar o evento de uma cobrança existente

{
  "reference": "PIX-615312"
}

Envie esse JSON para POST https://geralpay.com/api/v1/webhooks. Um novo evento é criado sem creditar o saldo novamente.

Erros comuns

Antes de publicar sua integração

Confirme se sua conta está aprovada, se a chave da API está ativa e se o checkout coleta os dados completos do pagador.