API v1 · PIX

Seu gateway PIX completo, em uma API.

Receba pagamentos, envie saques para qualquer chave, acompanhe MEDs com retenção automática e receba webhooks assinados de cada evento.

Abrir no ChatGPT

Cash-in

Cobranças PIX com QR Code

Cash-out

Saques PIX idempotentes

MED

Retenção e devolução automáticas

Webhooks

Eventos assinados HMAC

Começar

API BlackPay

A API BlackPay permite operar um gateway PIX completo: receber pagamentos (cash-in), enviar saques PIX para qualquer chave (cash-out), consultar saldo, acompanhar MEDs (contestações PIX) e receber webhooks assinados de cada evento.

ItemValorObservação
URL basehttps://blackpays.site/api/public/v1Todas as rotas abaixo são relativas a ela.
FormatoJSON (UTF-8)Envie Content-Type: application/json.
Valorescentavos (inteiro)R$ 10,00 = 1000. Nunca envie decimais.
DatasISO 8601 UTCEx.: 2026-11-17T12:00:00.000Z
AmbienteProduçãoToda chamada movimenta dinheiro real.

Chame a API somente do seu servidor. Nunca exponha a chave no navegador, no app ou no front-end do seu cliente.

Começar

Fluxo completo

1. Crie a cobrança com POST /pix e mostre o copia e cola ou o QR Code ao pagador.

2. Receba o webhook payment.paid. O valor líquido entra no saldo disponível na hora.

3. Consulte GET /balance e envie saques com POST /withdrawals para qualquer chave PIX.

4. Receba withdrawal.paid ou withdrawal.failed. Se falhar, o valor volta ao saldo automaticamente.

5. Se o pagador abrir um MED, você recebe med.opened. O valor fica retido e é devolvido se o MED for ganho (med.won) ou mantido se for perdido (med.lost).

Começar

Autenticação

Crie a chave em Painel → API & Webhooks → Chaves. Ela aparece uma única vez e começa com bp_live_. Envie em todas as requisições:

http
Authorization: Bearer bp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Se a chave vazar, revogue no painel e crie outra. Chaves revogadas respondem 401 imediatamente. A chave tem acesso total à conta, inclusive a saques.

Começar

Idempotência

Todo saque exige o cabeçalho Idempotency-Key com um UUID v4 único por saque. Se a rede cair e você repetir a mesma chamada com a mesma chave, a BlackPay devolve o mesmo saque (HTTP 200), sem enviar o dinheiro duas vezes.

http
Idempotency-Key: 3f6c1a2e-9b7d-4c1e-8a5f-2d9e4b7c1a03

Para cobranças, use externalRef com o ID do seu pedido e consulte GET /pix?externalRef=... antes de criar outra.

Cash-in (PIX)

Criar cobrança PIX

POST/pix

CampoTipoDescrição
amountCentsinteiroObrigatório. Mínimo 200 (R$ 2,00).
descriptiontextoAté 180 caracteres.
customerNametextoNome do pagador.
customerEmailtextoE-mail do pagador.
customerPhonetextoTelefone.
customerDocumenttextoCPF (11) ou CNPJ (14), só números.
externalReftextoSeu ID do pedido (até 100). Volta nas consultas e webhooks.
trackingobjetoUTMs: src, sck, utm_source, utm_medium, utm_campaign, utm_content, utm_term.
bash
curl -X POST https://blackpays.site/api/public/v1/pix \
  -H "Authorization: Bearer $BLACKPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 4990,
    "description": "Pedido 1234",
    "customerName": "Maria Souza",
    "customerDocument": "12345678909",
    "externalRef": "pedido-1234"
  }'

Resposta 201:

json
{
  "id": "TX_1A2B3C4D5E6F",
  "externalRef": "pedido-1234",
  "status": "pending",
  "amountCents": 4990,
  "pixCopyPaste": "00020126...",
  "qrCodeBase64": "iVBORw0KGgo...",
  "expiresAt": "2026-11-17T13:00:00.000Z"
}

Mostre pixCopyPaste (copia e cola) e o QR Code como imagem: data:image/png;base64, + qrCodeBase64.

Cash-in (PIX)

Consultar e listar cobranças

GET/pix/{id}

json
{ "id": "TX_1A2B3C4D5E6F", "status": "paid", "amountCents": 4990, "netCents": 4590,
  "feeCents": 400, "description": "Pedido 1234", "paidAt": "2026-11-17T12:31:00.000Z",
  "createdAt": "2026-11-17T12:30:00.000Z", "expiresAt": "2026-11-17T13:00:00.000Z" }

GET/pix?limit=20&status=paid&externalRef=pedido-1234&before=2026-11-01T00:00:00Z

Mais recentes primeiro. limit vai até 100. Para paginar, envie em before o createdAt do último item recebido.

StatusSignificado
created—Registrada, gerando o PIX.
pending—Aguardando pagamento.
paid—Pago; líquido creditado no saldo.
expired—Venceu sem pagamento.
failed—Não foi possível gerar.
refunded—Estornado.

Saldo

Consultar saldo

GET/balance

json
{ "availableCents": 125500, "processingCents": 10000, "totalReceivedCents": 980000, "currency": "BRL" }
CampoTipoDescrição
availableCentsinteiroDisponível para saque agora. Já desconta MEDs retidos.
processingCentsinteiroSaques em andamento.
totalReceivedCentsinteiroTotal líquido já recebido em vendas.

Cash-out (saques)

Criar saque PIX

POST/withdrawals

Envia um PIX do saldo da conta para qualquer chave PIX. O valor sai do saldo na hora do pedido; se o envio falhar, volta automaticamente.

CampoTipoDescrição
Idempotency-KeycabeçalhoObrigatório. UUID v4 único por saque.
amountCentsinteiroObrigatório. Valor debitado do saldo, em centavos.
pixKeytextoObrigatório. Chave PIX do destinatário.
pixKeyTypetextoCPF, CNPJ, EMAIL ou TELEFONE.
externalReftextoSeu ID do saque (até 100).
bash
curl -X POST https://blackpays.site/api/public/v1/withdrawals \
  -H "Authorization: Bearer $BLACKPAY_KEY" \
  -H "Idempotency-Key: 3f6c1a2e-9b7d-4c1e-8a5f-2d9e4b7c1a03" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 10000,
    "pixKey": "maria@email.com",
    "pixKeyType": "EMAIL",
    "externalRef": "saque-cliente-981"
  }'

Resposta 201 (ou 200 se a mesma Idempotency-Key já foi usada):

json
{
  "id": "WD_8F2C1A9B3D4E",
  "externalRef": "saque-cliente-981",
  "status": "processing",
  "amountCents": 10000,
  "feeCents": 650,
  "netCents": 9350,
  "pixKey": "maria@email.com",
  "pixKeyType": "EMAIL",
  "source": "api",
  "failureReason": null,
  "createdAt": "2026-11-17T12:00:00.000Z",
  "paidAt": null
}

feeCents é a taxa total do saque e netCents é o que o destinatário recebe. Por padrão, saques a partir de R$ 400,00 passam por liberação da equipe e ficam em pending até lá. Contas com autorização específica de saque automático não exigem essa liberação nem o teto BlackPay por valor; saldo, MEDs, segurança e limites do adquirente continuam aplicáveis.

Cash-out (saques)

Consultar e listar saques

GET/withdrawals/{id}

GET/withdrawals?limit=20&externalRef=saque-cliente-981&before=2026-11-01T00:00:00Z

StatusSignificado
pending—Reservado, aguardando envio ou liberação.
processing—Enviado ao banco.
paid—Pago ao destinatário.
failed—Recusado; valor devolvido ao saldo. Veja failureReason.

Se uma chamada POST /withdrawals der timeout, não crie outro saque: repita com a mesma Idempotency-Key ou consulte a lista pelo externalRef.

MED

MED (contestação PIX)

MED é o Mecanismo Especial de Devolução do Banco Central. Quando o pagador contesta um PIX, a BlackPay identifica a venda automaticamente e retém o valor do saldo da conta, sem ação manual.

SituaçãoO que acontece
Saldo suficiente—O valor do MED é retido na hora.
Saldo insuficiente—Retemos o que houver e o restante sai das próximas vendas (pendingCents).
MED ganho (won)—Devolvemos ao saldo exatamente o que foi retido.
MED perdido (lost)—O valor retido é devolvido ao pagador e não volta ao saldo.

GET/meds?status=open&limit=20

GET/meds/{id}

json
{
  "id": "6b1e0c1e-3f5a-4c2b-9b1d-2a7f0f3e9c11",
  "status": "open",
  "amountCents": 3000,
  "retainedCents": 3000,
  "pendingCents": 0,
  "releasedCents": 0,
  "reason": "Fraude",
  "chargeId": "TX_1A2B3C4D5E6F",
  "chargeExternalRef": "pedido-1234",
  "openedAt": "2026-11-17T08:08:00.000Z",
  "deadline": "2026-11-24T08:08:00.000Z",
  "closedAt": null
}
CampoTipoDescrição
retainedCentsinteiroValor retido agora do seu saldo.
pendingCentsinteiroValor que ainda será retido de vendas futuras.
releasedCentsinteiroValor já devolvido ao saldo (MED ganho).
chargeIdtextoCobrança contestada (TX_...).

Webhooks

Webhooks

Cadastre uma URL https em Painel → API & Webhooks → Webhook. Para cada evento, enviamos um POST JSON assinado.

EventoGrupoQuando
payment.paidcash-inPIX confirmado. Libere o pedido.
payment.failedcash-inCobrança falhou.
payment.refundedcash-inPagamento estornado.
withdrawal.paidcash-outSaque pago ao destinatário.
withdrawal.failedcash-outSaque recusado; valor devolvido ao saldo.
med.openedMEDMED aberto e valor retido.
med.wonMEDMED ganho; retido devolvido ao saldo.
med.lostMEDMED perdido; valor não volta.
test—Botão Enviar teste do painel.
http
POST https://seusite.com/webhooks/blackpay
Content-Type: application/json
X-BlackPay-Event: withdrawal.paid
X-BlackPay-Signature: 5f2b9c...  (HMAC-SHA256 hex do corpo bruto)

{
  "id": "withdrawal.paid:WD_8F2C1A9B3D4E",
  "event": "withdrawal.paid",
  "createdAt": "2026-11-17T12:01:10.000Z",
  "data": { ...mesmo formato de GET /withdrawals/{id} }
}

Em payment.*, data tem o formato de GET /pix/{id}, mais externalRef, customerName, customerEmail e tracking. Em med.*, data tem o formato de GET /meds/{id}.

Responda 2xx em até 8 segundos. Use o campo id para ignorar entregas repetidas e, antes de liberar valores, confirme o status consultando a API. Todos os envios aparecem em Últimos envios no painel.

Webhooks

Validar assinatura

Calcule o HMAC-SHA256 do corpo bruto, antes de converter o JSON, com o seu segredo whsec_... e compare em tempo constante com o cabeçalho X-BlackPay-Signature.

Node.js
// Node.js (Express)
import crypto from "node:crypto";
app.post("/webhooks/blackpay", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", process.env.BLACKPAY_WEBHOOK_SECRET).update(req.body).digest("hex");
  const got = req.get("X-BlackPay-Signature") || "";
  if (got.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) return res.sendStatus(401);
  const evt = JSON.parse(req.body.toString());
  // evt.event: payment.paid | withdrawal.paid | withdrawal.failed | med.opened | med.won | med.lost
  res.sendStatus(200);
});
Python
# Python (Flask)
import hmac, hashlib, os
@app.post("/webhooks/blackpay")
def blackpay():
    body = request.get_data()
    expected = hmac.new(os.environ["BLACKPAY_WEBHOOK_SECRET"].encode(), body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-BlackPay-Signature", "")):
        return "", 401
    evt = request.get_json()
    return "", 200
PHP
<?php // PHP
$body = file_get_contents("php://input");
$sig = hash_hmac("sha256", $body, getenv("BLACKPAY_WEBHOOK_SECRET"));
if (!hash_equals($sig, $_SERVER["HTTP_X_BLACKPAY_SIGNATURE"] ?? "")) { http_response_code(401); exit; }
$evt = json_decode($body, true);
http_response_code(200);

Referência

Exemplo completo (Node.js)

javascript
const API = "https://blackpays.site/api/public/v1";
const H = { Authorization: `Bearer ${process.env.BLACKPAY_KEY}`, "Content-Type": "application/json" };

// Cash-in
const charge = await fetch(`${API}/pix`, { method: "POST", headers: H,
  body: JSON.stringify({ amountCents: 4990, externalRef: "pedido-1234" }) }).then(r => r.json());

// Saldo
const { availableCents } = await fetch(`${API}/balance`, { headers: H }).then(r => r.json());

// Cash-out (idempotente)
const payout = await fetch(`${API}/withdrawals`, { method: "POST",
  headers: { ...H, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ amountCents: 10000, pixKey: "maria@email.com", pixKeyType: "EMAIL" }) }).then(r => r.json());

// MEDs abertos
const meds = await fetch(`${API}/meds?status=open`, { headers: H }).then(r => r.json());

Referência

Erros

Erros respondem JSON com error (código fixo) e, quando houver, message (texto em português).

HTTPerrorSignificado
400invalid_bodyCorpo inválido; veja details.
400idempotency_key_requiredSaque sem Idempotency-Key válida.
400invalid_pix_keyChave PIX não confere com o tipo.
401unauthorizedChave ausente, errada ou revogada.
403account_blocked / withdrawal_blockedConta sem permissão para cobrar ou sacar.
403risk_blockedBloqueado pela análise de risco.
404not_foundRecurso não existe nesta conta.
422insufficient_balanceSaldo insuficiente ou retido.
422below_minimum / above_maximumFora dos limites de saque.
422med_openSaldo retido por MED.
503unavailableTente novamente em instantes.

Referência

Boas práticas e segurança

• Guarde a chave da API e o segredo do webhook em variáveis de ambiente do servidor.

• Sempre valide a assinatura do webhook e confirme o status pela API antes de liberar produto ou saldo para o seu cliente final.

• Use uma Idempotency-Key nova por saque e reutilize a mesma chave ao repetir após um timeout.

• Mantenha o saldo de MEDs no seu próprio sistema: o valor retido não pode ser sacado até a decisão.

• Trabalhe sempre em centavos inteiros, sem converter para número decimal.

Integre com ajuda de IA

Envie esta documentação ao ChatGPT e peça o código pronto para a sua linguagem.

Abrir no ChatGPT