Ir para o conteúdo
Sharkpay

Documentação da API

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

API 2026-10-14

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çãoComoObservaçã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.

CampoTipoDescriçã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.
Solicitar saque
#!/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
Consultar saque
#!/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

O campo loquidAmount (grafia original) e entoend são nomes legados mantidos por compatibilidade; use netAmount e endToEndId.