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.
| Item | Valor | Observação |
|---|---|---|
| URL base | https://blackpays.site/api/public/v1 | Todas as rotas abaixo são relativas a ela. |
| Formato | JSON (UTF-8) | Envie Content-Type: application/json. |
| Valores | centavos (inteiro) | R$ 10,00 = 1000. Nunca envie decimais. |
| Datas | ISO 8601 UTC | Ex.: 2026-11-17T12:00:00.000Z |
| Ambiente | Produção | Toda 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:
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.
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
| Campo | Tipo | Descrição |
|---|---|---|
| amountCents | inteiro | Obrigatório. Mínimo 200 (R$ 2,00). |
| description | texto | Até 180 caracteres. |
| customerName | texto | Nome do pagador. |
| customerEmail | texto | E-mail do pagador. |
| customerPhone | texto | Telefone. |
| customerDocument | texto | CPF (11) ou CNPJ (14), só números. |
| externalRef | texto | Seu ID do pedido (até 100). Volta nas consultas e webhooks. |
| tracking | objeto | UTMs: src, sck, utm_source, utm_medium, utm_campaign, utm_content, utm_term. |
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:
{
"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}
{ "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.
| Status | Significado | |
|---|---|---|
| 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
{ "availableCents": 125500, "processingCents": 10000, "totalReceivedCents": 980000, "currency": "BRL" }| Campo | Tipo | Descrição |
|---|---|---|
| availableCents | inteiro | Disponível para saque agora. Já desconta MEDs retidos. |
| processingCents | inteiro | Saques em andamento. |
| totalReceivedCents | inteiro | Total 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.
| Campo | Tipo | Descrição |
|---|---|---|
| Idempotency-Key | cabeçalho | Obrigatório. UUID v4 único por saque. |
| amountCents | inteiro | Obrigatório. Valor debitado do saldo, em centavos. |
| pixKey | texto | Obrigatório. Chave PIX do destinatário. |
| pixKeyType | texto | CPF, CNPJ, EMAIL ou TELEFONE. |
| externalRef | texto | Seu ID do saque (até 100). |
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):
{
"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
| Status | Significado | |
|---|---|---|
| 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ção | O 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}
{
"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
}| Campo | Tipo | Descrição |
|---|---|---|
| retainedCents | inteiro | Valor retido agora do seu saldo. |
| pendingCents | inteiro | Valor que ainda será retido de vendas futuras. |
| releasedCents | inteiro | Valor já devolvido ao saldo (MED ganho). |
| chargeId | texto | Cobrança contestada (TX_...). |
Webhooks
Webhooks
Cadastre uma URL https em Painel → API & Webhooks → Webhook. Para cada evento, enviamos um POST JSON assinado.
| Evento | Grupo | Quando |
|---|---|---|
| payment.paid | cash-in | PIX confirmado. Libere o pedido. |
| payment.failed | cash-in | Cobrança falhou. |
| payment.refunded | cash-in | Pagamento estornado. |
| withdrawal.paid | cash-out | Saque pago ao destinatário. |
| withdrawal.failed | cash-out | Saque recusado; valor devolvido ao saldo. |
| med.opened | MED | MED aberto e valor retido. |
| med.won | MED | MED ganho; retido devolvido ao saldo. |
| med.lost | MED | MED perdido; valor não volta. |
| test | — | Botão Enviar teste do painel. |
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 (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 (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
$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)
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).
| HTTP | error | Significado |
|---|---|---|
| 400 | invalid_body | Corpo inválido; veja details. |
| 400 | idempotency_key_required | Saque sem Idempotency-Key válida. |
| 400 | invalid_pix_key | Chave PIX não confere com o tipo. |
| 401 | unauthorized | Chave ausente, errada ou revogada. |
| 403 | account_blocked / withdrawal_blocked | Conta sem permissão para cobrar ou sacar. |
| 403 | risk_blocked | Bloqueado pela análise de risco. |
| 404 | not_found | Recurso não existe nesta conta. |
| 422 | insufficient_balance | Saldo insuficiente ou retido. |
| 422 | below_minimum / above_maximum | Fora dos limites de saque. |
| 422 | med_open | Saldo retido por MED. |
| 503 | unavailable | Tente 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.