Documentação do Gateway

Integre PIX (cash-in/cash-out) com seleção de provider (WishPag / Versell) e webhooks.
Ver página de vendas Entrar Baixar PDF

Visão geral

Este gateway expõe endpoints para criar cobranças PIX (cash-in), solicitar saques (cash-out) e receber confirmações via webhooks. No Admin, você define qual adquirente usar por operação (WishPag / Versell / Auto).

Cash-inQR Code + Copia e Cola
Cash-outPIX para chave (telefone/e-mail/CPF/CNPJ/aleatória)
WebhooksAtualização automática de status
Importante: Webhooks devem estar acessíveis via HTTPS público. Em produção, habilite logs e valide assinatura (HMAC / token) conforme sua adquirente.

Quickstart

  1. Configure as credenciais no Admin (ou no .env).
  2. Defina CASHIN_PROVIDER e CASHOUT_PROVIDER.
  3. Teste um depósito (cash-in) e valide o retorno do QR.
  4. Configure webhooks no painel da adquirente.

Exemplo de .env:

WISHPAG_SECRET_KEY=SEU_SECRET
WISHPAG_COMPANY_ID=SUA_EMPRESA

VERSELL_VSPI=SEU_VSPI
VERSELL_VSPS=SEU_VSPS

# auto | wishpag | versell
CASHIN_PROVIDER=wishpag
CASHOUT_PROVIDER=wishpag

Endpoints

Criar cobrança PIX (cash-in)

POST /libs/funcoes/gerar_pix.php

Body sugerido:

{
  "valor": 100.00,
  "user_id": 1,
  "descricao": "Pedido #123",
  "local_id": "pedido_123"
}

Solicitar saque PIX (cash-out)

POST /libs/funcoes/gerar_saque.php

Body sugerido:

{
  "valor": 50.00,
  "pix": "11999999999",
  "tipo": "telefone",
  "local_id": "saque_456"
}

Dica: sempre envie um local_id único por operação. Ele facilita conciliação e atualização de status via webhook.

WishPag

Use WishPag quando quiser padronizar com Idempotency-Key e conciliação via local_id. Para webhook: 

http://pagpix.site/libs/wishpag/webhook.php

Versell

Versell retorna o QR via base64 + código de pagamento. Configure o webhook para atualizações: 

http://pagpix.site/libs/versell/webhook.php

Webhooks

Ao receber uma confirmação, o sistema tenta localizar a transação por local_id e/ou external_id e atualiza o status em transactions.status.

Rotas:

POST /libs/wishpag/webhook.php
POST /libs/versell/webhook.php
Recomendação: valide assinatura/token do provedor (quando disponível) e faça allowlist de IPs se sua adquirente publicar ranges oficiais.

Exemplos • PHP

cURL (cash-in):

curl -X POST http://pagpix.site/libs/funcoes/gerar_pix.php \
  -H "Content-Type: application/json" \
  -d '{"valor":100,"user_id":1,"descricao":"Pedido #123","local_id":"pedido_123"}'

PHP (file_get_contents):

<?php
$url = "http://pagpix.site/libs/funcoes/gerar_pix.php";
$payload = [
  "valor" => 100.00,
  "user_id" => 1,
  "descricao" => "Pedido #123",
  "local_id" => "pedido_123",
];
$ctx = stream_context_create([
  "http" => [
    "method" => "POST",
    "header" => "Content-Type: application/json\r\n",
    "content" => json_encode($payload),
    "timeout" => 20,
  ]
]);
$res = file_get_contents($url, false, $ctx);
echo $res;

Exemplos • Node.js

Fetch:

const res = await fetch('http://pagpix.site/libs/funcoes/gerar_pix.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ valor: 100, user_id: 1, descricao: 'Pedido #123', local_id: 'pedido_123' })
});
const data = await res.json();
console.log(data);

Axios:

import axios from 'axios';
const { data } = await axios.post('http://pagpix.site/libs/funcoes/gerar_pix.php', {
  valor: 100,
  user_id: 1,
  descricao: 'Pedido #123',
  local_id: 'pedido_123'
});
console.log(data);

Exemplos • Laravel

HTTP Client (Illuminate\\Support\\Facades\\Http):

use Illuminate\Support\Facades\Http;

$resp = Http::timeout(20)->post('http://pagpix.site/libs/funcoes/gerar_pix.php', [
  'valor' => 100,
  'user_id' => 1,
  'descricao' => 'Pedido #123',
  'local_id' => 'pedido_123',
]);

$data = $resp->json();
// $data['pixCopiaECola'] / $data['qrCodeBase64']
Dica Laravel: para robustez, envie local_id com um UUID, registre status no seu banco e finalize o pedido apenas após webhook.

SDK (PHP)

O SDK simplifica chamadas ao gateway. Arquivo incluído: /libs/sdk/PagPixClient.php. 

<?php
require_once __DIR__ . "/libs/sdk/PagPixClient.php";

$client = new PagPixClient("http://pagpix.site");

$pix = $client->createPix([
  "valor" => 100.00,
  "user_id" => 1,
  "descricao" => "Pedido #123",
  "local_id" => "pedido_123",
]);

$saque = $client->createCashout([
  "valor" => 50.00,
  "pix" => "11999999999",
  "tipo" => "telefone",
  "local_id" => "saque_456",
]);

Segurança (produção)

  • Ative HTTPS obrigatório e HSTS.
  • Use Idempotency-Key e local_id único para evitar duplicidade.
  • Valide assinatura/token nos webhooks sempre que disponível.
  • Logue todas requisições/retornos (sem expor segredos).
  • Restrinja o Admin por IP, e use senhas fortes + 2FA.

Troubleshooting

Erros comuns e correções rápidas:

  • 404 /public/index.php → seu Nginx está apontando pra /public mas o projeto está na raiz.
  • 500 → verifique logs do PHP/Nginx e permissões em libs/*.
  • Webhook não chega → confirme URL pública/HTTPS e liberação de firewall.

Baixe o PDF para envio ao cliente:

http://pagpix.site/documentacao_pdf.php
Copiado