Documentação da API

Nossos endpoints permitem criar cobranças, consultar pagamentos e verificar saldos. Todas as requisições devem ser autenticadas com um token no header X-API-Token.

URL Base: https://pixbitcoin.org/

Como obter seu Token de API

Para realizar requisições autenticadas, você precisa de um token único. Siga os passos:

Pré-requisito: sua conta precisa de ao menos 1 compra confirmada no site, paga com o seu próprio CPF/CNPJ. Sem isso o botão "Novo Token" responde 403 kyc_purchase_required. É o KYC mínimo de merchant — impede que uma conta recém-criada saia cobrando terceiros pela API.

Faça (ou já tenha) 1 compra confirmada na conta, pagando com o seu CPF/CNPJ.
Acesse a tela Carteira.
Clique no botão "Novo Token". Gerar um token novo revoga o anterior, e o valor só aparece uma vez — copie na hora.
O token nasce ativo: o seu merchantId DePix é o EUID da sua conta, atribuído automaticamente na emissão. Já dá para cobrar.
Insira o token no header da sua requisição:
X-API-Token: <seu_token_aqui>

Token emitido antes de jun/2026? Ele não tem merchantId e falha ao cobrar com 403 merchant_id_missing. Gere um token novo pela Carteira (respeitando o pré-requisito acima) — o novo já nasce com merchantId e ativo.

Ir para Carteira

Criar Pagamento

POST /api/create-payment

Cria uma nova cobrança Pix para depósito. O QR Code gerado tem validade de 10 minutos. O valor recebido pode ser convertido automaticamente para as criptomoedas DEPIX, BTC e USDt conforme as taxas abaixo.

Estrutura de Taxas de Conversão

Bitcoin (L-BTC): Taxa 6% sobre a cotação do momento.
Dólar Theter (USDt): Taxa de 2% sobre a cotação do momento.
DePix: Taxa de 2% no momento do saque.

Uma taxa fixa de R$ 1,00 adicionada a cada depósito.

Parâmetros do Body:

value Valor em BRL (Ex: "150.75"). Min R$10(USDt e Depix) e R$20(Bitcoin), Max R$5.000. De acordo com Limites
email E-mail da conta do cliente que receberá o saldo.
swap_to opcional Define a moeda de conversão automática. Opções: BTC, USDt, DEPIX.
euid opcional Identificador do end user (EUID) do pagador. A Depix exige um end user identificado para gerar QR Codes acima de R$10,00. Na 1ª cobrança de um cliente você ainda não tem o EUID — gere-a sem euid e com valor de até R$10,00. Depois do pagamento, o EUID volta no campo payerEuid do get-payment (e do webhook); guarde-o e envie-o no euid das próximas cobranças daquele cliente para liberar valores acima de R$10,00. Veja Como obter o EUID.
tax_number obrigatório* CPF (11 díg.) ou CNPJ (14 díg.) do pagador. *Obrigatório enviar euid OU tax_number em toda cobrança (exigência DePix). Não é KYC e não pede documentos — serve só para identificar qual conta está pagando, prevenindo golpes e estornos indevidos (MED). Atenção: mandar o tax_number não libera valores acima de R$10 — a DePix só aceita QR acima disso com euid. A 1ª cobrança de cada cliente é sempre de até R$10,00; pegue o payerEuid no get-payment e mande no euid das próximas para liberar o 1º tier (R$499) e a escada acima dele.

Merchants (token de API): cada cobrança é atribuída ao seu merchantId DePix — o risco de MED do seu end user é seu, não cai na conta-mãe. O merchantId é o EUID da sua conta e já vem preenchido na emissão do token. End users com MED prévio (email/CPF/EUID) são bloqueados mesmo via API.

webhook_url opcional URL que receberá notificações quando o pagamento for confirmado.
webhook_secret opcional Chave secreta para validar a assinatura do webhook (HMAC SHA256).

EXEMPLO DE REQUISIÇÃO (cURL)

curl -X POST https://pixbitcoin.org/api/create-payment \
  -H "X-API-Token: <seu_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "250.00",
    "email": "cliente@example.com",
    "swap_to": "BTC",
    "euid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "webhook_url": "https://sua-api.com/webhook",
    "webhook_secret": "seu_secret_seguro"
  }'

EXEMPLO DE RESPOSTA (JSON)

{
  "id": "4fbbd7a-c1b1-4f3b-8a3b-18a0b0e5d8d6",
  "qrCopyPaste": "0002012666...",
  "qrImageUrl": "https://api.pixbitcoin.org/qrcodes/4fbb.../image.png",
  "expiresAt": "2025-07-19T16:33:12Z",
  "status": "waiting_payment"
} // headers com X-Webhook-Signature gerado apartir do secret + campos[payment_id, email, value_in_cents, payer_euid]

Consultar Pagamento

GET /api/get-payment/{payment_id}

Verifica o status de um pagamento específico usando o id retornado na criação.

Status Possíveis:

waiting_payment: Aguardando o pagamento do Pix.
pending: Pagamento recebido e aguardando confirmações.
under_review: Pagamento recebido, em análise pelo provedor (compliance da DePix).
security_hold: Retido pela nossa verificação antifraude (ex.: identidade já usada em outra conta, ou pagador diferente do informado). O valor está seguro; a liberação depende da revisão.
depix_sent: Pagamento confirmado e valor creditado na sua conta.
canceled: O pagamento foi cancelado pelo sistema ou usuário.
expired: O tempo para pagamento do QR Code expirou.
will_refund: A transação será devolvida ao pagador (risco/compliance) — aviso prévio de reembolso.
refunded: O valor do pagamento foi devolvido ao pagador.
after7d: Pagamento de terceiro — saldo convertido mas retido por 7 dias corridos. Saque liberado automaticamente após o prazo.
error: Ocorreu um erro inesperado no processamento.

Regra `AFTER7D` — Pagamento por Terceiro

Se quem pagou o Pix (payerEuid / payerTaxNumber) for diferente do pagador que você informou no create-payment (campo euid ou cpf), o pagamento é tratado como de terceiro e retido por 7 dias:

O saldo é convertido normalmente (BTC, USDt ou DePix conforme swap_to).
O status retornado pelo /api/get-payment será after7d.
O saque fica bloqueado durante os 7 dias corridos.
Após o prazo, o status muda para depix_sent e o saque é liberado automaticamente.
Webhooks são disparados na confirmação do pagamento e novamente na liberação do saldo.

Regra `security_hold` — Verificação antifraude

Proteção contra reembolso indevido (MED). O pagamento fica retido — sem conversão e sem saque — até revisão manual quando cai em uma das regras:

O pagador (e-mail, CPF/CNPJ ou EUID) tem MED anterior — bloqueado.
A mesma identidade (EUID/CPF) já pertence a outra conta — cada identidade vale para uma única conta.
O pagador real difere do informado de forma inesperada (fora do fluxo de terceiro).

Não confunda com under_review, que é a análise do provedor (DePix). security_hold é a nossa verificação.

Como obter o EUID do seu cliente

A Depix só gera o EUID (identificador do pagador) quando o cliente paga o Pix — não há como obtê-lo antes do primeiro pagamento. Por isso a primeira cobrança de cada cliente é limitada a R$10,00.

1ª cobrança de um cliente novo: chame create-payment sem euid e com valor de até R$10,00.
Quando o status virar depix_sent, a resposta do get-payment traz o campo payerEuid — o mesmo valor também é enviado no webhook (payer_euid).
Guarde o payerEuid associado ao seu cliente.
Nas próximas cobranças daquele cliente, envie esse valor no campo euid do create-payment — assim você gera QR Codes acima de R$10,00.

Quando a 1ª cobrança é criada com tax_number, o payerEuid pode aparecer no get-payment antes mesmo do pagamento (a Depix resolve o pagador pelo CPF/CNPJ). Se ele já estiver lá, pode usar.

EXEMPLO DE REQUISIÇÃO (cURL)

curl https://pixbitcoin.org/api/get-payment/4fbb... \
  -H "X-API-Token: <seu_token>"

EXEMPLO DE RESPOSTA (JSON)

{
  "qrId": "4fbbd7a-c1b1-4f3b-8a3b-18a0b0e5d8d6",
  "status": "depix_sent",
  "payerName": "Fulano de Tal",
  "payerTaxNumber": "***.456.789-**",
  "payerEuid": "EU013089459847844",  // reutilize no campo "euid" das próximas cobranças deste cliente
  "amount": 25000,
  "updatedAt": "2025-07-19T16:35:02Z"
}

Obter Saldo

GET /api/get-balance

Retorna os saldos disponíveis em todas as moedas para a conta associada ao token.

EXEMPLO DE REQUISIÇÃO (cURL)

curl https://pixbitcoin.org/api/get-balance \
  -H "X-API-Token: <seu_token>"

EXEMPLO DE RESPOSTA (JSON)

{
  "email": "cliente@example.com",
  "balances": {
    "DEPIX": {
      "available_cents": 12345,
      "available_brl": "R$ 123,45"
    },
    "BTC": {
      "available_sats": 987654,
      "available_btc": "0.00987654"
    },
    "USDt": {
      "available_cents_USDt": 2500000,
      "available_USDt": "2.500000"
    }
  }
}

Webhooks

Quando você cria um pagamento com os campos webhook_url e webhook_secret, o sistema enviará automaticamente uma notificação para a URL especificada quando o pagamento for confirmado.

Validação de Assinatura:

Se você fornecer um webhook_secret, o sistema incluirá um header X-Webhook-Signature com a assinatura HMAC SHA256 do payload. Você pode usar isso para validar que a requisição veio realmente do nosso sistema.

Dados Enviados:

payment_id: ID do pagamento
email: E-mail do cliente
value_in_cents: Valor em centavos

EXEMPLO DE WEBHOOK RECEBIDO (JSON)

{
  "payment_id": "4fbbd7a-c1b1-4f3b-8a3b-18a0b0e5d8d6",
  "email": "cliente@example.com",
  "value_in_cents": 25000
}

EXEMPLO DE VALIDAÇÃO DA ASSINATURA (Python)

import hmac
import hashlib
import json

def validate_webhook(payload, signature, secret):
    message = json.dumps(payload, separators=(',', ':'))
    expected = hmac.new(
        secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Códigos de Status HTTP

200 OK - Requisição bem-sucedida.
400 Bad Request - Erro de validação nos dados enviados.
401 Unauthorized - Token de API ausente ou inválido.
403 Forbidden - Acesso negado para o recurso.
404 Not Found - Recurso não encontrado.

Códigos de Erro

Toda resposta de erro traz error (texto para humano) e code (estável, para a sua integração ramificar). Ramifique no code, nunca no texto — o texto pode mudar.

code	HTTP	O que fazer
token_missing	401	Faltou o header `X-API-Token`.
token_not_found	401	Token não existe (ou foi substituído por um mais novo). Gere outro na Carteira.
token_pending	403	Token criado mas ainda não aprovado. Peça a ativação ao suporte.
token_inactive	403	Token inativo, revogado ou expirado — inclusive quando você gerou um token novo (o antigo é revogado). Use o token atual.
merchant_id_missing	403	Token sem `merchantId` DePix — típico de token emitido antes de jun/2026. Gere um token novo e peça a ativação.
kyc_purchase_required	403	Conta sem compra confirmada. Faça 1 compra no site pagando com o seu CPF/CNPJ e tente de novo.
kyc_identity_unidentified	403	Tem compra, mas o provedor não devolveu o EUID do pagador. Só o suporte libera — mande o e-mail da conta.

EXEMPLO DE RESPOSTA DE ERRO

{
  "error": "Este token não tem merchantId DePix e por isso não pode criar cobranças. …",
  "code": "merchant_id_missing",
  "docs_url": "https://pixbitcoin.org/api-docs",
  "support_email": "pixbitcoin.org@gmail.com"
}

Documentação da API

Como obter seu Token de API

Criar Pagamento

Estrutura de Taxas de Conversão

Parâmetros do Body:

EXEMPLO DE REQUISIÇÃO (cURL)

EXEMPLO DE RESPOSTA (JSON)

Consultar Pagamento

Status Possíveis:

Regra AFTER7D — Pagamento por Terceiro

Regra security_hold — Verificação antifraude

Como obter o EUID do seu cliente

EXEMPLO DE REQUISIÇÃO (cURL)

EXEMPLO DE RESPOSTA (JSON)

Obter Saldo

EXEMPLO DE REQUISIÇÃO (cURL)

EXEMPLO DE RESPOSTA (JSON)

Webhooks

Validação de Assinatura:

Dados Enviados:

EXEMPLO DE WEBHOOK RECEBIDO (JSON)

EXEMPLO DE VALIDAÇÃO DA ASSINATURA (Python)

Códigos de Status HTTP

Códigos de Erro

EXEMPLO DE RESPOSTA DE ERRO

Regra `AFTER7D` — Pagamento por Terceiro

Regra `security_hold` — Verificação antifraude