Início rápido

Em cerca de 10 minutos você obtém um token, cadastra o webhook e cria sua primeira cobrança Pix. Os exemplos usam variáveis de ambiente para que nenhum segredo apareça no código.

Antes de começar

Use apenas no servidor. Defina as variáveis no ambiente (ou cofre de segredos) — nunca no código, no front-end ou em prompts de IA:

Terminal

export SHARKPAY_BASE_URL="https://sharkpay.com.br"
export SHARKPAY_PUBLIC_KEY="PUB-..."   # painel → Perfil
export SHARKPAY_SECRET_KEY="SEC-..."   # painel → Perfil (não compartilhe)

1. Habilite os meios de pagamento

No painel, confirme que o método desejado (Pix, boleto, cartão) está habilitado para sua conta. Sem isso a criação responde 400 informando que a forma de pagamento não está habilitada.

2. Obtenha o token

Troque as chaves por um token Bearer. Ele vale por padrão 30 dias (expires_in informa em segundos).

POST /api/auth

#!/usr/bin/env bash
# Obter token de acesso (chave pública + chave secreta em HTTP Basic)
set -euo pipefail
: "${SHARKPAY_BASE_URL:?}" "${SHARKPAY_PUBLIC_KEY:?}" "${SHARKPAY_SECRET_KEY:?}"
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/auth" \
  -u "$SHARKPAY_PUBLIC_KEY:$SHARKPAY_SECRET_KEY"
echo

// Obter token de acesso — Node.js 18+
const basic = Buffer.from(`${process.env.SHARKPAY_PUBLIC_KEY}:${process.env.SHARKPAY_SECRET_KEY}`).toString('base64');

const res = await fetch(`${process.env.SHARKPAY_BASE_URL}/api/auth`, {
  method: 'POST',
  headers: { Authorization: `Basic ${basic}` },
  signal: AbortSignal.timeout(30_000),
});
const data = await res.json().catch(() => ({}));
if (!res.ok) { console.error(res.status, data); process.exit(1); }

// Guarde o token em memória/cofre e renove ao expirar (expires_in, em segundos).
console.log(JSON.stringify(data.success, null, 2));

# Obter token de acesso — Python 3.9+ (pip install requests)
import os, sys
import requests

res = requests.post(
    os.environ["SHARKPAY_BASE_URL"] + "/api/auth",
    auth=(os.environ["SHARKPAY_PUBLIC_KEY"], os.environ["SHARKPAY_SECRET_KEY"]),  # HTTP Basic
    timeout=30,
)
data = res.json() if res.content else {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Obter token de acesso — PHP 8+ com ext-curl
$ch = curl_init(getenv('SHARKPAY_BASE_URL') . '/api/auth');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_USERPWD => getenv('SHARKPAY_PUBLIC_KEY') . ':' . getenv('SHARKPAY_SECRET_KEY'), // HTTP Basic
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, ' ', $response, PHP_EOL;
exit($status === 200 ? 0 : 1);

Resposta 200

{
  "success": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 2592000
  }
}

Exporte o token: export SHARKPAY_TOKEN="eyJ0eXAi..."

3. Configure o webhook

Informe a URL https pública do seu servidor. Na primeira vez a resposta traz o segredo de assinatura (whsec_…) — guarde-o: ele não é mostrado de novo.

PUT /api/webhook

#!/usr/bin/env bash
# Configurar a URL do webhook
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
curl -sS --fail-with-body -X PUT "$SHARKPAY_BASE_URL/api/webhook" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "'"$WEBHOOK_URL"'"
}'
echo

// Configurar a URL do webhook — Node.js 18+ (fetch nativo, sem dependências)
import { randomUUID } from 'node:crypto';

const BASE = process.env.SHARKPAY_BASE_URL;
const TOKEN = process.env.SHARKPAY_TOKEN;

const body = {
  url: process.env.WEBHOOK_URL,
};

const headers = { Authorization: `Bearer ${TOKEN}` };
headers['Content-Type'] = 'application/json';
const res = await fetch(`${BASE}/api/webhook`, {
  method: 'PUT',
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000), // sempre defina um timeout
});
const data = await res.json().catch(() => ({}));
console.log(res.status, JSON.stringify(data, null, 2));
if (!res.ok) process.exit(1);

# Configurar a URL do webhook — Python 3.9+ (pip install requests)
import os, sys, uuid
import requests

BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]

body = {
    "url": os.environ["WEBHOOK_URL"],
}

headers = {"Authorization": f"Bearer {TOKEN}"}
res = requests.put(BASE + "/api/webhook", headers=headers, json=body, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Configurar a URL do webhook — PHP 8+ com ext-curl

$base  = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");

$body = [
    'url' => getenv("WEBHOOK_URL"),
];

$ch = curl_init($base . '/api/webhook');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30, // sempre defina um timeout
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $response, PHP_EOL;
exit($status >= 200 && $status < 300 ? 0 : 1);

Depois valide o receptor com um evento de teste: POST /api/webhook/test. Veja Webhooks para verificar a assinatura.

4. Crie a cobrança Pix

Envie sempre um Idempotency-Key único por pedido. Se a rede cair, repita a mesma chamada com a mesma chave.

POST /api/pix/create

#!/usr/bin/env bash
# Criar cobrança Pix
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
DUE=$(date -d "+7 days" +%F 2>/dev/null || date -v+7d +%F)  # vencimento daqui a 7 dias
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/pix/create" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY:-$(uuidgen)}" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 100,
  "quantity": 2,
  "discount": 10,
  "tax": 5,
  "invoice_no": "PED-1001",
  "due_date": "'"$DUE"'",
  "item_name": "Camiseta",
  "email": "maria@example.com",
  "document": "12345678909",
  "client": "Maria Souza",
  "notes": "Pedido 1001"
}'
echo

// Criar cobrança Pix — Node.js 18+ (fetch nativo, sem dependências)
import { randomUUID } from 'node:crypto';

const BASE = process.env.SHARKPAY_BASE_URL;
const TOKEN = process.env.SHARKPAY_TOKEN;
const dueDate = new Date(Date.now() + 7 * 864e5).toISOString().slice(0, 10); // vencimento em 7 dias

const body = {
  amount: 100,
  quantity: 2,
  discount: 10,
  tax: 5,
  invoice_no: "PED-1001",
  due_date: dueDate,
  item_name: "Camiseta",
  email: "maria@example.com",
  document: "12345678909",
  client: "Maria Souza",
  notes: "Pedido 1001",
};

const headers = { Authorization: `Bearer ${TOKEN}` };
headers['Content-Type'] = 'application/json';
headers['Idempotency-Key'] = process.env.IDEMPOTENCY_KEY ?? randomUUID(); // reutilize a MESMA chave ao repetir a operação
const res = await fetch(`${BASE}/api/pix/create`, {
  method: 'POST',
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000), // sempre defina um timeout
});
const data = await res.json().catch(() => ({}));
console.log(res.status, JSON.stringify(data, null, 2));
if (!res.ok) process.exit(1);

# Criar cobrança Pix — Python 3.9+ (pip install requests)
import os, sys, uuid
from datetime import date, timedelta
import requests

BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]
due_date = (date.today() + timedelta(days=7)).isoformat()  # vencimento em 7 dias

body = {
    "amount": 100,
    "quantity": 2,
    "discount": 10,
    "tax": 5,
    "invoice_no": "PED-1001",
    "due_date": due_date,
    "item_name": "Camiseta",
    "email": "maria@example.com",
    "document": "12345678909",
    "client": "Maria Souza",
    "notes": "Pedido 1001",
}

headers = {"Authorization": f"Bearer {TOKEN}"}
headers["Idempotency-Key"] = os.environ.get("IDEMPOTENCY_KEY", str(uuid.uuid4()))  # reutilize a MESMA chave ao repetir
res = requests.post(BASE + "/api/pix/create", headers=headers, json=body, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Criar cobrança Pix — PHP 8+ com ext-curl

$base  = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");
$dueDate = date('Y-m-d', strtotime('+7 days')); // vencimento em 7 dias

$body = [
    'amount' => 100,
    'quantity' => 2,
    'discount' => 10,
    'tax' => 5,
    'invoice_no' => 'PED-1001',
    'due_date' => $dueDate,
    'item_name' => 'Camiseta',
    'email' => 'maria@example.com',
    'document' => '12345678909',
    'client' => 'Maria Souza',
    'notes' => 'Pedido 1001',
];

$ch = curl_init($base . '/api/pix/create');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30, // sempre defina um timeout
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
        "Content-Type: application/json",
        "Idempotency-Key: " . (getenv("IDEMPOTENCY_KEY") ?: bin2hex(random_bytes(16))), // reutilize a MESMA chave ao repetir
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $response, PHP_EOL;
exit($status >= 200 && $status < 300 ? 0 : 1);

Resposta 200 (exemplo ilustrativo)

{
  "invoice": {
    "reference": "INV-A1B2C3",
    "total": "190.00",
    "txid": "7f3c9e...",
    "due_date": "2026-12-31",
    "copy": "00020126580014br.gov.bcb.pix...",
    "qrcode": "data:image/svg+xml;base64,..."
  }
}

O total é valor × quantidade + imposto% − desconto%. No exemplo: 200,00 + 5% (10,00) − 10% (20,00) = 190,00. Exiba o qrcode e/ou o copy (copia-e-cola) ao pagador.

5. Acompanhe o pagamento

Quando o cliente paga, você recebe invoice.paid no webhook. Como rede de segurança, consulte pela referência:

GET /api/invoice/ref/{ref_id}

#!/usr/bin/env bash
# Consultar cobrança pela referência
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
curl -sS --fail-with-body -X GET "$SHARKPAY_BASE_URL/api/invoice/ref/$SHARKPAY_REF" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN"
echo

// Consultar cobrança pela referência — Node.js 18+ (fetch nativo, sem dependências)
import { randomUUID } from 'node:crypto';

const BASE = process.env.SHARKPAY_BASE_URL;
const TOKEN = process.env.SHARKPAY_TOKEN;

const headers = { Authorization: `Bearer ${TOKEN}` };
const res = await fetch(`${BASE}/api/invoice/ref/${process.env.SHARKPAY_REF}`, {
  method: 'GET',
  headers,
  signal: AbortSignal.timeout(30_000), // sempre defina um timeout
});
const data = await res.json().catch(() => ({}));
console.log(res.status, JSON.stringify(data, null, 2));
if (!res.ok) process.exit(1);

# Consultar cobrança pela referência — Python 3.9+ (pip install requests)
import os, sys, uuid
import requests

BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]

headers = {"Authorization": f"Bearer {TOKEN}"}
res = requests.get(BASE + "/api/invoice/ref/" + os.environ["SHARKPAY_REF"] + "", headers=headers, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Consultar cobrança pela referência — PHP 8+ com ext-curl

$base  = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");

$ch = curl_init($base . '/api/invoice/ref/' . getenv('SHARKPAY_REF'));
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30, // sempre defina um timeout
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $token",
    ],
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, " ", $response, PHP_EOL;
exit($status >= 200 && $status < 300 ? 0 : 1);

Libere o pedido somente quando status for PAID.