Trust7Docs
Documentação oficialv1.3.0

Integre pagamentos
sem adivinhação.

Um guia direto e completo para criar cobranças Pix, acompanhar pagamentos e processar webhooks com segurança.

Base URL de produçãohttps://trust7.dev/v1

Integração previsível

JSON, valores em centavos, erros estruturados e idempotência obrigatória.

Atualização em tempo real

Webhooks assinados, entrega at-least-once e regras claras de retentativa.

Pronta para IA

llms.txt e OpenAPI públicos para dar contexto exato a qualquer agente.

Começando

Pré-requisitos

Antes de escrever código, confirme estes quatro pontos. Eles evitam a maioria das falhas de primeira integração.

  1. 1
    Cadastro aprovado

    A conta do seller precisa estar aprovada para emitir uma chave de API e operar pagamentos.

  2. 2
    Chave criada no dashboard

    Abra Integração → Chaves de API. Copie a chave completa na criação; o segredo não pode ser consultado depois.

  3. 3
    Chamadas somente pelo backend

    Nunca exponha a chave em navegador, aplicativo distribuído, repositório ou ferramenta de analytics.

  4. 4
    Método habilitado

    Consulte GET /payment-methods. Só crie Pix quando method=pix e enabled=true.

Primeira integração

Pix em quatro passos

O fluxo mínimo seguro é: validar disponibilidade, criar uma cobrança, exibir o código Pix e aguardar a confirmação por webhook.

1. Verifique o método

cURL
curl --request GET \
  --url https://trust7.dev/v1/payment-methods \
  --header 'Authorization: Bearer SUA_CHAVE_SECRETA' \
  --header 'Accept: application/json'

2. Crie uma cobrança

cURL
curl --request POST \
  --url https://trust7.dev/v1/payments \
  --header 'Authorization: Bearer SUA_CHAVE_SECRETA' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-789-pix-1' \
  --data '{
    "amount": 2590,
    "currency": "BRL",
    "payment_method": {
      "type": "pix",
      "expires_in_seconds": 1800
    },
    "customer": {
      "reference": "cliente-123",
      "name": "Ana Silva",
      "email": "cliente@example.com",
      "phone": "+5511999999999"
    },
    "metadata": {
      "order_id": "pedido-789"
    }
  }'

3. Use a resposta

A criação Pix responde 202 Accepted. Salve id e sequence; mostre next_action.qr_code como Pix Copia e Cola ou gere a imagem do QR Code no frontend.

Resposta 202
{
  "id": "pay_01J8ZQ5MB2",
  "status": "pending_action",
  "amount": 2590,
  "amount_captured": 0,
  "amount_refunded": 0,
  "currency": "BRL",
  "capture_method": "automatic",
  "payment_method": { "type": "pix" },
  "next_action": {
    "type": "pix_qr_code",
    "qr_code": "000201...",
    "expires_at": "2026-08-13T00:30:00Z"
  },
  "metadata": { "order_id": "pedido-789" },
  "sequence": 1,
  "created_at": "2026-08-13T00:00:00Z",
  "updated_at": "2026-08-13T00:00:00Z"
}

4. Confirme pelo webhook

Marque o pedido como pago somente ao receber payment.captured com assinatura válida, ou após confirmar o mesmo estado em GET /payments/{id}.

Fundamentos

Autenticação

Todas as chamadas técnicas usam uma chave secreta no header Authorization.

Header obrigatório
Authorization: Bearer key_xxxxx.sk_xxxxx

Criação

No dashboard do seller, abra Integração, informe um nome que identifique o sistema e clique em Criar chave.

Armazenamento

Guarde em secret manager ou variável de ambiente do servidor. O valor completo aparece uma única vez.

Rotação

Ao rotacionar, a chave anterior permanece válida por 24 horas. Migre o sistema e depois remova o segredo antigo.

Revogação

Revogar é imediato. Faça isso quando uma integração for desativada ou houver suspeita de vazamento.

Fundamentos

Convenções da API

Protocolo
HTTPS com JSON UTF-8
Base URL
https://trust7.dev/v1
Dinheiro
Inteiro na menor unidade: 2590 = R$ 25,90
Moeda
ISO-4217 em maiúsculas, atualmente BRL
Datas
ISO 8601 em UTC, exemplo 2026-08-13T00:00:00Z
IDs
Strings opacas; não extraia significado nem imponha tamanho
Campos novos
Seu parser deve ignorar propriedades desconhecidas
Segredos
Nunca são devolvidos novamente após a criação

Headers recomendados

HeaderQuandoValor
AuthorizationTodas as chamadasBearer SUA_CHAVE
Content-TypeCorpo JSONapplication/json
AcceptRecomendadoapplication/json
Idempotency-KeyPOST financeiroID único da operação lógica
Segurança operacional

Idempotência

Todo POST que cria ou move dinheiro exige Idempotency-Key, com 8 a 255 caracteres. A chave representa uma operação lógica — por exemplo, “criar o Pix do pedido 789”.

Primeira chamadaProcessa e armazena a resposta
Retry igualDevolve a resposta original
Mesmo ID, corpo diferenteHTTP 409
Pagamentos

Cobrança Pix

Crie o pagamento no seu backend. O exemplo abaixo está pronto para uso e trata erros antes de devolver os dados necessários ao frontend.

Node.js 18+
import crypto from "node:crypto";

export async function criarPix({ orderId, amount, customer }) {
  const response = await fetch("https://trust7.dev/v1/payments", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.TRUST7_API_KEY}`,
      "Content-Type": "application/json",
      "Accept": "application/json",
      "Idempotency-Key": `order-${orderId}-pix-v1`
    },
    body: JSON.stringify({
      amount,
      currency: "BRL",
      payment_method: { type: "pix", expires_in_seconds: 1800 },
      customer,
      metadata: { order_id: String(orderId) }
    }),
    signal: AbortSignal.timeout(10_000)
  });

  const payload = await response.json();
  if (!response.ok) {
    const error = new Error(payload.error?.message ?? "Trust7 request failed");
    error.status = response.status;
    error.code = payload.error?.code;
    throw error;
  }
  return {
    paymentId: payload.id,
    status: payload.status,
    copyPaste: payload.next_action?.qr_code,
    expiresAt: payload.next_action?.expires_at
  };
}

Campos do pedido

CampoObrigatórioDescrição
amountSimValor inteiro em centavos, maior que zero.
currencySimBRL.
payment_method.typeSimUse exatamente pix.
expires_in_secondsNãoDe 60 a 86.400; padrão de 3.600 segundos.
customer.referenceNãoID estável do cliente no seu sistema.
customer.nameNãoNome do pagador; aparece na lista e na exportação de clientes.
customer.emailNãoE-mail válido do pagador.
customer.phoneNãoTelefone com DDI e DDD; aparece na exportação de clientes.
metadataNãoChaves e valores string para conciliação; não armazene segredos.
Pagamentos

Consulta e status

Consultar por ID
curl https://trust7.dev/v1/payments/pay_01J8ZQ5MB2 \
  --header 'Authorization: Bearer SUA_CHAVE_SECRETA'
StatusÉ final?Ação recomendada
pending_actionNãoExiba o Pix e aguarde webhook.
capturedSimConfirme o pedido como pago.
expiredSimOfereça a criação de uma nova cobrança.
canceledSimNão entregue o pedido.
failedSimInforme falha sem expor detalhes internos.
refundedSimRegistre o reembolso integral.
partially_refundedNãoConcilie amount_refunded.
blocked_medNãoBloqueie disponibilidade do valor e acompanhe os eventos MED.
Webhooks

Atualizações em tempo real

A Trust7 envia um POST quando o estado de um pagamento muda. A entrega é at-least-once: o mesmo evento pode chegar mais de uma vez, e eventos diferentes podem chegar fora de ordem.

Trust7 muda o pagamento
POST assinado ao seu endpoint
Seu servidor valida e grava
Resposta 2xx rápida

Cadastre um endpoint

POST /webhook-endpoints
curl --request POST \
  --url https://trust7.dev/v1/webhook-endpoints \
  --header 'Authorization: Bearer SUA_CHAVE_SECRETA' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://api.sualoja.com/webhooks/trust7",
    "events": [
      "payment.captured",
      "payment.expired",
      "payment.canceled",
      "payment.failed"
    ]
  }'

A resposta 201 contém secret. Armazene-o imediatamente: nas listagens posteriores o segredo é omitido. Uma lista vazia de eventos ou ["*"] assina todos os eventos.

Envelope do evento

payment.captured
{
  "id": "evt_01J8ZQ7",
  "type": "payment.captured",
  "sequence": 2,
  "created_at": "2026-08-13T00:02:10Z",
  "data": {
    "object": {
      "id": "pay_01J8ZQ5MB2",
      "status": "captured",
      "amount": 2590,
      "amount_captured": 2590,
      "currency": "BRL",
      "metadata": { "order_id": "pedido-789" },
      "sequence": 2
    }
  }
}
Webhooks

Valide antes de confiar

Cada entrega inclui Trust7-Signature no formato t=TIMESTAMP,v1=HEX. O digest é HMAC-SHA256(secret, timestamp + "." + corpo_cru).

Express + Node.js
import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/webhooks/trust7", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.get("Trust7-Signature") ?? "";
  const parts = Object.fromEntries(signature.split(",").map(part => part.split("=", 2)));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return res.sendStatus(400);
  }

  const expected = crypto.createHmac("sha256", process.env.TRUST7_WEBHOOK_SECRET)
    .update(`${timestamp}.`)
    .update(req.body)
    .digest("hex");
  const received = Buffer.from(parts.v1 ?? "", "hex");
  const valid = received.length === expected.length / 2 &&
    crypto.timingSafeEqual(received, Buffer.from(expected, "hex"));
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // 1) insira event.id com UNIQUE; duplicado significa que já foi processado
  // 2) aplique somente sequence maior que a última do mesmo pagamento
  // 3) confirme o pedido apenas em payment.captured
  res.sendStatus(204);
});
  • Recuse timestamps com diferença superior a 5 minutos.
  • Compare o HMAC em tempo constante.
  • Use um segredo diferente por endpoint.
  • Deduplicate pelo event.id em armazenamento persistente.
  • Não siga a URL presente no payload nem confie em IP como autenticação.
Webhooks

Eventos e retentativas

Eventos de pagamento

EventoQuando acontece
payment.pending_actionA cobrança aguarda ação do pagador.
payment.authorizedPagamento autorizado, ainda não capturado.
payment.capturedPagamento confirmado; libere o pedido.
payment.canceledPagamento cancelado antes da conclusão.
payment.expiredPix ou boleto expirou sem pagamento.
payment.failedFalha definitiva.
payment.blocked_medValor Pix capturado foi bloqueado pelo MED.
payment.med_releasedBloqueio MED liberado.
payment.med_debitedDevolução MED debitada em definitivo.

Também existem refund.created, refund.failed, dispute.opened, dispute.won, dispute.lost, payout.paid, payout.failed, payout.returned e seller.status_changed.

Política de entrega

Timeout5 segundos por tentativa
Máximo10 tentativas
IntervaloExponencial + jitter, teto de 30 min
SucessoQualquer HTTP 2xx

A Trust7 repete em falha de rede, timeout, HTTP 408, 429 e 5xx. Outros 4xx encerram a entrega, pois indicam rejeição permanente do payload. Responda 2xx somente depois de validar e persistir o evento; execute trabalho pesado de forma assíncrona.

Referência

Erros e retries

Erros sempre usam um envelope previsível. Registre request_id para suporte, mas não mostre detalhes internos ao comprador.

Envelope de erro
{
  "error": {
    "type": "payment_method_error",
    "code": "payment_method_unavailable",
    "message": "payment method is not available",
    "param": "payment_method.type",
    "request_id": "req_01J8ZR0"
  }
}
HTTPSignificadoRetry?
400Corpo ou parâmetro inválido.Não; corrija a requisição.
401Chave ausente, inválida ou revogada.Não; corrija a credencial.
403Credencial sem escopo ou conta bloqueada.Não automaticamente.
404Recurso não encontrado para esta conta.Não.
409Estado inválido ou conflito de idempotência.Leia error.code.
424Método/adquirente indisponível.Não em loop; consulte disponibilidade.
429Limite de requisições excedido.Sim, respeite Retry-After.
500+Falha temporária da Trust7.Sim, com backoff e mesma idempotência.
Go live

Checklist de produção

Para agentes de código

Dê o contrato, não um print

Uma IA integra melhor quando recebe fontes estruturadas. Forneça os dois links abaixo e o prompt recomendado.

Prompt recomendado
Integre pagamentos Pix da Trust7 neste projeto.

Fontes canônicas:
- https://docs.trust7.dev/llms.txt
- https://docs.trust7.dev/openapi.yaml

Antes de editar:
1. Leia as duas fontes por completo e identifique a arquitetura atual do projeto.
2. Mantenha TRUST7_API_KEY apenas no backend e em variável de ambiente.
3. Consulte GET /payment-methods e trate Pix desabilitado.
4. Use valores inteiros em centavos e Idempotency-Key persistida por pedido.
5. Crie o Pix no backend e devolva ao frontend somente payment_id, qr_code e expires_at.
6. Implemente webhook com corpo cru, HMAC-SHA256, tolerância de 300 s, deduplicação por event.id e fencing por sequence.
7. Confirme pedidos somente em payment.captured.
8. Trate 400, 401, 409, 424, 429 e 5xx conforme a documentação.
9. Adicione testes para sucesso, replay idempotente, assinatura inválida, evento duplicado e evento fora de ordem.
10. Não invente endpoints, campos, status ou capacidades ausentes do OpenAPI.

Ao final, liste arquivos alterados, variáveis de ambiente, testes executados e um roteiro de validação.
Referência

Endpoints principais

MétodoEndpointUso
GET/payment-methodsCapacidades ativas da conta.
POST/paymentsCriar pagamento; exige idempotência.
GET/payments/{id}Consultar um pagamento.
GET/paymentsListar e filtrar pagamentos.
POST/payments/{id}/refundsReembolso total ou parcial.
POST/webhook-endpointsCadastrar destino e obter secret.
GET/webhook-endpointsListar destinos sem segredos.
DELETE/webhook-endpoints/{id}Remover destino.
GET/webhook-deliveries?limit=50Histórico de entregas.
© 2026 Trust7Documentação da API v1.3.0
Copiado