Reembolsos, cancelamentos e saques
Esta página diz com franqueza o que a API faz — e o que não faz — para devoluções e retiradas de saldo.
O que é suportado
| Operação | Como | Observação |
|---|---|---|
| Saber que uma cobrança foi devolvida | Webhook invoice.refunded ou GET /api/invoice/ref/{ref} | Status REFUNDED. |
| Saber que uma cobrança foi cancelada | Webhook invoice.canceled ou consulta | Status CANCELED. |
| Retirar saldo via Pix | POST /api/pixout/create | Exige Idempotency-Key; veja abaixo. |
| Acompanhar saques | GET /api/pixout/withdraw/{txid}, GET /api/pixout/list | Eventos pixout.paid / pixout.canceled. |
Saque Pix
O saque reserva o saldo (valor + tarifa) de forma atômica antes de falar com o banco. Se o banco recusar, o valor é devolvido ao saldo e o saque fica CANCELED. Duas chamadas simultâneas nunca gastam o mesmo saldo duas vezes.
| Campo | Tipo | Descrição |
|---|---|---|
| amountobrigatório | número > 0 | Valor do saque. |
| pixkeyobrigatório | string ≤ 140 | Chave Pix de destino. |
| keytypeobrigatório | CPF | CNPJ | EMAIL | PHONE | EVP | Tipo da chave. |
| client · document · emailopcional | string | Dados do destinatário. |
| descriptionopcional | string ≤ 140 | Descrição. |
#!/usr/bin/env bash
# Solicitar saque 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"}"
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/pixout/create" \
-H "Authorization: Bearer $SHARKPAY_TOKEN" \
-H "Idempotency-Key: ${IDEMPOTENCY_KEY:-$(uuidgen)}" \
-H "Content-Type: application/json" \
-d '{
"amount": 50,
"pixkey": "maria@example.com",
"keytype": "EMAIL",
"client": "Maria Souza",
"document": "12345678909",
"description": "Repasse"
}'
echo// Solicitar saque 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 body = {
amount: 50,
pixkey: "maria@example.com",
keytype: "EMAIL",
client: "Maria Souza",
document: "12345678909",
description: "Repasse",
};
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/pixout/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);# Solicitar saque Pix — Python 3.9+ (pip install requests)
import os, sys, uuid
import requests
BASE = os.environ["SHARKPAY_BASE_URL"]
TOKEN = os.environ["SHARKPAY_TOKEN"]
body = {
"amount": 50,
"pixkey": "maria@example.com",
"keytype": "EMAIL",
"client": "Maria Souza",
"document": "12345678909",
"description": "Repasse",
}
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/pixout/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
// Solicitar saque Pix — PHP 8+ com ext-curl
$base = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");
$body = [
'amount' => 50,
'pixkey' => 'maria@example.com',
'keytype' => 'EMAIL',
'client' => 'Maria Souza',
'document' => '12345678909',
'description' => 'Repasse',
];
$ch = curl_init($base . '/api/pixout/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);#!/usr/bin/env bash
# Consultar saque
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/pixout/withdraw/$SHARKPAY_WITHDRAW_REF" \
-H "Authorization: Bearer $SHARKPAY_TOKEN"
echo// Consultar saque — 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/pixout/withdraw/${process.env.SHARKPAY_WITHDRAW_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 saque — 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/pixout/withdraw/" + os.environ["SHARKPAY_WITHDRAW_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 saque — PHP 8+ com ext-curl
$base = getenv("SHARKPAY_BASE_URL");
$token = getenv("SHARKPAY_TOKEN");
$ch = curl_init($base . '/api/pixout/withdraw/' . getenv('SHARKPAY_WITHDRAW_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);O campo loquidAmount (grafia original) e entoend são nomes legados mantidos por compatibilidade; use netAmount e endToEndId.