Documentação da API PinaCash v2.0

curl -H "Accept: application/json" https://api.pinacash.com/health

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "timestamp": "2026-03-20T01:00:00-03:00"
  }
}

{
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Descrição do erro",
    "errors": ["campo X é obrigatório"]
  }
}

X-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "event": "payment.paid",
  "timestamp": "2026-02-11T15:02:15Z",
  "data": {
    "transaction_id": "TX-ABC123",
    "external_id": "pedido_12345",
    "amount": 150.00,
    "amount_cents": 15000,
    "status": "PAID",
    "payer_name": "Joao Silva",
    "payer_document": "12345678900",
    "merchant_id": 7,
    "end_to_end_id": "E12345678202602111502ABCD",
    "offer_id": 123,
    "paid_at": "2026-02-11T15:02:15Z"
  }
}

signature = HMAC-SHA256(payload_json, SHA256(webhook_secret))

// 1. Seu webhook secret (gerado ao criar o webhook no painel)
$webhookSecret = 'whsec_SEU_SECRET_AQUI';

// 2. Ler payload e assinatura
$payload = file_get_contents('php://input');
$receivedSignature = $_SERVER['HTTP_X_PINACASH_SIGNATURE'] ?? '';

// 3. Calcular assinatura esperada
//    Chave = SHA-256 do secret (nao o secret cru)
$expectedSignature = hash_hmac(
    'sha256',
    $payload,
    hash('sha256', $webhookSecret)
);

// 4. Comparar (timing-safe)
if (!hash_equals($expectedSignature, $receivedSignature)) {
    http_response_code(401);
    error_log('[PinaCash] Assinatura HMAC invalida');
    exit('Invalid signature');
}

// 5. Headers adicionais
$eventName = $_SERVER['HTTP_X_PINACASH_EVENT'] ?? 'unknown';
$webhookId = $_SERVER['HTTP_X_PINACASH_WEBHOOK_ID'] ?? '';

// 6. Processar
$data = json_decode($payload, true);
$event = $data['event'] ?? 'unknown';

switch ($event) {
    case 'payment.paid':
        // Marcar pedido como pago
        break;
    case 'payment.created':
        // Cobranca criada
        break;
    case 'withdrawal.completed':
        // Saque concluido
        break;
}

// 7. SEMPRE responder 200 (evita retentativas)
http_response_code(200);
echo json_encode(['received' => true]);

const crypto = require('crypto');

function verifyWebhook(payload, receivedSignature, webhookSecret) {
  // Chave = SHA-256 do secret
  const key = crypto.createHash('sha256').update(webhookSecret).digest('hex');
  const expected = crypto
    .createHmac('sha256', key)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSignature)
  );
}

// Uso no Express:
app.post('/webhook/pinacash', (req, res) => {
  const payload = req.body; // raw body string
  const sig = req.headers['x-pinacash-signature'];
  const event = req.headers['x-pinacash-event'];

  if (!verifyWebhook(payload, sig, 'whsec_SEU_SECRET')) {
    return res.status(401).send('Invalid signature');
  }

  const data = JSON.parse(payload);
  console.log(`Evento: ${data.event}`);

  res.status(200).json({ received: true });
});

import hmac, hashlib

def verify_webhook(payload: bytes, received_sig: str, secret: str) -> bool:
    key = hashlib.sha256(secret.encode()).hexdigest()
    expected = hmac.new(key.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_sig)

# Uso no Flask:
@app.route('/webhook/pinacash', methods=['POST'])
def webhook():
    payload = request.get_data()
    sig = request.headers.get('X-PINACASH-SIGNATURE', '')
    event = request.headers.get('X-PINACASH-EVENT', '')

    if not verify_webhook(payload, sig, 'whsec_SEU_SECRET'):
        return 'Invalid signature', 401

    data = request.json
    print(f"Evento: {data['event']}")

    return jsonify({'received': True}), 200

checkout_view → form_start → form_complete → pix_generated → pix_copied → payment_paid → converted

<script>
(function() {
  var offerId = 123; // Seu offer_id
  var visitorId = 'v_' + Math.random().toString(36).substr(2,12);
  fetch('https://api.pinacash.com/public/offer-collect.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      offer_id: offerId,
      visitor_id: visitorId,
      page_url: location.href,
      referrer: document.referrer
    })
  });
})();
</script>

1. Visitante clica anúncio → URL contém ?fbclid=xxx ou ?gclid=xxx
2. JS do checkout (ads-loader.js) captura e envia via tracking/collect
3. EventRecorder grava na coluna dedicada em gateway_events
4. AdsEventDispatcher inclui click IDs no payload server-side
5. Meta CAPI / GA4 MP recebem para atribuição de conversão

composer require pinacash/pinacash-php

use PinaCash\PinaCash;

$pinacash = new PinaCash('pk_live_xxx', 'sk_live_xxx');

// Criar cobrança PIX
$pix = $pinacash->pix->charge([
    'amount'     => 100.00,
    'external_id' => 'pedido_123',
    'customer'  => [
        'name'     => 'João Silva',
        'document' => '12345678900',
        'email'    => 'joao@email.com'
    ]
]);

echo $pix->qr_code_base64;
echo $pix->pix_code;

// Consultar saldo
$balance = $pinacash->balance->get();
echo "Disponível: R$ " . $balance->available;

// Payout
$payout = $pinacash->pix->payout([
    'amount'  => 50.00,
    'pix_key' => 'email@destino.com'
]);

npm install @pinacash/pinacash-node

const PinaCash = require('@pinacash/pinacash-node');

const pinacash = new PinaCash('pk_live_xxx', 'sk_live_xxx');

// Criar cobrança
const pix = await pinacash.pix.charge({
  amount: 100.00,
  external_id: 'pedido_123',
  customer: {
    name: 'João Silva',
    document: '12345678900'
  }
});

console.log(pix.pix_code);
console.log(pix.qr_code_base64);

pip install pinacash

from pinacash import PinaCash

client = PinaCash('pk_live_xxx', 'sk_live_xxx')

# Criar cobrança
pix = client.pix.charge(
    amount=100.00,
    external_id='pedido_123',
    customer={
        'name': 'João Silva',
        'document': '12345678900'
    }
)

print(pix.pix_code)
print(pix.qr_code_base64)