Ir para o conteúdo

Entrar Criar conta

Documentação da API

Integre pagamentos, saques e webhooks ao seu sistema com uma API HTTP/JSON aberta e documentada.

API 2026-10-14

Consultar status de transações

Acompanhe cada cobrança por webhook (recomendado) e, como rede de segurança, por consulta no seu servidor.

Status das cobranças

Status	Significa	Evento enviado
PENDING	Criada e aguardando pagamento.	—
PAID	Pagamento confirmado e creditado na sua carteira.	invoice.paid
CANCELED	Cancelada (por exemplo, expirada ou cancelada pelo painel).	invoice.canceled
REFUNDED	Devolvida ao pagador.	invoice.refunded

Saques Pix têm PENDING, PAID e CANCELED (eventos pixout.paid e pixout.canceled).

Consultar

Quando usar	Endpoint
Pela referência devolvida na criação (INV-XXXXXX)	GET /api/invoice/ref/{ref_id}
Pelo id numérico	GET /api/invoice/{invoice_id}
Listar/filtrar	GET /api/invoices
Registro bruto Pix por referência / txid	GET /api/pix/invoice/{ref} · GET /api/pix/txid/{txid}
Saque Pix	GET /api/pixout/withdraw/{txid} · GET /api/pixout/list
Checkout hospedado	GET /api/checkout/{tx_ref}

Consultar pela referência

#!/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);

Listagem e filtros

GET /api/invoices aceita page, limit (1–50, padrão 10), invoice_no e email (busca parcial) e o par start_date + end_date. Você só enxerga as cobranças da sua conta; um id de outra conta responde 404.

Listar cobranças

#!/usr/bin/env bash
# Listar cobranças
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/invoices?page=1&limit=10" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN"
echo

// Listar cobranças — 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/invoices?page=1&limit=10`, {
  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);

# Listar cobranças — 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/invoices", headers=headers, params={"page": 1, "limit": 10}, timeout=30)
try:
    data = res.json()
except ValueError:
    data = {}
print(res.status_code, data)
sys.exit(0 if res.ok else 1)

<?php
// Listar cobranças — PHP 8+ com ext-curl

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

$ch = curl_init($base . '/api/invoices?page=1&limit=10');
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);

Polling responsável

Prefira o webhook; use consulta apenas para conciliar (por exemplo, a cada 5–10 minutos para cobranças PENDING antigas).
Respeite o limite de 60 requisições/min e use backoff exponencial ao receber 429.
Nunca confirme pagamento pelo redirecionamento do navegador do cliente.