API do DePix App

Introdução

A API do DePix App permite criar e gerenciar checkouts Pix programaticamente. É a mesma API que alimenta o plugin do BTCPay Server, a área Meu Negócio e agora agentes de IA — pelo MCP e pelo SDK.

URL base

https://api.depixapp.com

Formato

Todos os requests e responses usam JSON (Content-Type: application/json). Valores monetários são sempre em centavos (inteiros). Exemplo: R$ 10,00 = 1000.

Todas as datas e horas que a API retorna — respostas e webhooks — vêm num único formato, RFC 3339 em UTC: "2026-07-01T12:00:00.000Z". As duas exceções são campos que carregam só a data, sem hora: due_date e cycle_due_date das cobranças ("2026-08-05"). O conteúdo de metadata nunca é alterado — volta exatamente como você enviou.

Autenticação

Use uma API key no header Authorization em todos os requests autenticados.

Authorization: Bearer sk_live_<sua-chave>

Nos exemplos curl desta documentação, a chave vem da variável de ambiente DEPIX_API_KEY. Defina-a uma vez no seu shell — export DEPIX_API_KEY=sk_live_... (ou sua chave sk_test_ no sandbox) — em vez de colar a chave inline em cada comando.

Tipos de chave

Para gerenciar suas chaves (criar, listar, revogar), acesse Meu Negócio em depixapp.com/#merchant. Máximo de 5 chaves live e 5 chaves test ativas por conta.

Cada chave nasce com scopes explícitos (merchant_read, merchant_write, wallet_read, wallet_write) e, no caso de chaves com scope wallet_write, com limites de gasto obrigatórios. A chave é imutável após a criação — veja Scopes e limites por chave.

Acesso à API de produção

Chaves sk_test_ são liberadas automaticamente após criar sua conta de negócio — comece integrando contra o sandbox sem esperar nada. Chaves sk_live_ exigem aprovação manual: na área de API Keys, clique em Solicitar acesso, responda 5 perguntas curtas sobre sua integração, e nossa equipe avalia. Aprovações costumam sair em algumas horas em dias úteis.

Scopes e limites por chave

Cada API key carrega um conjunto explícito de scopes que define o que ela pode fazer. Os scopes são escolhidos na criação da chave e não podem ser alterados depois — a chave é imutável; para mudar scopes ou limites, revogue e crie outra.

Os scopes se dividem em dois eixos: merchant_* é o lado lojista (o gateway — checkouts e produtos) e wallet_* é o lado carteira (o on/off-ramp Pix — depósitos e saques).

• Sem hierarquia implícita — merchant_write não inclui merchant_read, e os scopes wallet_* não incluem nenhum deles. Uma chave pode combinar os quatro: ["merchant_read", "merchant_write", "wallet_read", "wallet_write"].
• Chamada sem o scope exigido → 403 com error.code = "insufficient_scope" e details.required_scope (ver Erros). A resposta nunca ecoa a lista de scopes da chave.

Chaves wallet_write nascem com limites obrigatórios

Toda chave com scope wallet_write tem limites de gasto próprios, aplicados além dos limites da conta (os limites de conta sempre prevalecem). Se você não informar valores na criação, os defaults se aplicam: R$ 100,00 por transação (per_tx_limit_cents = 10000) e R$ 500,00 por dia (daily_limit_cents = 50000, janela rolante de 24h somando depósitos e saques atribuídos à chave). Você pode elevar os valores conscientemente na criação — mas uma chave wallet_write sem limites não existe.

Operação que excede um limite da chave → 400 com error.code = "key_limit_exceeded" e details: { limit: "per_tx" | "daily", limit_cents, used_cents }.

Criação de chave com scopes e limites

A gestão de credenciais é exclusiva do dono logado: POST /api/api-keys aceita apenas o JWT do dashboard (nunca outra API key). Além dos campos existentes (type, label, expires_in_days), a criação aceita:

{
  "id":                  "a1b2c3d4e5f6...",
  "key":                 "sk_test_...",       // exibida só uma vez
  "prefix":              "sk_test_",
  "label":               "agent-payments",
  "is_live":             false,
  "expires_at":          null,
  "scopes":              ["merchant_read", "merchant_write", "wallet_read", "wallet_write"],
  "per_tx_limit_cents":  10000,
  "daily_limit_cents":   50000,
  "rate_limit_per_min":  30
}

Idempotência

Os POSTs com efeito monetário aceitam o header opcional Idempotency-Key (1–255 caracteres ASCII visíveis). Fortemente recomendado para agentes e para qualquer integração com retry automático: um retry com a mesma chave devolve a resposta original em vez de criar um segundo QR ou uma segunda cobrança.

Endpoints cobertos

• POST /api/deposit
• POST /api/withdraw
• POST /api/checkouts

Semântica exata

• Escopo de unicidade: (identidade, endpoint, chave) — chaves de merchants diferentes nunca colidem.
• Comparação do body: hash do JSON parseado. Whitespace/formatação não afetam; a ordem dos campos afeta — body semanticamente igual com campos reordenados → 422. Retry byte-idêntico sempre casa.
• Respostas 5xx e 429 nunca são armazenadas — o retry re-executa. 4xx determinísticos (validação, limites) são armazenados e replayados.
• TTL de 24 horas — depois disso a mesma chave vale como nova.
• Operações sandbox (sk_test_) participam normalmente — o agente treina o fluxo completo.

Exemplo

curl -X POST https://api.depixapp.com/api/deposit \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-run-42-deposit-1" \
  -d '{ "amountInCents": 1500, "depixAddress": "lq1qq...", "payer_tax_number": "52998224725" }'

Primeira chamada: 200 com o QR. Retry idêntico: 200 com o mesmo body + Idempotency-Replayed: true. Retry com amountInCents alterado:

{
  "response": { "errorMessage": "Idempotency-Key já utilizada com um corpo diferente." },
  "error": {
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used with a different request body.",
    "request_id": "gru1::abcd-1234",
    "docs_url": "https://depixapp.com/docs/en/#errors"
  }
}

Erros

Erros carregam um envelope duplo: response.errorMessage (mensagem legada em português, sempre presente e sempre legível para humanos) e o objeto error (contrato estruturado para máquinas, mensagens em inglês). Programe contra error.code — nunca contra o texto das mensagens.

{
  "response": { "errorMessage": "Muitas requisições. Tente novamente em 1 minuto." },
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this scope.",
    "request_id": "gru1::iad1::v9x4k-1751476800000-abc123",
    "retry_after": 37,
    "docs_url": "https://depixapp.com/docs/en/#errors",
    "details": { "scope": "deposit" }
  }
}

• request_id — id de correlação, devolvido em toda resposta (sucesso incluso) no header X-Request-Id. Cite-o em pedidos de suporte.
• retry_after — segundos até poder repetir; presente em todo 429, 503 e no 409 idempotency_in_flight. Espelhado no header HTTP Retry-After.
• details — extras opcionais e normativos por code: campo ofensor, scope exigido, limites em centavos (ver a tabela abaixo).
• Irmãos legados preservados: erros de validação do criar checkout mantêm response.errors[] (lista por campo) e o 403 de conta bloqueada mantém blocked: true.
• Handlers legados fora da superfície de agente ainda podem responder só com response.errorMessage, sem o objeto error.

next_action — o próximo passo, legível por máquina

Todo erro tipado voltado a agentes carrega uma ação seguinte, em error.details.next_action. Ela existe para que um agente que nunca leu esta página saiba o que fazer em vez de adivinhar pelo texto da mensagem. Nas ferramentas do MCP o mesmo objeto chega em data.next_action. É por isso que o docs_url de todo erro aponta para cá.

{
  "error": {
    "code": "merchant_required",
    "message": "A merchant profile is required for this operation.",
    "request_id": "gru1::iad1::v9x4k-1751476800000-abc123",
    "docs_url": "https://depixapp.com/docs/en/#errors",
    "details": {
      "next_action": {
        "kind": "call_tool",
        "tool": "get_onboarding_status"
      }
    }
  }
}

kind é um conjunto fechado de cinco. Programe contra ele:

• Uma ação por erro, sempre. Oferecer duas devolveria ao agente a escolha que este contrato existe para acabar.
• relay — o texto pronto que o agente cola para o humano, em pt e en: no máximo 4 passos, sem jargão. Está presente exatamente quando kind é human_step, e nunca nos outros. Ele mora no MCP, não neste servidor: a fronteira anti-injeção do MCP deriva a mensagem só do code e descarta texto livre vindo daqui, então copy enviada por este servidor seria jogada fora.
• wait traz retry_after_seconds como espelho do error.retry_after (e do header Retry-After), nunca uma terceira fonte: dois números diferentes para o mesmo prazo fariam o agente ou martelar porta fechada ou dormir além da reabertura.
• Levam next_action os codes voltados ao dono da conta: credenciais, escada de verificação, domínio, bloqueios e limites de retentativa. As rotas do pagador não levam — quem paga é um estranho, e mandá-lo ao painel do lojista é o erro de categoria que o filtro existe para evitar.

Catálogo de codes

Os codes transversais — os que qualquer rota pode devolver, incluindo todos os que carregam next_action. Cada linha tem âncora estável no formato #error-<code> (ex.: #error-rate_limited). Erros específicos de um fluxo (tickets, cobranças, trilho DePix, assinatura de agente) estão na seção daquele fluxo.

Criar checkout

Cria um novo checkout Pix. Retorna o QR code e a URL de pagamento para exibir ao seu cliente.

Parâmetros

Exemplo

curl -X POST https://api.depixapp.com/api/checkouts \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2990,
    "payer_tax_number": "529.982.247-25",
    "description": "Camiseta tamanho M",
    "expires_in": 900,
    "callback_url": "https://minha-loja.com/webhook/depix",
    "metadata": { "order_id": "ORD-123" }
  }'

const res = await fetch("https://api.depixapp.com/api/checkouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_<sua-chave>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 2990,
    payer_tax_number: "529.982.247-25",
    description: "Camiseta tamanho M",
    expires_in: 900,
    callback_url: "https://minha-loja.com/webhook/depix",
    metadata: { order_id: "ORD-123" },
  }),
});
const data = await res.json();
console.log(data.id, data.payment_url);

import requests

resp = requests.post(
    "https://api.depixapp.com/api/checkouts",
    headers={"Authorization": "Bearer sk_live_<sua-chave>"},
    json={
        "amount": 2990,
        "payer_tax_number": "529.982.247-25",
        "description": "Camiseta tamanho M",
        "expires_in": 900,
        "callback_url": "https://minha-loja.com/webhook/depix",
        "metadata": {"order_id": "ORD-123"},
    },
)
data = resp.json()
print(data["id"], data["payment_url"])

$ch = curl_init("https://api.depixapp.com/api/checkouts");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_<sua-chave>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 2990,
        "payer_tax_number" => "529.982.247-25",
        "description" => "Camiseta tamanho M",
        "expires_in" => 900,
        "callback_url" => "https://minha-loja.com/webhook/depix",
        "metadata" => ["order_id" => "ORD-123"],
    ]),
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data["id"] . " " . $data["payment_url"];

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_<sua-chave>");

var payload = new {
    amount = 2990,
    payer_tax_number = "529.982.247-25",
    description = "Camiseta tamanho M",
    expires_in = 900,
    callback_url = "https://minha-loja.com/webhook/depix",
    metadata = new { order_id = "ORD-123" }
};

var res = await client.PostAsync(
    "https://api.depixapp.com/api/checkouts",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
var json = await res.Content.ReadAsStringAsync();
Console.WriteLine(json);

body := `{"amount":2990,"payer_tax_number":"529.982.247-25","description":"Camiseta tamanho M","expires_in":900,"callback_url":"https://minha-loja.com/webhook/depix","metadata":{"order_id":"ORD-123"}}`

req, _ := http.NewRequest("POST", "https://api.depixapp.com/api/checkouts", strings.NewReader(body))
req.Header.Set("Authorization", "Bearer sk_live_<sua-chave>")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

require "net/http"
require "json"

uri = URI("https://api.depixapp.com/api/checkouts")
req = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer sk_live_<sua-chave>",
  "Content-Type" => "application/json",
})
req.body = { amount: 2990, payer_tax_number: "529.982.247-25", description: "Camiseta tamanho M", expires_in: 900,
             callback_url: "https://minha-loja.com/webhook/depix",
             metadata: { order_id: "ORD-123" } }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)

HttpClient client = HttpClient.newHttpClient();
String json = """
    {"amount":2990,"payer_tax_number":"529.982.247-25","description":"Camiseta tamanho M","expires_in":900,
     "callback_url":"https://minha-loja.com/webhook/depix",
     "metadata":{"order_id":"ORD-123"}}""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.depixapp.com/api/checkouts"))
    .header("Authorization", "Bearer sk_live_<sua-chave>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "id":          "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
  "status":      "pending",
  "amount":      2990,
  "description": "Camiseta tamanho M",
  "image_url":   null,
  "expires_at":  "2025-06-01T15:30:00.000Z",
  "is_live":     true,
  "payment_url": "https://pay.depixapp.com/chk_01jxxxxxxxxxxxxxxxxxxxxxx",
  "pix": {
    "qr_code": "00020126580014br.gov.bcb.pix..."    // payload EMV para QR code
  }
}

Cobrar direto em DePix: envie "payment_method": "depix" no mesmo endpoint. A resposta troca o bloco pix por um bloco depix com endereço, valor exato e link de pagamento — ver Receber DePix direto.

Formato da resposta: o POST /api/checkouts devolve o checkout plano, na raiz do JSON (como acima). Já o GET /api/checkouts/:id devolve o mesmo objeto embrulhado em { "checkout": { ... } } — ver Consultar checkout.

Consultar checkout

Retorna os detalhes de um checkout específico.

curl https://api.depixapp.com/api/checkouts/chk_01jxxxxxxxxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "checkout": {
    "id":             "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
    "status":         "completed",     // pending | processing | approved | completed | cancelled | expired
    "amount":         2990,
    "description":    "Camiseta tamanho M",
    "image_url":      null,
    "callback_url":   "https://minha-loja.com/webhook/depix",
    "redirect_url":   null,
    "metadata":       { "order_id": "ORD-123" },
    "expires_at":     "2025-06-01T15:30:00.000Z",      // todas as datas em UTC, formato RFC 3339
    "is_live":        1,
    "created_at":     "2025-06-01T15:00:00.000Z",
    "processing_at":  "2025-06-01T15:02:00.000Z",
    "approved_at":    "2025-06-01T15:03:00.000Z",
    "completed_at":   "2025-06-01T15:22:00.000Z",
    "cancelled_at":   null,
    "blockchain_tx_id": "abc123...def456",  // txid Liquid (presente quando completed)
    "rejection_reasons": [],        // array de motivos quando o pagamento foi devolvido/retido
    "delay_until":     null,        // quando o dinheiro é liberado, se a venda estiver retida
    "vault_hours":     0            // horas que essa venda ficou marcada para esperar (0 = nenhuma; null = sem registro)
  }
}

Formato da resposta: aqui o checkout vem embrulhado em { "checkout": { ... } }, enquanto o POST /api/checkouts devolve o objeto plano na raiz do JSON — atenção ao parsear os dois.

Enquanto o checkout está pending, a resposta também traz pix_payload (o payload EMV do QR Pix); o campo é omitido assim que o status sai de pending. approved_at está sempre presente (null até a aprovação).

Status possíveis

Venda paga que ainda não caiu

processing quer dizer que o dinheiro do pagador chegou até nós. Antes de cair na sua carteira, ele pode ficar um tempo guardado no Cofre — a proteção que segura o valor por até 14 dias para o caso de o pagamento ser contestado.

Liberar o produto ou serviço em processing é decisão sua. Quem vende conteúdo digital costuma liberar nessa hora; quem envia produto físico ou vende valores altos costuma esperar o completed.

Dois campos contam essa história:

• delay_until — a data em que o dinheiro cai. É a única data que vale; não calcule created_at + vault_hours. Vem null se a venda não foi retida, e também enquanto a data ainda não chegou do provedor.
• vault_hours — quantas horas de espera a venda recebeu ao ser criada. 0 = sem espera; null = sem registro (venda de sandbox ou venda paga em DePix).

O prazo diminui conforme a conta ganha tempo de uso e valor recebido:

A tabela é o caso normal. O prazo que vale para cada venda é sempre o delay_until dela.

Motivos de devolução (rejection_reasons)

Quando o pagamento de um checkout é devolvido ou retido pelo provedor, o campo rejection_reasons traz um array com os motivos ([] quando não houve recusa). Novos códigos podem surgir — trate valores desconhecidos de forma genérica.

Listar checkouts

Lista os checkouts do merchant com filtros e paginação.

Query params (todos opcionais)

curl "https://api.depixapp.com/api/checkouts?status=completed&limit=20" \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "checkouts": [
    {
      "id":            "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
      "status":        "completed",
      "amount":        2990,
      "description":   "Camiseta tamanho M",
      "product_name":  "Camiseta Preta",    // null se checkout não vier de um produto
      "metadata":      "{\"order_id\":\"42\"}",  // string JSON, null se ausente
      "created_at":    "2025-06-01T15:00:00.000Z",   // todas as datas em UTC, formato RFC 3339
      "processing_at": "2025-06-01T15:02:14.000Z",
      "approved_at":   "2025-06-01T15:03:00.000Z",
      "expires_at":    "2025-06-01T15:30:00.000Z",
      "is_live":       1,
      "payment_method": "depix",        // "pix" ou "depix" — a trilha em que a venda foi liquidada
      "depix_discount_pct": 10,       // só na trilha depix: desconto oferecido, em %
      "depix_due_cents": 2691,       // só na trilha depix: o valor que o pagador realmente envia
      "rejection_reasons": [],    // array de motivos quando o pagamento foi devolvido/retido
      "delay_until":   null,          // quando o dinheiro é liberado, se a venda estiver retida
      "vault_hours":   0              // horas que essa venda ficou marcada para esperar (0 = nenhuma; null = sem registro)
    }
  ],
  "stats": {
    "total":            47,
    "pending":          2,
    "completed":        40,
    "completed_amount":  189500    // centavos — R$ 1.895,00
  },
  "limit":  20,
  "offset": 0
}

Criar produto

Cria um novo produto com valor fixo. Cada produto gera um link de pagamento permanente que pode ser compartilhado com seus clientes.

Parâmetros

Exemplo

curl -X POST https://api.depixapp.com/api/products \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Camiseta M",
    "slug": "camiseta-m",
    "amount": 2990,
    "description": "Camiseta tamanho M"
  }'

const res = await fetch("https://api.depixapp.com/api/products", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_<sua-chave>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Camiseta M",
    slug: "camiseta-m",
    amount: 2990,
    description: "Camiseta tamanho M",
  }),
});
const data = await res.json();
console.log(data.product.payment_url);

import requests

resp = requests.post(
    "https://api.depixapp.com/api/products",
    headers={"Authorization": "Bearer sk_live_<sua-chave>"},
    json={
        "name": "Camiseta M",
        "slug": "camiseta-m",
        "amount": 2990,
        "description": "Camiseta tamanho M",
    },
)
data = resp.json()
print(data["product"]["payment_url"])

$ch = curl_init("https://api.depixapp.com/api/products");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_<sua-chave>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "Camiseta M",
        "slug" => "camiseta-m",
        "amount" => 2990,
        "description" => "Camiseta tamanho M",
    ]),
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data["product"]["payment_url"];

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_<sua-chave>");

var payload = new { name = "Camiseta M", slug = "camiseta-m", amount = 2990, description = "Camiseta tamanho M" };

var res = await client.PostAsync(
    "https://api.depixapp.com/api/products",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
Console.WriteLine(await res.Content.ReadAsStringAsync());

body := `{"name":"Camiseta M","slug":"camiseta-m","amount":2990,"description":"Camiseta tamanho M"}`

req, _ := http.NewRequest("POST", "https://api.depixapp.com/api/products", strings.NewReader(body))
req.Header.Set("Authorization", "Bearer sk_live_<sua-chave>")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

require "net/http"
require "json"

uri = URI("https://api.depixapp.com/api/products")
req = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer sk_live_<sua-chave>",
  "Content-Type" => "application/json",
})
req.body = { name: "Camiseta M", slug: "camiseta-m", amount: 2990, description: "Camiseta tamanho M" }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)

HttpClient client = HttpClient.newHttpClient();
String json = """
    {"name":"Camiseta M","slug":"camiseta-m","amount":2990,"description":"Camiseta tamanho M"}""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.depixapp.com/api/products"))
    .header("Authorization", "Bearer sk_live_<sua-chave>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "product": {
    "id":           "prd_xxx",
    "name":         "Camiseta M",
    "slug":         "camiseta-m",
    "amount":       2990,
    "description":  "Camiseta tamanho M",
    "image_url":    null,
    "callback_url": null,
    "redirect_url": null,
    "metadata":     null,
    "expires_in":   1200,
    "active":       true,
    "is_live":      true,
    "payment_url":  "https://pay.depixapp.com/joao/camiseta-m"
  }
}

Listar produtos

Lista os produtos do merchant com filtros e paginação.

Query params (todos opcionais)

curl "https://api.depixapp.com/api/products?active=1" \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "products": [
    {
      "id":          "prd_xxx",
      "name":        "Camiseta M",
      "slug":        "camiseta-m",
      "amount":      2990,
      "description": "Camiseta tamanho M",
      "active":      1,
      "is_live":     1,
      "position":    0,
      "created_at":  "2025-06-01T15:00:00.000Z",  // todas as datas em UTC, formato RFC 3339
      "total_checkouts":     12,
      "completed_checkouts": 5,
      "completed_amount":    14950,
      "settled_count":       5,
      "processing_count":    0
    }
  ],
  "limit":  50,
  "offset": 0
}

position — inteiro ou null. Ordem de exibição na vitrine pública. null = não fixado (ordenado por mais vendidos); inteiro = fixado, exibido na posição indicada (menor primeiro).

payment_url — só em linhas de cobrança (kind=charge). Para produtos o link é https://pay.depixapp.com/{merchant_slug}/{slug}, devolvido pronto na criação (201).

Consultar produto

Retorna os detalhes de um produto específico, incluindo estatísticas de checkouts.

curl https://api.depixapp.com/api/products/prd_xxx \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "product": {
    "id":           "prd_xxx",
    "name":         "Camiseta M",
    "slug":         "camiseta-m",
    "amount":       2990,
    "description":  "Camiseta tamanho M",
    "image_url":    null,
    "callback_url": null,
    "redirect_url": null,
    "metadata":     null,
    "expires_in":   1200,
    "active":       1,
    "is_live":      1,
    "position":     0,
    "created_at":   "2025-06-01T15:00:00.000Z"   // todas as datas em UTC, formato RFC 3339
  },
  "stats": {
    "total":            12,
    "completed":        5,
    "pending":          1,
    "completed_amount": 14950
  }
}

position — inteiro ou null. Ordem de exibição na vitrine pública. null = não fixado (ordenado por mais vendidos); inteiro = fixado, exibido na posição indicada (menor primeiro).

Editar produto

Atualiza um ou mais campos de um produto existente. Envie apenas os campos que deseja alterar.

Parâmetros (todos opcionais)

curl -X PATCH https://api.depixapp.com/api/products/prd_xxx \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 3490, "description": "Camiseta tamanho M - Edição Especial" }'

{ "success": true }

A resposta não devolve o produto — consulte Consultar produto para ler o estado atualizado.

Ativar / Desativar produto

Ativa ou desativa um produto. Produtos inativos retornam erro 404 quando acessados pelo link de pagamento.

curl -X POST https://api.depixapp.com/api/products/prd_xxx/activate \
  -H "Authorization: Bearer $DEPIX_API_KEY"

curl -X POST https://api.depixapp.com/api/products/prd_xxx/deactivate \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{ "success": true }

Destacar produtos na vitrine

Define a lista ordenada de produtos fixados no topo da página pública do lojista (a "vitrine"). Os produtos fixados aparecem primeiro, na ordem informada; todo produto que não estiver na lista é desfixado e volta à ordenação por mais vendidos. Enviar uma lista vazia remove todos os destaques. Esta requisição reconcilia o conjunto inteiro de fixados de uma só vez (não é incremental).

Parâmetros

Exemplo

curl -X POST https://api.depixapp.com/api/products/featured \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "productIds": ["prd_abc123", "prd_def456"] }'

const res = await fetch("https://api.depixapp.com/api/products/featured", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_<sua-chave>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    productIds: ["prd_abc123", "prd_def456"],
  }),
});
const data = await res.json();
console.log(data.featured);

import requests

resp = requests.post(
    "https://api.depixapp.com/api/products/featured",
    headers={"Authorization": "Bearer sk_live_<sua-chave>"},
    json={
        "productIds": ["prd_abc123", "prd_def456"],
    },
)
data = resp.json()
print(data["featured"])

$ch = curl_init("https://api.depixapp.com/api/products/featured");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_<sua-chave>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "productIds" => ["prd_abc123", "prd_def456"],
    ]),
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data["featured"]);

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_<sua-chave>");

var payload = new { productIds = new[] { "prd_abc123", "prd_def456" } };

var res = await client.PostAsync(
    "https://api.depixapp.com/api/products/featured",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
Console.WriteLine(await res.Content.ReadAsStringAsync());

body := `{"productIds":["prd_abc123","prd_def456"]}`

req, _ := http.NewRequest("POST", "https://api.depixapp.com/api/products/featured", strings.NewReader(body))
req.Header.Set("Authorization", "Bearer sk_live_<sua-chave>")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

require "net/http"
require "json"

uri = URI("https://api.depixapp.com/api/products/featured")
req = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer sk_live_<sua-chave>",
  "Content-Type" => "application/json",
})
req.body = { productIds: ["prd_abc123", "prd_def456"] }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)

HttpClient client = HttpClient.newHttpClient();
String json = """
    {"productIds":["prd_abc123","prd_def456"]}""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.depixapp.com/api/products/featured"))
    .header("Authorization", "Bearer sk_live_<sua-chave>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "success":  true,
  "featured": ["prd_abc123", "prd_def456"]
}

Erros possíveis: 400 (productIds não é uma lista, IDs repetidos ou mais de 50), 404 (algum produto não pertence ao lojista) e 403 (sem conta de lojista). Veja a seção Erros para o formato das respostas de erro.

Checkouts do produto

Lista os checkouts gerados a partir de um produto específico. Aceita os mesmos filtros da listagem geral de checkouts.

curl "https://api.depixapp.com/api/products/prd_xxx/checkouts?status=completed" \
  -H "Authorization: Bearer $DEPIX_API_KEY"

A resposta segue o mesmo formato da listagem de checkouts.

Cobranças

Uma cobrança é um produto com kind=charge: o mesmo endpoint, o mesmo checkout e os mesmos webhooks, com três diferenças — tem data de vencimento, pode ter multa e juros por atraso, e vive num link privado que nunca aparece na sua loja pública. É o formato certo para aluguel, mensalidade, parcela — qualquer valor que vence numa data e pode atrasar.

Crie com POST /api/products passando kind: "charge" e due_date; liste com GET /api/products?kind=charge. O link vem em payment_url no formato https://pay.depixapp.com/c/prd_xxx — endereçado por id (não por slug), com noindex, e a pré-visualização em apps de mensagem mostra o nome da sua loja e o título da cobrança, nunca o valor. Os demais endpoints de produto (GET, PATCH, ativar/desativar, checkouts do produto) funcionam em cobranças sem nenhuma mudança.

Se você tiver o recebimento direto em DePix ativado, a página da cobrança também oferece Pagar com DePix, ao lado do Pix — mesmo fluxo das páginas de loja e de produto. O valor cobrado no trilho DePix é o total do dia (valor original + multa + juros), com o seu desconto aplicado sobre esse total, e a quitação entra na fila da cobrança igual a um pagamento Pix. Nesse trilho não se pede CPF/CNPJ do pagador.

Como o valor é calculado

O valor não é fixo: ele é calculado no momento em que o pagador abre o link e gera o QR.

dias_de_atraso = dias corridos após o vencimento (fuso America/Sao_Paulo)
multa          = valor_base × late_fine_bps / 10000              // uma vez só
juros          = valor_base × late_interest_monthly_bps / 10000 × dias_de_atraso / 30
total          = min(valor_base + multa + juros, 600000)          // teto por transação

O dia do vencimento não conta como atraso — o atraso começa no dia seguinte. Não há adiamento para fim de semana ou feriado: o Pix funciona 24/7. Os juros são lineares (pro-rata por dia), nunca compostos. Não há correção monetária.

Recorrência e quitação (FIFO)

Com recurrence, a cobrança vira uma série de vencimentos ancorada em due_date, e o mesmo link serve para sempre. Cada pagamento quita a competência mais antiga em aberto; a próxima visita já mostra a seguinte. A competência quitada por cada checkout vai em metadata.charge_cycle, e o webhook traz data.product_id — juntos, dizem exatamente qual mês foi pago.

Duas regras que decidem qual competência um QR cobra, e valem a leitura antes de integrar:

• Um QR em aberto reserva a competência dele. O valor e a competência são congelados quando o QR é criado, mas a posição na série é resolvida na liquidação. Se dois QRs vivos fossem precificados como a mesma competência e ambos fossem pagos, o segundo pagador levaria a multa e os juros de uma competência que não estava atrasada. Por isso um QR ainda válido conta para a posição: o próximo QR já sai precificado na competência que ele realmente vai quitar. QRs expirados não contam.
• A posição nunca anda para trás. Conta-se competência que já liquidou alguma vez. Um estorno (MED, reembolso por divergência de CPF) portanto não faz o link recobrar uma competência já paga nem aplicar os encargos do ciclo errado — e também não recobra sozinho a competência estornada. Isso é decisão do lojista: você recebe checkout.cancelled e vê a venda cancelada, e decide o que fazer.

charge_state

Presente em cada linha de GET /api/products?kind=charge e na resposta 201 do checkout de uma cobrança.

{
  "settled":              false,      // true = cobrança única já paga (demais campos ausentes)
  "cycle_due_date":       "2026-08-05",  // competência corrente (mais antiga em aberto)
  "days_late":            10,
  "base_cents":           250000,
  "fine_cents":           5000,
  "interest_cents":       833,
  "total_today_cents":    255833,   // o que um QR criado agora cobra
  "capped":               false,      // true = base + encargos passou do teto e foi limitado
  "status":               "late",      // late | due_today | upcoming
  "open_past_due_cycles": 1,         // > 1 = competências acumuladas
  "in_flight":            false       // um Pix pago desta cobrança está liquidando
}

Erros específicos

Links de pagamento

O DePix App gera links de pagamento permanentes para produtos e para a página do merchant. Esses links criam checkouts sob demanda quando o cliente acessa.

Tipos de link

Ciclo de vida

• Quando o cliente acessa o link e inicia o pagamento, um checkout individual é criado automaticamente.
• A partir daí, o ciclo de vida é idêntico a um checkout criado via API (status, webhooks, expiração).
• O callback_url segue a cadeia: campo do produto (se houver) → default do merchant → null.
• O redirect_url segue a mesma cadeia.

Produto público

Retorna os dados públicos de um produto ativo. Não requer autenticação.

curl https://api.depixapp.com/api/products/prd_xxx/public

{
  "product": {
    "id":          "prd_xxx",
    "name":        "Camiseta M",
    "slug":        "camiseta-m",
    "amount":      2990,
    "description": "Camiseta tamanho M",
    "image_url":   null
  },
  "merchant": {
    "name":          "Loja do Joao",
    "merchant_slug": "joao",
    "username":      "joao"
  }
}

Checkout do produto

Cria um checkout a partir de um produto ativo. Não requer autenticação. O valor é herdado do produto.

Parâmetros

curl -X POST https://api.depixapp.com/api/products/prd_xxx/checkout \
  -H "Content-Type: application/json" \
  -d '{ "payer_tax_number": "52998224725" }'

A resposta segue o mesmo formato do criar checkout (status 201).

Página do merchant

Retorna os dados públicos do merchant. Não requer autenticação.

curl https://api.depixapp.com/api/merchants/joao/public

{
  "merchant": {
    "name":          "Loja do Joao",
    "merchant_slug": "joao",
    "username":      "joao"
  }
}

Checkout do merchant

Cria um checkout com valor customizado a partir da página do merchant. Não requer autenticação.

Parâmetros

curl -X POST https://api.depixapp.com/api/merchants/joao/checkout \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "payer_tax_number": "52998224725" }'

A resposta segue o mesmo formato do criar checkout (status 201).

Receber DePix direto (Liquid)

Todo checkout pode ser cobrado por um de dois trilhos, escolhido no campo payment_method. O padrão (pix) é o QR Pix de sempre. O alternativo (depix) cobra direto em DePix: quem paga envia DePix de carteira para carteira na rede Liquid, para um endereço exclusivo daquele lojista, e o DePix App acompanha a rede para confirmar o pagamento. Não existe QR Pix, não se pede CPF do pagador, e o dinheiro cai direto na carteira do lojista.

Como o lojista ativa

O recebimento direto é ligado pelo próprio dono da conta no DePix App, em Receber com DePix (confirmação de senha). Ao ativar, o app cria um endereço exclusivo para esses recebimentos — separado do endereço que recebe as liquidações de Pix — e o lojista escolhe um desconto de 0% a 90% para quem pagar por esse trilho. Não existe endpoint de API key para ligar o trilho nem para mudar o desconto: é sempre o dono, logado, com senha.

Enquanto o lojista não ativar, qualquer criação com payment_method: "depix" devolve depix_not_enabled (400) — o trilho Pix continua funcionando normalmente.

Criar uma cobrança em DePix

Mesmos endpoints de sempre (POST /api/checkouts, checkout do produto e checkout do merchant), trocando só o trilho.

curl -X POST https://api.depixapp.com/api/checkouts \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9990,
    "payment_method": "depix",
    "description": "Pedido #124",
    "expires_in": 1800,
    "expected_discount_pct": 10
  }'

const res = await fetch("https://api.depixapp.com/api/checkouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_<sua-chave>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 9990,
    payment_method: "depix",
    description: "Pedido #124",
    expires_in: 1800,
    expected_discount_pct: 10,
  }),
});
const data = await res.json();
console.log(data.depix.amount, data.depix.uri);

import requests

resp = requests.post(
    "https://api.depixapp.com/api/checkouts",
    headers={"Authorization": "Bearer sk_live_<sua-chave>"},
    json={
        "amount": 9990,
        "payment_method": "depix",
        "description": "Pedido #124",
        "expires_in": 1800,
        "expected_discount_pct": 10,
    },
)
data = resp.json()
print(data["depix"]["amount"], data["depix"]["uri"])

{
  "id":             "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
  "status":         "pending",
  "amount":         9990,
  "description":    "Pedido #124",
  "image_url":      null,
  "expires_at":     "2026-07-29T12:30:00.000Z",
  "is_live":        true,
  "payment_url":    "https://pay.depixapp.com/chk_01jxxxxxxxxxxxxxxxxxxxxxx",
  "payment_method": "depix",
  "depix": {
    "address":               "lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq...",
    "amount_cents":          8991,
    "amount":                "89.91",
    "asset_id":              "02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189",
    "uri":                   "liquidnetwork:lq1qqw8re6...?amount=89.91&assetid=02f22f8d...&depixid=chk_01jxxx...",
    "discount_pct":          10,
    "original_amount_cents": 9990,
    "detected":              false
  }
}

O checkout em DePix não traz o bloco pix — ele simplesmente não existe nesse trilho. Um checkout Pix, por sua vez, não traz o bloco depix. Sempre olhe payment_method antes de ler o payload de pagamento.

O objeto depix

Fluxo de status

Os status processing e cancelled não são usados nesse trilho. Enquanto o tempo mostra 0 e o status ainda é pending, continue consultando: é a janela de tolerância acima, não uma cobrança travada.

Por que o valor tem centavos "quebrados"?

O pagamento é identificado pelo valor exato. Para que duas cobranças abertas do mesmo lojista nunca tenham o mesmo valor, a API pode baixar alguns centavos — o valor pode variar até R$ 0,99 para baixo, sempre a favor de quem paga. Por isso o valor cobrado (depix.amount_cents) pode ser alguns centavos menor que o valor de face menos o desconto. Cobre e concilie sempre pelo valor que a API devolveu, nunca por um valor recalculado por você.

Uma consequência prática: pagamento com valor diferente do informado não é creditado automaticamente — ele vira um recebimento não atribuído (o lojista vê no app e recebe o webhook checkout.unmatched_payment). O dinheiro está na carteira do lojista; só a associação automática com o pedido não aconteceu.

Webhooks e conciliação

Nos eventos checkout.* desse trilho, amount continua sendo o valor de face, e o valor efetivamente pago vem em amount_received (com discount_pct e payment_method ao lado). Libere o pedido pelo amount_received. Se você concilia consultando a cobrança em vez de escutar o webhook, o bloco depix do GET /api/checkouts/{id} continua lá depois do pagamento — depix.amount_cents é o valor que entrou (o uri vem null, porque não há mais nada a pagar). Recebimentos que não casam com nenhuma cobrança geram o evento checkout.unmatched_payment, enviado para o default_callback_url do lojista.

depix_not_enabled          400   lojista não aceita recebimento direto em DePix
depix_busy                 409   sem valor único disponível agora — ofereça o Pix
discount_changed           409   o desconto mudou (details traz os valores atuais)
depix_address_unsupported  400   endereço de recebimento não é um lq1... confidencial
depix_address_conflict     400   o endereço precisa ser exclusivo desse recebimento
invalid_blinding_key       400   a chave de leitura não corresponde ao endereço

Os três últimos só aparecem no fluxo de ativação feito pelo dono da conta no app; uma integração por API key nunca os encontra.

Depósito e Saque (scopes wallet_*)

Além de receber por checkouts, uma API key com os scopes wallet_* movimenta o lado "pagar" da conta: gera QR Pix de depósito pessoal (on-ramp BRL → DePix) e cria saques DePix → Pix (off-ramp). É a mesma superfície que a UI humana usa — limites, delays e verificação da conta valem por construção.

Taxas

As taxas são descontadas do valor — o que o pagador envia não é o que o destino recebe. Planeje pelo valor líquido:

As duas faixas de saque se encontram sem degrau: em exatamente R$ 100,00 as duas regras custam R$ 2,00. As taxas podem mudar — a tabela canônica e sempre atualizada é o quadro de taxas em depixapp.com; trate os valores acima como ilustração do formato, não como contrato.

O ativo DePix na Liquid

O DePix é um ativo emitido na Liquid mainnet, com 8 casas decimais e paridade 1:1 com o BRL. O id do ativo é:

02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189

Você precisa dele sempre que montar a transação Liquid por conta própria em vez de deixar o SDK montar — em especial a saída da taxa de saque, que precisa pagar fee_cents para fee_address como saída DePix explícita (não-blindada) na mesma transação. Pagar o ativo errado, ou pagar blindado, faz o saque falhar e pode perder os fundos.

O fluxo de depósito (on-ramp)

• 1. POST /api/deposit → QR Pix (qrCopyPaste) + id.
• 2. O dono da conta paga o QR num app de banco.
• 3. Acompanhe por polling em GET /api/deposits/:id (5–15s) e/ou pelos webhooks deposit.* até o status terminal depix_sent — o DePix chegou no endereço Liquid informado.

O depósito pessoal conta para a verificação da conta. Alternativa de on-ramp: criar um checkout contra si mesmo — note que pagamentos de checkout não contam para a verificação.

O fluxo de saque (off-ramp)

• 1. POST /api/withdraw → cotação com depositAddress (endereço Liquid do provedor).
• 2. Envie o DePix para o depositAddress a partir da sua wallet — a assinatura é sempre do lado do cliente; a API jamais toca chave privada ou custodia fundos.
• 3. Acompanhe por GET /api/withdrawals/:id e/ou pelos webhooks withdraw.* até sent — o Pix chegou na chave de destino.

Limites

Duas camadas, sempre em conjunto (AND):

• Limites de conta — herdados da conta do dono e sempre prevalecentes. Cobrem primeiro depósito, valor por transação, atraso nos primeiros depósitos e tetos máximos de depósito e saque. Os valores dependem do nível de verificação da conta e podem mudar — não os codifique. Ao exceder → 400 account_limit_exceeded, com details informando limit_cents/used_cents vigentes.
• Limites de chave — os limites de gasto que o dono definiu ao criar a chave wallet_write (per_tx_limit_cents, daily_limit_cents; ver Scopes e limites), visíveis em GET /api/api-keys. Ao exceder → 400 key_limit_exceeded (details.limit = per_tx | daily).

Sandbox sintético (sk_test_)

Com uma chave sk_test_, deposit e withdraw respondem com payloads sintéticos marcados "sandbox": true: strings SANDBOX-…-DO-NOT-PAY impagáveis, ids sandbox_*, zero dinheiro, zero chamada ao provedor, zero registro criado. Todos os gates de conta e o limite por transação da chave são checados normalmente — o sandbox ensina os limites reais. Ver Sandbox.

Criar depósito

Gera um QR Pix de depósito pessoal. Quando o Pix é pago, o DePix é entregue no endereço Liquid informado. Exige scope wallet_write. Aceita Idempotency-Key.

Parâmetros

Exemplo

curl -X POST https://api.depixapp.com/api/deposit \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dep-pedido-42" \
  -d '{
    "amountInCents": 5000,
    "depixAddress": "lq1qq...",
    "payer_tax_number": "529.982.247-25"
  }'

const res = await fetch("https://api.depixapp.com/api/deposit", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_<sua-chave>",
    "Content-Type": "application/json",
    "Idempotency-Key": "dep-pedido-42",
  },
  body: JSON.stringify({
    amountInCents: 5000,
    depixAddress: "lq1qq...",
    payer_tax_number: "529.982.247-25",
  }),
});
const data = await res.json();
console.log(data.response.qrCopyPaste, data.response.id);

import requests

resp = requests.post(
    "https://api.depixapp.com/api/deposit",
    headers={
        "Authorization": "Bearer sk_live_<sua-chave>",
        "Idempotency-Key": "dep-pedido-42",
    },
    json={
        "amountInCents": 5000,
        "depixAddress": "lq1qq...",
        "payer_tax_number": "529.982.247-25",
    },
)
data = resp.json()
print(data["response"]["qrCopyPaste"], data["response"]["id"])

$ch = curl_init("https://api.depixapp.com/api/deposit");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_<sua-chave>",
        "Content-Type: application/json",
        "Idempotency-Key: dep-pedido-42",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amountInCents" => 5000,
        "depixAddress" => "lq1qq...",
        "payer_tax_number" => "529.982.247-25",
    ]),
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data["response"]["qrCopyPaste"];

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_<sua-chave>");
client.DefaultRequestHeaders.Add("Idempotency-Key", "dep-pedido-42");

var payload = new {
    amountInCents = 5000,
    depixAddress = "lq1qq...",
    payer_tax_number = "529.982.247-25"
};

var res = await client.PostAsync(
    "https://api.depixapp.com/api/deposit",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
var json = await res.Content.ReadAsStringAsync();
Console.WriteLine(json);

body := `{"amountInCents":5000,"depixAddress":"lq1qq...","payer_tax_number":"529.982.247-25"}`

req, _ := http.NewRequest("POST", "https://api.depixapp.com/api/deposit", strings.NewReader(body))
req.Header.Set("Authorization", "Bearer sk_live_<sua-chave>")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "dep-pedido-42")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

require "net/http"
require "json"

uri = URI("https://api.depixapp.com/api/deposit")
req = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer sk_live_<sua-chave>",
  "Content-Type" => "application/json",
  "Idempotency-Key" => "dep-pedido-42",
})
req.body = { amountInCents: 5000, depixAddress: "lq1qq...",
             payer_tax_number: "529.982.247-25" }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)

HttpClient client = HttpClient.newHttpClient();
String json = """
    {"amountInCents":5000,"depixAddress":"lq1qq...","payer_tax_number":"529.982.247-25"}""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.depixapp.com/api/deposit"))
    .header("Authorization", "Bearer sk_live_<sua-chave>")
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "dep-pedido-42")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "async": false,
  "response": {
    "qrCopyPaste": "00020126580014br.gov.bcb.pix...",   // payload EMV para QR code
    "qrImageUrl":  "https://qr.example/qr-id-456.png",
    "id":          "qr-id-456"                          // use no GET /api/deposits/:id
  }
}

{
  "async": false,
  "response": {
    "qrCopyPaste": "SANDBOX-DEPIX-TEST-MODE-DO-NOT-PAY-a1b2c3d4e5f60708",
    "qrImageUrl":  null,
    "id":          "sandbox_3uw_a1b2c3d4e5f60708",   // sandbox_<amount36>_<hex> — 5000 → 3uw
    "sandbox":     true
  }
}

Status do depósito

Consulta o status de um depósito criado via POST /api/deposit. Ownership é obrigatório: id de outra conta → 404. Faça polling a cada 5–15 segundos até um status terminal — depix_sent é o sucesso terminal.

curl https://api.depixapp.com/api/deposits/qr-id-456 \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "id":           "qr-id-456",
  "type":         "deposit",
  "amount_cents": 5000,
  "status":       "depix_sent",
  "created_at":   "2026-07-01T12:00:00.000Z",
  "updated_at":   "2026-07-01T12:34:56.000Z",
  "rejection_reasons": []   // sempre presente; [] quando não houve recusa
}

Status possíveis

Motivos de devolução (rejection_reasons)

A resposta sempre traz rejection_reasons como array — [] quando não houve recusa. Assim um agente em polling lê o campo incondicionalmente, sem checar existência. Ele é preenchido quando o pagamento foi devolvido ou retido pelo provedor (tipicamente nos status will_refund, refunded e error). Novos códigos podem surgir — exiba valores desconhecidos como recebidos. Saques não têm rejection_reasons.

Criar saque

Cota um saque DePix → Pix: a resposta traz o endereço Liquid do provedor para onde você envia o DePix. Depois de transmitir a transação, acompanhe o status. Exige scope wallet_write. Aceita Idempotency-Key.

Parâmetros

Envie exatamente um entre depositAmountInCents (modo "você envia") e payoutAmountInCents (modo "você recebe") — os mesmos dois modos da UI humana.

Exemplo

curl -X POST https://api.depixapp.com/api/withdraw \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-pedido-42" \
  -d '{
    "pixKey": "alguem@exemplo.com",
    "depositAmountInCents": 10000,
    "taxNumber": "529.982.247-25",
    "refundAddress": "lq1qq..."
  }'

const res = await fetch("https://api.depixapp.com/api/withdraw", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_<sua-chave>",
    "Content-Type": "application/json",
    "Idempotency-Key": "saque-pedido-42",
  },
  body: JSON.stringify({
    pixKey: "alguem@exemplo.com",
    depositAmountInCents: 10000,
    taxNumber: "529.982.247-25",
    refundAddress: "lq1qq...",
  }),
});
const data = await res.json();
console.log(data.response.withdrawalId, data.response.depositAddress);

import requests

resp = requests.post(
    "https://api.depixapp.com/api/withdraw",
    headers={
        "Authorization": "Bearer sk_live_<sua-chave>",
        "Idempotency-Key": "saque-pedido-42",
    },
    json={
        "pixKey": "alguem@exemplo.com",
        "depositAmountInCents": 10000,
        "taxNumber": "529.982.247-25",
        "refundAddress": "lq1qq...",
    },
)
data = resp.json()
print(data["response"]["withdrawalId"], data["response"]["depositAddress"])

$ch = curl_init("https://api.depixapp.com/api/withdraw");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_<sua-chave>",
        "Content-Type: application/json",
        "Idempotency-Key: saque-pedido-42",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "pixKey" => "alguem@exemplo.com",
        "depositAmountInCents" => 10000,
        "taxNumber" => "529.982.247-25",
        "refundAddress" => "lq1qq...",
    ]),
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
echo $data["response"]["depositAddress"];

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_<sua-chave>");
client.DefaultRequestHeaders.Add("Idempotency-Key", "saque-pedido-42");

var payload = new {
    pixKey = "alguem@exemplo.com",
    depositAmountInCents = 10000,
    taxNumber = "529.982.247-25",
    refundAddress = "lq1qq..."
};

var res = await client.PostAsync(
    "https://api.depixapp.com/api/withdraw",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
var json = await res.Content.ReadAsStringAsync();
Console.WriteLine(json);

body := `{"pixKey":"alguem@exemplo.com","depositAmountInCents":10000,"taxNumber":"529.982.247-25","refundAddress":"lq1qq..."}`

req, _ := http.NewRequest("POST", "https://api.depixapp.com/api/withdraw", strings.NewReader(body))
req.Header.Set("Authorization", "Bearer sk_live_<sua-chave>")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "saque-pedido-42")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

require "net/http"
require "json"

uri = URI("https://api.depixapp.com/api/withdraw")
req = Net::HTTP::Post.new(uri, {
  "Authorization" => "Bearer sk_live_<sua-chave>",
  "Content-Type" => "application/json",
  "Idempotency-Key" => "saque-pedido-42",
})
req.body = { pixKey: "alguem@exemplo.com", depositAmountInCents: 10000,
             taxNumber: "529.982.247-25", refundAddress: "lq1qq..." }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(res.body)

HttpClient client = HttpClient.newHttpClient();
String json = """
    {"pixKey":"alguem@exemplo.com","depositAmountInCents":10000,"taxNumber":"529.982.247-25","refundAddress":"lq1qq..."}""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.depixapp.com/api/withdraw"))
    .header("Authorization", "Bearer sk_live_<sua-chave>")
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "saque-pedido-42")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

{
  "response": {
    "withdrawalId":              "wd-123",           // use no GET de status
    "depositAddress":            "lq1qq2v9wxkyz...", // envie o DePix do saque para cá
    "depositAmountInCents":      9900,               // o que o provedor recebe
    "payoutAmountInCents":       9800,               // o que a chave Pix recebe
    "totalDepositAmountInCents": 10000,              // saída bruta da wallet (provedor + taxa)
    "split":                     { "address": "ex1qfee...", "amountCentavos": 100 },
    "fee_cents":                 100,                // taxa da plataforma — OBRIGATÓRIA na mesma transação
    "fee_address":               "ex1qfee..."        // endereço da taxa (forma não-confidencial)
  }
}

A resposta via API key inclui fee_cents e fee_address: a taxa da plataforma que a sua transação Liquid deve pagar como uma segunda saída explícita (não-blindada, asset DePix) para o fee_address, na mesma transação da saída principal para o depositAddress. Pague o fee_address exatamente como recebido — ele vem na forma não-confidencial (ex1...) de propósito: uma saída confidencial/blindada não pode ser verificada e conta como taxa não paga. A taxa é verificada automaticamente na transação Liquid que paga o saque.

{
  "response": {
    "withdrawalId":         "sandbox_0011223344556677",
    "depositAddress":       "SANDBOX-LIQUID-ADDRESS-DO-NOT-PAY",
    "depositAmountInCents": 9900,                // o que vai ao provedor: o valor digitado menos a nossa taxa
    "payoutAmountInCents":  9800,                // mesma conta do live: ~1% do provedor com piso de R$ 1
    "totalDepositAmountInCents": 10000,          // o que sai da carteira
    "split": { "address": "SANDBOX-LIQUID-FEE-ADDRESS-DO-NOT-PAY", "amountCentavos": 100 },
    "fee_cents":            100,                 // nossa taxa de 1%, no segundo output
    "fee_address":          "SANDBOX-LIQUID-FEE-ADDRESS-DO-NOT-PAY",
    "sandbox":              true
  }
}

Status do saque

Consulta o status de um saque criado via POST /api/withdraw. Ownership é obrigatório: id de outra conta → 404. Faça polling a cada 5–15 segundos até um status terminal — sent é o sucesso terminal.

curl https://api.depixapp.com/api/withdrawals/wd-123 \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "id":           "wd-123",
  "type":         "withdraw",
  "amount_cents": 10000,                // lado enviado (depositAmountInCents)
  "status":       "sent",
  "created_at":   "2026-07-01T10:00:00.000Z",
  "updated_at":   "2026-07-01T10:00:00.000Z",
  "liquid_txid":  "abab...ab"           // presente após a detecção on-chain da transferência
}

Status possíveis

Webhooks

Quando o status de um checkout muda, a API envia um POST para o callback_url que você informou ao criar o checkout (ou configurado no produto/merchant). Depósitos e saques criados via API key também disparam webhooks (eventos deposit.*/withdraw.*) para o default_callback_url do merchant — ver Eventos.

Como funciona

• O request é enviado com timeout de 30 segundos.
• Se falhar (resposta não-2xx, timeout ou erro de rede), a API tenta novamente até 5 vezes: após 1 minuto, 10 minutos, 1 hora, 4 horas e 12 horas (6 tentativas no total, cobrindo cerca de 17 horas).
• Sua endpoint deve responder com status 2xx para confirmar recebimento.
• O callback_url precisa ser HTTPS e de acesso público (sem IPs privados).

Headers enviados

• X-DePix-Signature — assinatura HMAC-SHA256 (ver seção Verificar assinatura).
• X-DePix-Event — nome do evento (ex: checkout.completed).
• X-DePix-Event-Id — identificador único e estável entre tentativas deste evento (ex: evt_abc123…). É a chave recomendada para deduplicação.
• X-DePix-Delivery-Attempt — número da tentativa atual (1, 2, … até 6). Muda a cada retry; não use para dedupe.
• User-Agent — sempre DePix-Webhook/1.0.

Entrega at-least-once e idempotência (obrigatório)

Webhooks são entregues com semântica at-least-once — é o padrão do mercado (Stripe, PayPal, Mercado Pago funcionam da mesma forma). Isso significa que o mesmo evento pode chegar ao seu endpoint mais de uma vez, mesmo que tudo esteja funcionando corretamente. Cenários comuns:

• Seu servidor processa o webhook mas responde lentamente — nossa API faz timeout em 30s, marca como falha e tenta novamente; você processa duas vezes.
• Seu servidor responde 200 mas a conexão cai antes da gente ler a resposta — mesma coisa: retry e processamento duplicado.
• O time de operações reenvia manualmente um evento (via comando administrativo) que você já processou.

Para evitar entregar produto duas vezes, creditar saldo em duplicidade, ou disparar acionamentos múltiplos, seu endpoint precisa ser idempotente. A forma mais simples e robusta é deduplicar por X-DePix-Event-Id: guarde os IDs de eventos já processados e ignore silenciosamente qualquer evento cujo ID já esteja na sua tabela.

// Exemplo de dedupe (Node.js, pseudo-código)
app.post("/webhook", async (req, res) => {
  // 1. Valide a assinatura HMAC primeiro (ver seção Verificar assinatura).

  const eventId = req.headers["x-depix-event-id"];

  // 2. Processe E marque como processado dentro da MESMA transação — se
  // processCheckout falhar, o INSERT também é revertido e o nosso retry
  // consegue entregar o evento novamente.
  try {
    await db.transaction(async (tx) => {
      await tx.query(
        "INSERT INTO processed_webhooks (event_id, received_at) VALUES (?, NOW())",
        [eventId]
      );
      await processCheckout(req.body, tx);
    });
  } catch (err) {
    if (err.code === "ER_DUP_ENTRY") {
      // Já processamos antes — responde 200 e ignora.
      return res.sendStatus(200);
    }
    throw err; // Deixa nossa API tentar novamente.
  }

  res.sendStatus(200);
});

Se preferir não manter uma tabela separada, você também pode deduplicar pelo campo event_id dentro do JSON (data.event_id) — ele carrega o mesmo valor estável do header X-DePix-Event-Id. Não use (data.id, event) como chave de dedupe: um reenvio manual feito pela equipe de operações reusa o mesmo id de checkout e o mesmo nome de evento, então uma chave baseada nessa tupla descartaria silenciosamente o reenvio.

Reduzindo retries

Para evitar entregas duplicadas no caminho feliz, responda o mais rápido possível — alvos comuns ficam abaixo de poucos segundos, para deixar folga para a latência de rede antes do nosso timeout de 30s. O padrão recomendado é: validar a assinatura, responder 200 imediatamente e processar o evento em background (fila, worker, etc.). Isso evita retries causados por timeout do nosso lado.

Eventos

checkout.processing

Disparado quando o pagamento Pix é recebido e a conversão está sendo processada.

{
  "event": "checkout.processing",
  "data": {
    "event_id":       "evt_01jxxxxxxxxxxxxxxxxxxxxxx",
    "id":             "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
    "product_id":     null,
    "status":         "processing",
    "amount":         2990,
    "processing_at":  "2025-06-01T15:02:00.000Z",
    "metadata":       { "order_id": "ORD-123" }
  }
}

checkout.approved

Disparado quando o pagamento é aprovado pelo banco e aguarda a liquidação final em DePix.

{
  "event": "checkout.approved",
  "data": {
    "event_id":     "evt_01jxxxxxxxxxxxxxxxxxxxxxx",
    "id":           "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
    "product_id":   null,
    "status":       "approved",
    "amount":       2990,
    "approved_at":  "2025-06-01T15:05:00.000Z",
    "metadata":     { "order_id": "ORD-123" }
  }
}

checkout.completed

Disparado quando o pagamento é confirmado e o DePix chega na carteira do merchant.

{
  "event": "checkout.completed",
  "data": {
    "event_id":      "evt_01jxxxxxxxxxxxxxxxxxxxxxx",
    "id":            "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
    "product_id":    null,
    "status":        "completed",
    "amount":        2990,
    "completed_at":  "2025-06-01T15:22:00.000Z",
    "metadata":      { "order_id": "ORD-123" }
  }
}

checkout.cancelled

Disparado quando o pagamento do checkout é cancelado, estornado ou entra em reembolso pelo provedor Pix. O payload traz rejection_reasons com o motivo — dá para revogar o pedido e registrar o porquê sem uma consulta extra.

{
  "event": "checkout.cancelled",
  "data": {
    "event_id":      "evt_01jxxxxxxxxxxxxxxxxxxxxxx",
    "id":            "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
    "product_id":    null,
    "status":        "cancelled",
    "amount":        2990,
    "cancelled_at":  "2025-06-01T15:05:00.000Z",
    "rejection_reasons": ["PAYER_MISMATCH"],  // o motivo — mesmo catálogo do GET; [] quando o provedor não informou
    "metadata":      { "order_id": "ORD-123" }
  }
}

checkout.expired

Disparado quando o checkout expira sem receber pagamento.

{
  "event": "checkout.expired",
  "data": {
    "event_id":    "evt_01jxxxxxxxxxxxxxxxxxxxxxx",
    "id":          "chk_01jxxxxxxxxxxxxxxxxxxxxxx",
    "product_id":  null,
    "status":      "expired",
    "amount":      2990,
    "expires_at":  "2025-06-01T15:30:00.000Z",
    "metadata":    { "order_id": "ORD-123" }
  }
}

checkout.unmatched_payment

Só no trilho DePix direto: chegou um pagamento no endereço do lojista que não casa com nenhuma cobrança (valor diferente do informado, pagamento depois da janela de tolerância, ou um segundo pagamento para uma cobrança já quitada). O dinheiro está na carteira do lojista — só a associação automática com o pedido não aconteceu, e a conciliação é uma decisão humana. Como não há checkout, a entrega vai para o default_callback_url do merchant.

{
  "event": "checkout.unmatched_payment",
  "data": {
    "event_id":     "evt_01jxxxxxxxxxxxxxxxxxxxxxx",
    "id":           "dout_9f8e7d6c5b4a",
    "type":         "depix_output",
    "status":       "unattributed",
    "amount_cents": 8997,
    "txid":         "abab…",
    "vout":         1,
    "first_seen_at": "2026-07-29T12:07:00.000Z",
    "reason":       "no_matching_checkout"
  }
}

status é unattributed (nenhuma cobrança aberta com esse valor exato) ou duplicate (segundo pagamento de uma cobrança já quitada). first_seen_at é quando o pagamento foi visto no endereço do lojista — pode ser alguns minutos antes desse aviso — e é o mesmo horário que aparece no app. reason detalha o motivo (no_matching_checkout, duplicate_payment, ambiguous_candidates, value_not_whole_cents, max_attributions_per_tx, transition_lost); concilie pelo id, não por esse texto.

Eventos deposit.* e withdraw.*

Depósitos e saques criados via API key (scope wallet_write) disparam um evento por transição real de status, nomeado 1:1 com o status cru: deposit.<status> / withdraw.<status>. Operações humanas (dashboard/SPA) não disparam. A entrega vai para o default_callback_url do merchant — sem ele configurado, nada é enviado. Operações sandbox (sk_test_) não criam registros e portanto nunca disparam webhooks.

Criar um depósito ou saque não emite webhook — o primeiro evento que você recebe é a próxima mudança de status. Por isso os eventos de estado inicial (deposit.pending, withdraw.unsent) só aparecem na reversão incomum de volta a esse estado.

O payload usa o mesmo shape em inglês dos GETs de status, mais o event_id — a chave de dedupe (mesmo valor do header X-DePix-Event-Id, estável entre retries). Payloads deposit.* sempre trazem rejection_reasons (array, [] quando não houve recusa) — com conteúdo em deposit.refunded, deposit.will_refund e deposit.error; vazio nos demais eventos. Payloads withdraw.* não têm esse campo:

{
  "event": "deposit.depix_sent",
  "data": {
    "id":           "qr-id-456",
    "type":         "deposit",
    "amount_cents": 5000,
    "status":       "depix_sent",
    "created_at":   "2026-07-01T12:00:00.000Z",
    "updated_at":   "2026-07-01T12:34:56.000Z",
    "rejection_reasons": [],   // ex.: ["PAYER_MISMATCH"] em deposit.refunded
    "event_id":     "evt_9f8e7d6c5b4a"
  }
}

{
  "event": "withdraw.sent",
  "data": {
    "id":           "wd-123",
    "type":         "withdraw",
    "amount_cents": 10000,
    "status":       "sent",
    "created_at":   "2026-07-01T10:00:00.000Z",
    "updated_at":   "2026-07-01T10:00:00.000Z",
    "liquid_txid":  "abab...ab",
    "event_id":     "evt_1a2b3c4d5e6f"
  }
}

Verificar assinatura

Cada webhook vem com um header X-DePix-Signature. Sempre valide a assinatura antes de processar o evento — isso garante que o request veio da API do DePix App e não de terceiros.

Formato do header

X-DePix-Signature: t=1717257600,v1=abc123def456...

• t — timestamp Unix do envio (segundos).
• v1 — assinatura HMAC-SHA256 em hexadecimal.

Como validar

A assinatura é calculada sobre a string timestamp.payload usando o Webhook Secret da sua conta (disponível em Meu Negócio).

# Calcular a assinatura esperada
EXPECTED=$(echo -n "${TIMESTAMP}.${RAW_BODY}" | \
  openssl dgst -sha256 -hmac "${WEBHOOK_SECRET}" | awk '{print $2}')

# Comparar com o v1 recebido
if [ "$EXPECTED" = "$RECEIVED_V1" ]; then
  echo "Assinatura válida"
fi

import crypto from "node:crypto";

function verifyWebhook(rawBody, sigHeader, secret) {
  const parts = Object.fromEntries(
    sigHeader.split(",").map(p => p.split("=", 2))
  );
  const timestamp = parts["t"];
  const received  = parts["v1"];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  // Use timingSafeEqual to prevent timing attacks
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

// Exemplo com Express
app.post("/webhook/depix", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-depix-signature"];
  if (!verifyWebhook(req.body.toString(), sig, process.env.DEPIX_WEBHOOK_SECRET)) {
    return res.status(401).send("Assinatura inválida");
  }
  const { event, data } = JSON.parse(req.body);
  // processa o evento...
  res.sendStatus(200);
});

import hmac, hashlib

def verify_webhook(raw_body: str, sig_header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in sig_header.split(","))
    timestamp = parts["t"]
    received = parts["v1"]
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, received)

function verifyWebhook(string $rawBody, string $sigHeader, string $secret): bool {
    $parts = [];
    foreach (explode(",", $sigHeader) as $pair) {
        [$k, $v] = explode("=", $pair, 2);
        $parts[$k] = $v;
    }
    $expected = hash_hmac("sha256", $parts["t"] . "." . $rawBody, $secret);
    return hash_equals($expected, $parts["v1"]);
}

static bool VerifyWebhook(string rawBody, string sigHeader, string secret) {
    var parts = sigHeader.Split(',')
        .ToDictionary(p => p.Split('=', 2)[0], p => p.Split('=', 2)[1]);
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(
        hmac.ComputeHash(Encoding.UTF8.GetBytes($"{parts["t"]}.{rawBody}"))
    ).ToLower();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(parts["v1"])
    );
}

func verifyWebhook(rawBody, sigHeader, secret string) bool {
    parts := make(map[string]string)
    for _, p := range strings.Split(sigHeader, ",") {
        kv := strings.SplitN(p, "=", 2)
        parts[kv[0]] = kv[1]
    }
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(parts["t"] + "." + rawBody))
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(parts["v1"]))
}

def verify_webhook(raw_body, sig_header, secret)
  parts = sig_header.split(",").to_h { |p| p.split("=", 2) }
  expected = OpenSSL::HMAC.hexdigest("sha256", secret, "#{parts['t']}.#{raw_body}")
  Rack::Utils.secure_compare(expected, parts["v1"])
end

static boolean verifyWebhook(String rawBody, String sigHeader, String secret)
        throws Exception {
    Map<String, String> parts = new HashMap<>();
    for (String p : sigHeader.split(",")) {
        String[] kv = p.split("=", 2);
        parts.put(kv[0], kv[1]);
    }
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
    String expected = HexFormat.of().formatHex(
        mac.doFinal((parts.get("t") + "." + rawBody).getBytes())
    );
    return MessageDigest.isEqual(expected.getBytes(), parts.get("v1").getBytes());
}

Logs de entrega

Auditoria somente-leitura das entregas dos eventos checkout.*, deposit.* e withdraw.* às callback URLs desta conta — o que foi entregue, retentado ou falhou. A listagem retorna as 50 tentativas mais recentes (da mais nova para a mais antiga) sem os corpos; busque um log pelo id para ver os payloads de requisição e resposta. Um log de outra conta responde 404: a posse nunca é revelada.

curl https://api.depixapp.com/api/webhook-logs \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "logs": [
    {
      "id":           "wlog_1",
      "checkout_id":  "chk_abc123",
      "event":        "checkout.completed",
      "url":          "https://store.example.com/hook",
      "status_code":  200,
      "error":        null,
      "attempt":      1,
      "sent_at":      "2026-07-22T12:00:00.000Z"
    },
    {
      "id":           "wlog_2",
      "checkout_id":  null,               // eventos deposit.*/withdraw.* não têm checkout
      "event":        "deposit.depix_sent",
      "url":          "https://store.example.com/hook",
      "status_code":  null,               // null = nem chegou a haver resposta HTTP
      "error":        "fetch timeout",
      "attempt":      2,
      "sent_at":      "2026-07-22T11:58:00.000Z"
    }
  ]
}

{
  "log": {
    "id": "wlog_1", "checkout_id": null, "merchant_id": "mrc_1",
    "event": "deposit.depix_sent", "url": "https://store.example.com/hook", "status_code": 200,
    "request_body":  "{...}",   // o payload assinado enviado (X-DePix-Signature cobre estes bytes)
    "response_body": "{...}",   // o que o receptor respondeu
    "error": null, "attempt": 1, "next_retry_at": null, "sent_at": "2026-07-22T12:00:00.000Z"
  }
}

insufficient_scope  403   a chave não tem merchant_read
merchant_required   403   a conta não tem perfil de lojista
not_found           404   log não existe ou pertence a outra conta (só no detalhe)

Sandbox

Use chaves do tipo sk_test_... para testar sem movimentar dinheiro real. Checkouts criados com chave test nunca geram Pix real e ficam isolados dos checkouts de produção.

Diferenças do modo test

• O campo is_live marca o modo: false nas respostas de criação e no GET /api/me, 0 nas consultas de checkouts e produtos.
• O QR code gerado não é um Pix válido — não pode ser pago num app de banco.
• Use o endpoint /simulate-payment para marcar o checkout como pago.
• Webhooks são enviados normalmente — ótimo para testar sua integração de ponta a ponta.

Depósito e saque em modo test

• POST /api/deposit e POST /api/withdraw com sk_test_ respondem com payloads sintéticos marcados "sandbox": true: strings SANDBOX-…-DO-NOT-PAY impagáveis, ids sandbox_*, e no saque a mesma conta de taxa do live, com os mesmos campos.
• Zero dinheiro e zero registro: nenhuma chamada ao provedor Pix, nenhuma linha gravada — os contadores econômicos da conta não são afetados.
• Validações e limites reais são exercitados: os gates da conta e o limite por transação da chave rodam normalmente. O limite diário não acumula (nada é gravado).
• GET /api/deposits/:id e GET /api/withdrawals/:id com id sandbox_* devolvem um status sintético fixo (depix_sent / confirmed) para treinar o loop de polling.
• Sem registros → operações sandbox nunca disparam webhooks deposit.*/withdraw.*. Para testar webhooks de ponta a ponta, use checkout + simulate-payment.
• Chave sk_test_ jamais lê ou escreve dados live: qualquer id que não seja sandbox_* → 404.

Simular pagamento

Marca um checkout de teste como pago. Só funciona com chaves sk_test_. Dispara o webhook checkout.completed normalmente.

# 1. Crie um checkout de teste
curl -X POST https://api.depixapp.com/api/checkouts \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1000, "payer_tax_number": "529.982.247-25", "callback_url": "https://minha-loja.com/webhook" }'

# 2. Simule o pagamento
curl -X POST https://api.depixapp.com/api/checkouts/chk_01jxxxxxxxxxxxxxxxxxxxxxx/simulate-payment \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{ "success": true }

Após a simulação, seu callback_url receberá o evento checkout.completed em alguns segundos — exatamente como num pagamento real.

Verificar chave (GET /api/me)

Retorna as informações do merchant autenticado. Útil para verificar se a API key é válida e consultar dados da conta.

curl https://api.depixapp.com/api/me \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "merchant_id":    "mrc_xxx",
  "name":           "Loja do Joao",
  "username":       "joao",
  "merchant_slug":  "joao",
  "is_live":        true,
  "created_at":     "2025-06-01T00:00:00.000Z"
}

Verificação da conta

Diz se esta conta já pode usar as ferramentas de lojista (checkouts e produtos) e, se não pode, exatamente o que falta. O GET lê o estado; o POST avalia a prova e, quando tudo está satisfeito, destrava as ferramentas. Faça polling do GET enquanto a pessoa cumpre os passos e então chame o POST.

Campos da resposta

curl https://api.depixapp.com/api/verification \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "verified":          false,
  "verified_at":       null,
  "whatsapp_verified": 1,
  "method":            "round_trip",
  "enabled":           true,
  "eligible":          false,
  "requirements": { "deposit_cents": 9500, "withdraw_cents": 8500, "min_account_age_days": 0, "max_days_between_legs": 30, "domain_proof": false },
  "missing":  ["withdraw_leg"],
  "unlocks":  ["checkouts", "products"],
  "steps": [
    { "id": "deposit",      "state": "done",    "target_cents": 9500, "remaining_cents": 0 },
    { "id": "convert_lbtc", "state": "unknown", "target_cents": 500,  "remaining_cents": null },
    { "id": "withdraw",     "state": "pending", "target_cents": 8500, "remaining_cents": 8500 }
  ]
}

account_blocked                    403   conta suspensa
verification_tax_number_in_use     409   esse CPF/CNPJ já verificou outra conta — um documento verifica uma conta só
(demais 409)                       409   o que falta vem em error.details.missing / error.details.remaining

Editar perfil da loja (PATCH /api/merchants/me)

Atualiza parcialmente o perfil da loja autenticada. Envie apenas os campos que deseja alterar. Aceita tanto o JWT do dashboard quanto uma API key com scope merchant_write.

Parâmetros (todos opcionais — envie só o que muda)

curl -X PATCH https://api.depixapp.com/api/merchants/me \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "default_redirect_url": "https://loja.exemplo.com/obrigado" }'

{
  "success":        true,
  "merchant_slug":  "loja-do-joao"       // muda apenas se business_name mudou
}

{
  "response": { "errorMessage": "Este campo só pode ser alterado pelo dono da conta no painel web." },
  "error": {
    "code":        "validation_error",
    "message":     "This field can only be changed by the account owner in the web dashboard.",
    "request_id":  "gru1::abcd-1234",
    "docs_url":    "https://depixapp.com/docs/en/#errors",
    "details":     { "field": "liquid_address" }
  }
}

Audit log da chave

Toda operação de escrita feita com uma API key é auditada: ação, valor, recurso, request_id, IP, flag de sandbox e replays idempotentes — inclusive negações autenticadas (ex.: insufficient_scope, account_blocked, com a ação sufixada *.denied:<code>). O dono consulta o histórico de cada chave com o endpoint abaixo. Retenção: 90 dias. GETs e respostas 429 não são logados.

Query params (todos opcionais)

curl "https://api.depixapp.com/api/api-keys/a1b2c3d4e5f6/audit?limit=50&offset=0" \
  -H "Authorization: Bearer <jwt-do-dashboard>"

{
  "audit": [
    {
      "id":           "aud_01jxxxxxxxxxxxxxxxxxxxxxx",
      "action":       "withdraw.create",
      "method":       "POST",
      "path":         "/api/withdraw",
      "status_code":  200,
      "amount_cents": 10000,
      "resource_id":  "wd-123",
      "is_sandbox":   0,
      "is_replay":    0,       // 1 = replay idempotente (handler não rodou)
      "ip":           "203.0.113.9",
      "request_id":   "gru1::iad1::v9x4k-1751476800000-abc123",
      "created_at":   "2026-07-02T14:03:11.000Z"
    }
  ],
  "total": 123
}

Rate limits

A API aplica limites de requisições para garantir estabilidade e proteger contra abusos.

• Para requests autenticados com API key, um rate limit adicional é aplicado por merchant (padrão 30 req/min, compartilhado entre todos os endpoints — fale com o suporte se precisar de aumento) e, quando definido na criação, por chave (rate_limit_per_min).
• As escritas autenticadas alcançáveis por API key — criar/simular checkout e o CRUD de produtos — têm limite por-endpoint (60/min por IP · 30/min por chave), listado na tabela acima. As leituras do lado "receber" (listar checkouts e produtos, GET /api/me, etc.) não têm limite por-endpoint próprio — são cobertas pelo orçamento por merchant (padrão 30 req/min, configurável). O caminho JWT/SPA também é limitado, não só o de API key.
• Nas rotas de deposit/withdraw, o contador por usuário vale por chave — cada API key tem budget próprio, sem competir com o dono na SPA.
• Para endpoints públicos (sem auth), o rate limit é aplicado apenas por IP.
• Quando o limite é atingido, a API retorna 429 com error.code = "rate_limited" (ou "merchant_rate_limited"), o campo error.retry_after e o header Retry-After — aguarde os segundos indicados antes de tentar de novo.
• Em rotas wallet_* autenticadas por API key, falha de infraestrutura no check de rate limit responde 503 service_unavailable com retry_after (fail-closed) em vez de deixar o request passar.
• Velocidade por pagador: no máximo 2 QRs por CPF/CNPJ do pagador em uma janela deslizante de 30 minutos (depósitos e checkouts contam juntos). A partir do 3º, a API retorna 429 com error.code = "payer_velocity_limit", details: { window_minutes, max_per_window } e o header Retry-After indicando os segundos até liberar.

Abrir um ticket

Abre um ticket de suporte. Os endpoints /api/tickets funcionam tanto para usuários humanos (o JWT do dashboard) quanto para agentes de IA (uma chave sk_live_/sk_test_) — nenhum escopo é exigido. Uma requisição assinada com sk_ se comporta exatamente como a com JWT. Cada sessão ou chave só enxerga os tickets que ela mesma criou; os tickets de outro principal são invisíveis.

Parâmetros

Campos do ticket

curl -X POST https://api.depixapp.com/api/tickets \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Saque preso como pendente",
    "category": "payment",
    "body": "O saque wtd_123 está pendente há 2 horas."
  }'

{
  "ticket": {
    "id": "tkt_ab12cd34ef",
    "opener_type": "human",
    "status": "awaiting_reply",
    "subject": "Saque preso como pendente",
    "category": "payment",
    "created_at": "2026-07-22T12:00:00.000Z",
    "last_activity_at": "2026-07-22T12:00:00.000Z",
    "closed_reason": null,
    "closed_at": null
  }
}

validation_error   400   campo inválido (details.field; irmão legado response.errors[])
ticket_open_cap    429   tickets abertos demais (details.max_open)
unauthorized       401   credencial ausente / inválida

O limite é de 5 tickets abertos simultaneamente (1 para contas suspensas); error.details.max_open traz o teto. Erros de validação também expõem o irmão legado response.errors[] ao lado de error.details.field.

Listar seus tickets

Lista os tickets criados pelo principal que faz a chamada (esta sessão JWT ou esta API key), da atividade mais recente para a mais antiga. Paginado.

Parâmetros de query

curl "https://api.depixapp.com/api/tickets?limit=50&offset=0" \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "tickets": [
    {
      "id": "tkt_ab12cd34ef",
      "opener_type": "human",
      "status": "awaiting_reply",
      "subject": "Saque preso como pendente",
      "category": "payment",
      "created_at": "2026-07-22T12:00:00.000Z",
      "last_activity_at": "2026-07-22T12:00:00.000Z",
      "closed_reason": null,
      "closed_at": null
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Detalhe do ticket & mensagens

Retorna um ticket com toda a thread de mensagens, da mais antiga para a mais recente. Fazer polling deste endpoint é como você (ou um agente) lê uma resposta do suporte.

curl https://api.depixapp.com/api/tickets/tkt_ab12cd34ef \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "ticket": {
    "id": "tkt_ab12cd34ef",
    "opener_type": "human",
    "status": "answered",
    "subject": "Saque preso como pendente",
    "category": "payment",
    "created_at": "2026-07-22T12:00:00.000Z",
    "last_activity_at": "2026-07-22T13:15:00.000Z",
    "closed_reason": null,
    "closed_at": null
  },
  "messages": [
    { "id": "tmsg_1", "sender": "user",  "body": "O saque wtd_123 está pendente há 2 horas.", "created_at": "2026-07-22T12:00:00.000Z" },
    { "id": "tmsg_2", "sender": "admin", "body": "Acabou de liquidar — pode confirmar?", "created_at": "2026-07-22T13:15:00.000Z" }
  ]
}

O sender de uma mensagem é um de user, admin ou system.

not_found   404   ticket inexistente — ou pertence a outro principal

Um ticket que não é seu retorna o mesmo 404 not_found de um inexistente — a posse nunca é revelada.

Responder

Anexa uma mensagem do usuário à thread. Responder um ticket answered o traz de volta para awaiting_reply. Responder um ticket fechado automaticamente em até 7 dias o reabre. Tickets fechados por um usuário ou por um admin são terminais — uma resposta ali falha com 409 ticket_closed.

Parâmetros

curl -X POST https://api.depixapp.com/api/tickets/tkt_ab12cd34ef/messages \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Confirmado, os fundos chegaram. Obrigado!" }'

{
  "message": { "id": "tmsg_3", "sender": "user", "body": "Confirmado, os fundos chegaram. Obrigado!", "created_at": "2026-07-22T13:20:00.000Z" },
  "ticket": {
    "id": "tkt_ab12cd34ef",
    "opener_type": "human",
    "status": "awaiting_reply",
    "subject": "Saque preso como pendente",
    "category": "payment",
    "created_at": "2026-07-22T12:00:00.000Z",
    "last_activity_at": "2026-07-22T13:20:00.000Z",
    "closed_reason": null,
    "closed_at": null
  }
}

validation_error   400   body inválido (details.field)
not_found          404   ticket inexistente (ou não é seu)
ticket_closed      409   ticket fechado por um usuário ou admin (terminal)

Anexar arquivo

Envia um arquivo (imagem, PDF, log ou JSON) para a equipe de suporte — ideal para um print de tela ou um arquivo de diagnóstico ao relatar um bug. Os bytes vão em file_b64 (base64, sem o prefixo data:), até ~3 MB. O arquivo é encaminhado ao suporte, não é armazenado nem servido de volta — a resposta registra apenas o nome e o tipo. Anexar conta como uma resposta: um ticket answered volta para awaiting_reply e um ticket fechado automaticamente em até 7 dias reabre.

Parâmetros

curl -X POST https://api.depixapp.com/api/tickets/tkt_ab12cd34ef/attachments \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "erro-checkout.png", "content_type": "image/png", "file_b64": "iVBORw0KGgo…" }'

{
  "message": {
    "id": "tmsg_5",
    "sender": "user",
    "body": "erro-checkout.png",
    "created_at": "2026-07-22T14:05:00.000Z",
    "attachment": { "name": "erro-checkout.png", "mime": "image/png" }
  },
  "ticket": {
    "id": "tkt_ab12cd34ef",
    "opener_type": "human",
    "status": "awaiting_reply",
    "subject": "Saque preso como pendente",
    "category": "payment",
    "created_at": "2026-07-22T12:00:00.000Z",
    "last_activity_at": "2026-07-22T14:05:00.000Z",
    "closed_reason": null,
    "closed_at": null
  }
}

validation_error        400   content_type/file_b64 inválido (details.field)
attachment_too_large    413   arquivo acima de ~3 MB
not_found               404   ticket inexistente (ou não é seu)
ticket_closed           409   ticket fechado por um usuário ou admin (terminal)
attachment_unavailable  503   sem canal de suporte agora — tente de novo ou use texto

Fechar um ticket

Fecha o ticket você mesmo, definindo closed_reason como user. Um ticket fechado pelo usuário é terminal — para continuar a conversa você abre um novo ticket.

curl -X POST https://api.depixapp.com/api/tickets/tkt_ab12cd34ef/close \
  -H "Authorization: Bearer $DEPIX_API_KEY"

{
  "ticket": {
    "id": "tkt_ab12cd34ef",
    "opener_type": "human",
    "status": "closed",
    "subject": "Saque preso como pendente",
    "category": "payment",
    "created_at": "2026-07-22T12:00:00.000Z",
    "last_activity_at": "2026-07-22T13:25:00.000Z",
    "closed_reason": "user",
    "closed_at": "2026-07-22T13:25:00.000Z",
    "rating": null,
    "rated_at": null
  }
}

not_found       404   ticket inexistente (ou não é seu)
ticket_closed   409   já fechado

Avaliar o atendimento

Dá uma nota de 0 a 10 ao atendimento de um ticket já encerrado (0 = pior, 10 = melhor). A avaliação é única: a segunda chamada devolve 409 already_rated, então a primeira nota nunca é sobrescrita em silêncio.

Avaliar apenas registra o dado — não reabre o ticket, não conta como mensagem e não altera last_activity_at.

curl -X POST https://api.depixapp.com/api/tickets/tkt_ab12cd34ef/rating \
  -H "Authorization: Bearer $DEPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": 10}'

{
  "ticket": {
    "id": "tkt_ab12cd34ef",
    "opener_type": "human",
    "status": "closed",
    "subject": "Saque preso como pendente",
    "category": "payment",
    "created_at": "2026-07-22T12:00:00.000Z",
    "last_activity_at": "2026-07-22T13:25:00.000Z",
    "closed_reason": "admin",
    "closed_at": "2026-07-22T13:25:00.000Z",
    "rating": 10,
    "rated_at": "2026-07-22T13:31:00.000Z"
  }
}

validation_error  400   nota ausente, fora de 0–10 ou não inteira
not_found         404   ticket inexistente (ou não é seu)
ticket_open       409   o ticket ainda está aberto
already_rated     409   este ticket já foi avaliado

Contas de agente

Uma conta de agente é um merchant que um agente de IA cria e opera sozinho — sem e-mail, WhatsApp ou captcha. É provisionada e operada inteiramente pelos endpoints /api/agents/* abaixo. A maioria dos agentes os acessa pelo SDK DePix (a classe DepixAgent), que assina cada requisição por você.

Autenticação por requisição assinada

Os endpoints de agente não usam uma API key estática. Cada requisição é assinada com a chave Ed25519 da conta (gerada e guardada localmente pelo agente). Envie estes headers em cada chamada:

depix-agent-auth:v1
api.depixapp.com
<METHOD>
<path-without-query>
<timestamp>
<nonce>
<sha256hex(raw-request-body)>

Onboarding e graduação

Um agente novo começa com uma chave sandbox sk_test_ e uma chave sk_live_ starter (só wallet), limitada a R$100/tx e R$500/dia. A conta gradua — e passa a emitir chaves sk_live_ completas — quando fica verificada. Para um agente, verificar a conta é provar um domínio por DNS: é o mesmo domínio que libera receber de terceiros (checkouts, escopos merchant_*), então uma coisa destrava a outra.

O atraso de 24h (inter_deposit_delay_hours) aplicado aos depósitos 2–5 segura a liquidação (a entrega do DePix) daqueles depósitos — ele não bloqueia criar o próximo depósito, que pode ser criado em seguida.

A posição do depósito é contada por conta, não por canal: um checkout Pix conta igual a um QR pessoal. As 24h valem para depósitos de até R$ 100 — acima disso vale a espera do nível da conta, que é maior. O 1º depósito de até R$ 100 liquida na hora; do 6º em diante valem o teto de recebimento e a faixa instantânea. Um checkout pago pelo trilho DePix (Liquid) fica fora de todas essas regras, por não passar pelo trilho Pix.

agent_invalid_signature   401   assinatura não confere
agent_signature_expired   401   timestamp fora de ±300s
agent_replay_detected     401   nonce já usado
agent_unknown_key         401   chave não registrada (rotas autenticadas)
account_suspended         403   conta pausada (rotas mutantes)
agents_disabled           503   kill-switch de onboarding de agente ligado

Registrar um agente

Cria uma conta de agente — um merchant, um endereço Liquid de recebimento e as chaves starter. Exige um operator token (op_…) que um humano obtém conectando uma identidade (GitHub/Google) em https://api.depixapp.com/api/agents/oauth/start — a âncora anti-abuso. O token não é show-once: a mesma página mostra o mesmo token a cada login, então perdê-lo não custa nada — basta entrar de novo.

Parâmetros

curl -X POST https://api.depixapp.com/api/agents/register \
  -H "x-agent-public-key: <64hex>" \
  -H "x-agent-signature: <128hex>" \
  -H "x-agent-nonce: <unique>" -H "x-agent-timestamp: <unix>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "operator_token": "op_...",
    "operator_email": "me@example.com",
    "liquid_address": "lq1..."
  }'

{
  "response": {
    "agent":    { "username": "agent_9f3c2a1b0d", "public_key": "<64hex>", "account_type": "agent" },
    "merchant": { "id": "mrc_...", "merchant_slug": "agent_9f3c2a1b0d", "liquid_address": "lq1...", "webhook_secret": "whsec_..." },
    "keys": {
      "test":         { "id": "...", "key": "sk_test_...", "scopes": "merchant_read merchant_write wallet_read wallet_write" },
      "live_starter": { "id": "...", "key": "sk_live_...", "scopes": "wallet_read wallet_write", "per_tx_limit_cents": 10000, "daily_limit_cents": 50000, "starter": true }
    },
    "graduation": {
      "requires": "domain_proof",                                  // o que falta: provar um domínio
      "verify_domain_endpoint": "POST /api/agents/verify-domain",  // onde provar
      "allowed_tlds_endpoint": "GET /api/agents/domain-tlds"       // TLDs aceitos — consulte antes
    },
    "pacing": {
      "first_deposit_max_cents": 10000,
      "unverified_per_tx_max_cents": 10000,
      "inter_deposit_delay_hours": 24,   // atrasa a liquidação dos depósitos 2–5 — não bloqueia criar o próximo
      "payer_velocity": { "max_per_window": 2, "window_minutes": 30 },
      "verified_per_tx_deposit_max_cents": 600000,
      "verified_per_tx_withdraw_send_max_cents": 600000,     // teto de depositAmountInCents — quanto você envia
      "verified_per_tx_withdraw_receive_max_cents": 600000  // teto de payoutAmountInCents — quanto cai na conta, já sem as taxas
    }
  }
}

As chaves em texto plano e o webhook_secret são devolvidos uma única vez.

validation_error               400   campo inválido (details.field)
invalid_operator_token         401   operator token inválido
operator_token_revoked         403
agent_pubkey_exists            409   essa chave já tem uma conta
username_taken                 409
operator_register_cap_exceeded 429   teto do operador (details.window_hours) — aguarde retry_after
agents_disabled                503

O 429 é o teto anti-fazenda do próprio operator token: um op_ só abre um punhado de contas-agente dentro de uma janela deslizante. details.max_per_window e details.window_hours trazem o formato exato, e retry_after os segundos até liberar uma vaga. Bater nele sem ter aberto essas contas significa que o token vazou — peça ao operador para revogá-lo. Os dois tetos do registro, este e o por IP, falham fechados: quando a infraestrutura que faz a contagem está indisponível, o endpoint responde 503 em vez de deixar o registro passar.

Criar uma chave

Emite uma nova API key para a conta do agente. Chaves live exigem graduação; escopos merchant_* exigem um domínio verificado.

Parâmetros

{
  "response": {
    "id": "...", "key": "sk_live_...", "prefix": "sk_live_",
    "is_live": true, "scopes": "wallet_read wallet_write",
    "per_tx_limit_cents": 10000, "daily_limit_cents": 50000
  }
}

O key em texto plano é devolvido uma vez. Máximo de 5 chaves ativas por tipo (live / test).

validation_error   400   scopes / label / limites inválidos, ou limite de 5 chaves
graduation_pending 403   live:true antes da graduação
domain_required    403   escopo merchant_* sem domínio verificado

Revogar uma chave

Revoga uma das chaves da conta. Idempotente — revogar uma chave já revogada ainda retorna sucesso.

Parâmetros

{ "response": { "id": "...", "revoked": true } }

not_found (404) quando a chave não pertence ao merchant deste agente.

Status da conta

Lê o estado da conta e o progresso de graduação. Continua disponível mesmo com a conta suspensa, para o agente conseguir ler o motivo.

Assimetria importante: a suspensão da sua conta mantém esta leitura disponível (200, com o campo reason). Já o kill-switch global do programa de agentes responde 503 agents_disabled até para esta leitura — trate 503 agents_disabled como pausa da plataforma inteira, não como suspensão da sua conta.

{
  "response": {
    "account_status": "active",          // active | suspended
    "graduated": false,
    "graduation": { "blocked_on": "domain_proof" },  // "domain_proof": prove um domínio (é com você)
                                                     // "gate_review": verificado, graduação ainda não caiu — poll
                                                     // null: já graduou
    "keys": [
      { "id": "...", "prefix": "sk_test_", "is_live": false, "starter": false, "scopes": "...", "revoked_at": null }
    ]
    // "reason": "..."  — presente só quando suspensa
  }
}

Logs de entrega de webhook

Auditoria somente-leitura das entregas dos eventos checkout.*, deposit.* e withdraw.* às callback URLs desta conta — o que foi entregue, retentado ou falhou. A listagem retorna as 50 tentativas mais recentes (da mais nova para a mais antiga) sem os corpos; busque um log pelo id para ver os payloads de requisição/resposta. Um log de outra conta responde 404.

curl https://api.depixapp.com/api/agents/webhook-logs \
  -H "x-agent-public-key: <64hex>" \
  -H "x-agent-signature: <128hex>" \
  -H "x-agent-nonce: <unique>" -H "x-agent-timestamp: <unix>"

{
  "logs": [
    { "id": "...", "checkout_id": null, "event": "deposit.depix_sent", "url": "https://...", "status_code": 200, "error": null, "attempt": 1, "sent_at": "..." }
  ]
}

{
  "log": {
    "id": "...", "event": "checkout.completed", "url": "https://...", "status_code": 200,
    "request_body": "{...}",   // o payload assinado enviado (X-DePix-Signature cobre estes bytes)
    "response_body": "{...}",  // o que o receptor respondeu
    "error": null, "attempt": 1, "next_retry_at": null, "sent_at": "..."
  }
}

merchant_required  403   sem perfil de lojista ATIVO (ex.: conta suspensa)
not_found          404   log não existe ou pertence a outra conta

Verificar um domínio

Prova por DNS TXT em duas fases. Libera o recebimento de terceiros (checkouts / escopos merchant_*). O domínio é normalizado para sua raiz registrável (ex.: shop.acme.com.br → acme.com.br).

Parâmetros

{
  "record_name":  "_depix-verify.acme.com.br",
  "record_value": "depix-verify=<token 32-hex>"
}

{ "verified_domain": "acme.com.br", "verified": true }  // verified: a conta ficou verificada — a graduação vem em seguida

validation_error      400   details.field: "domain"
domain_tld_not_allowed 422   details.allowed_tlds: [...]
domain_free_host      422   vercel.app / netlify.app / github.io / ... negados
domain_txt_not_found  422   TXT ausente/divergente — tente após propagar o DNS

Allowlist de TLDs

Público. Retorna os sufixos de TLD aceitos pela verificação de domínio.

curl https://api.depixapp.com/api/agents/domain-tlds

{ "allowed_tlds": [".com", ".net", ".org", ".io", ".ai", ".dev", ".app", ".com.br", ".br", ".store", ".shop", "..."] }

Ligar o trilho DePix

Registra (ou remove) o endereço Liquid confidencial dedicado em que o merchant do agente é pago pelo trilho DePix — assim os checkouts dele passam a ser pagos em DePix on-chain, e não só por Pix. A porta gêmea humana (POST /api/merchants/me/depix-pay) é protegida por senha; um agente não tem senha nem navegador, então prova a intenção com a assinatura do par de chaves, nunca uma Bearer key.

Ligar exige o endereço e a chave de visão (a blinding key privada): a chave é a prova de posse — o endereço é reconstruído a partir dela e precisa bater — e é a única coisa que nos deixa ler os valores que chegam ali. Ela é selada em repouso e nunca é devolvida. O endereço precisa ser confidencial (lq1…) e exclusivo: os endereços de payout e de split são recusados. Desligar não pede chave nenhuma. Exige uma conta verificada (para um agente, o domínio provado) e recusa um merchant suspenso.

Parâmetros

curl -X POST https://api.depixapp.com/api/agents/depix-pay \
  -H "x-agent-public-key: <64hex>" \
  -H "x-agent-signature: <128hex>" \
  -H "x-agent-nonce: <unique>" -H "x-agent-timestamp: <unix>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "address": "lq1qq...",
    "blinding_key": "<64hex>",
    "derivation_index": 12
  }'

curl -X POST https://api.depixapp.com/api/agents/depix-pay \
  -H "x-agent-public-key: <64hex>" \
  -H "x-agent-signature: <128hex>" \
  -H "x-agent-nonce: <unique>" -H "x-agent-timestamp: <unix>" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

{
  "response": {
    "depix_pay_enabled": true,
    "depix_pay_address": "lq1qq...",   // o endereço registrado (em minúsculas)
    "depix_derivation_index": 12,   // o índice enviado, ecoado; null se nenhum
    "depix_discount_pct": 0        // desconto atual do trilho; esta chamada não mexe nele
  }
}

{
  "response": {
    "depix_pay_enabled": false,
    "view_key_deleted": true,     // ao menos uma chave de visão foi apagada
    "pending_addresses": 0       // endereços que mantiveram a chave por um checkout DePix ainda aberto
  }
}

validation_error          400   corpo malformado (details.field) — ex.: enabled ausente
depix_address_unsupported 400   endereço não confidencial (não lq1…) ou indecodificável
depix_address_conflict    400   endereço não exclusivo (payout/split) ou já registrado
invalid_blinding_key      400   a chave de visão não corresponde ao endereço
agent_unknown_key         401   assinatura falhou ou chave não registrada
verification_required     403   conta não verificada — para um agente, prove um domínio
account_suspended         403   merchant suspenso (account_blocked se bloqueado)
service_unavailable       503   trilho indisponível (KEK ausente / anti-replay fora do ar)
agents_disabled           503   programa de agentes desligado globalmente