API TrustPay

Introdução

A API da TrustPay é REST, aceita e devolve JSON em UTF-8 e usa os verbos e códigos HTTP padrão. Tudo que o painel faz — cobrar, consultar saldo, sacar, gerenciar subcontas — está disponível pela API com as mesmas regras.

Rotas de negócio são escopadas ao seu merchant: o caminho sempre começa com /merchants/{merchantId}/…. O merchant da rota é autoritativo — o corpo da requisição nunca decide de qual conta é a operação.

Autenticação

Há duas credenciais, para dois usos diferentes: API key para integração servidor-a-servidor, e JWT para sessões de usuário no painel.

Criando uma API key

A criação exige um JWT de usuário Administrador. A chave é exibida uma única vez na resposta — guarde-a no momento em que criar, porque não há como recuperá-la depois.

curl -X POST https://api.trustand.com.br/api/v1/merchants/{merchantId}/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Servidor de produção"}'

{
  "id": "b2f1…",
  "name": "Servidor de produção",
  "key": "gk_live_9f2a…",
  "mode": "live",
  "createdAt": "2026-07-19T12:00:00.000Z"
}

Login de usuário e MFA

O login nunca devolve tokens diretamente: o segundo fator é obrigatório para todos os usuários. Com MFA ativo, o login retorna { mfaRequired, mfaToken } e você conclui em POST /auth/mfa/verify. Sem MFA, retorna { mfaSetupRequired, mfaSetupToken } e o usuário se inscreve no próprio fluxo de login.

Teste e produção

O sandbox não é um servidor separado: são os mesmos endpoints, discriminados pela chave que você usa.

Uma chave gk_test_ opera em modo teste — os dados nascem com livemode: false, ficam isolados da operação real e o adquirente de cartão é sempre o simulado, mesmo que haja um adquirente real configurado. Nada criado em modo teste aparece para a chave live nem toca o saldo real.

Primeira cobrança

Do zero a um pagamento aprovado em três chamadas. O exemplo usa cartão; PIX e boleto são ainda mais curtos.

1. Tokenize o cartão

O número do cartão nunca deve trafegar pela sua aplicação nem ser armazenado. Troque-o por um token de uso único, válido por 15 minutos.

curl -X POST https://api.trustand.com.br/api/v1/merchants/{merchantId}/card-tokens \
  -H "X-API-Key: $TRUSTPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "4111111111111111",
    "holderName": "MARIA SOUZA",
    "expiryMonth": "12",
    "expiryYear": "2030",
    "cvv": "123"
  }'
# → { "token": "tok_…", "cardLast4": "1111", "cardBrand": "visa" }

2. Crie o pagamento

curl -X POST https://api.trustand.com.br/api/v1/merchants/{merchantId}/payments \
  -H "X-API-Key: $TRUSTPAY_KEY" \
  -H "Idempotency-Key: pedido-10432" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 149.90,
    "paymentMethod": "credit_card",
    "cardToken": "tok_…",
    "installments": 1
  }'
# → { "id": "pay_…", "status": "authorized", … }

3. Capture

A autorização reserva o limite; a captura é o que efetivamente cobra e gera o recebível na sua agenda.

curl -X POST https://api.trustand.com.br/api/v1/merchants/{merchantId}/payments/pay_…/capture \
  -H "X-API-Key: $TRUSTPAY_KEY"
# → { "id": "pay_…", "status": "paid", … }

Erros

Erros usam os códigos HTTP padrão e sempre trazem um corpo JSON com a mesma forma.

{
  "statusCode": 422,
  "message": "Saldo insuficiente para a transferência",
  "error": "Unprocessable Entity"
}

Idempotência

Timeout de rede não significa que a operação falhou. A idempotência garante que reenviar a mesma requisição não cobra o cliente duas vezes.

Envie o header Idempotency-Key com um valor único seu (o ID do pedido serve bem) em qualquer POST. A primeira resposta é armazenada e as repetições com o mesmo payload recebem a resposta original de volta, sem executar nada.

# A mesma chave em duas chamadas idênticas cobra UMA vez.
curl -X POST https://api.trustand.com.br/api/v1/merchants/{merchantId}/payments \
  -H "X-API-Key: $TRUSTPAY_KEY" \
  -H "Idempotency-Key: pedido-10432" \
  -d '{"amount":149.90,"paymentMethod":"pix"}'

Além do header universal, POST /payments e POST /transfers também aceitam idempotencyKey dentro do corpo.

Paginação e filtros

Toda listagem compartilha a mesma base de parâmetros, e cada recurso acrescenta os seus.

Filtros específicos por recurso

Rate limits

Os limites são por IP e variam conforme a sensibilidade da rota.

Ao exceder, a resposta é 429 Too Many Requests. Implemente retry com backoff exponencial — e combine com idempotência para que a retentativa seja segura.

Pagamentos com cartão

O ciclo é autorizar → capturar. A autorização reserva o limite do portador; a captura cobra de fato e gera os recebíveis na sua agenda de liquidação.

Status possíveis: created → authorized → paid → partially_refunded → refunded, ou os terminais declined, blocked_fraud e cancelled.

{
  "token": "tok_7f3a…",
  "cardLast4": "1111",
  "cardBrand": "visa"
}

{
  "amount": 149.90,
  "paymentMethod": "credit_card",
  "cardToken": "tok_7f3a…",
  "installments": 3,
  "metadata": { "pedido": "10432" }
}

{
  "id": "pay_c81b…",
  "status": "authorized",
  "amount": 149.90,
  "installments": 3,
  "cardBrand": "visa",
  "cardLast4": "1111",
  "authorizationCode": "A1B2C3",
  "nsu": "004512",
  "livemode": true
}

{ "amount": 50.00 }

PIX

Cobrança PIX com BR Code copia-e-cola. A liquidação é assíncrona: o crédito no saldo acontece quando o pagador paga, e você é avisado por webhook.

{
  "id": "pix_4a90…",
  "status": "created",
  "amount": 149.90,
  "brCode": "00020126580014BR.GOV.BCB.PIX…",
  "expiresAt": "2026-07-19T15:02:00.000Z"
}

QR fixo (o QR do balcão). Um código estático permanente para consultório, clínica ou comércio: imprima uma vez e receba quantos PIX chegarem. Cada pagamento vira uma transação PIX própria (com staticQrId preenchido), com tarifa, comprovante e webhook pix.completed iguais aos da cobrança avulsa. Valor fixo (mínimo R$ 1,00) ou aberto — o pagador digita. Sem split.

Desativar é interno: o QR some do painel, mas um código já impresso pode continuar pagável no banco emissor — pagamento que chegar depois ainda credita, marcado em metadata.paid_while_disabled. Recolha o material físico ao desativar.

Boleto e Bole-Pix

Boleto registrado com linha digitável e código de barras FEBRABAN. Com withPix, o mesmo documento aceita pagamento por QR Code PIX — é o Bole-Pix.

{
  "id": "bol_1e77…",
  "status": "created",
  "amount": 149.90,
  "dueDate": "2026-08-05",
  "barcode": "00190500954014481606906809350314337370000010000",
  "barcodeLine": "00190.50095 40144.816069 06809.350314 3 37370000010000",
  "documentUrl": "https://…"
}

Transações unificadas

Uma listagem só para as cobranças dos três trilhos — cartão, PIX e boleto — e um detalhe por transação com a linha do tempo de eventos, paga ou não. É a mesma visão da tela Transações do painel.

{
  "data": [
    {
      "id": "97dd99ce-…",
      "type": "payment",
      "method": "card",
      "amount": 156.00,
      "netAmount": 151.34,
      "status": "partially_refunded",
      "info": "visa •••• 1111",
      "createdAt": "2026-07-20T21:52:37.000Z",
      "paidAt": "2026-07-20T21:52:37.000Z",
      "dueDate": null
    },
    {
      "id": "e3aa3844-…",
      "type": "boleto",
      "method": "bolepix",
      "amount": 80.00,
      "netAmount": null,
      "status": "pending",
      "info": "venc. 27/07/2026",
      "createdAt": "2026-07-20T21:53:22.000Z",
      "paidAt": null,
      "dueDate": "2026-07-27"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 50
}

type identifica a fonte (payment, pix ou boleto) e é o segmento usado nas rotas de detalhe abaixo. Um boleto híbrido aparece com method: bolepix; a cobrança PIX interna de um Bole-Pix não é listada — o boleto representa a cobrança.

O detalhe devolve { transaction, events[] }. Cada evento é { key, label, description?, occurredAt, amount? } — a linha do tempo da cobrança: criação, autorização (código/NSU), pagamento, recusa, estorno(s), liquidação de recebível por parcela, chargeback, vencimento, expiração e cancelamento. Evento sem data registrada vem com occurredAt: null; vencimento futuro de boleto vem com data futura (o painel o mostra como etapa prevista).

Links de pagamento

Uma página de checkout hospedada pela TrustPay, sem você escrever front-end. Útil para venda avulsa, cobrança por WhatsApp e primeiros testes.

{
  "id": "lnk_66c2…",
  "slug": "camisa-preta-p",
  "url": "https://app.trustand.com.br/pay/camisa-preta-p",
  "status": "active"
}

Cupons de desconto

O pagador digita um código na página e vê o valor já com desconto. O cupom vale na contratação: numa assinatura ele desconta a adesão e não volta nos meses seguintes — desconto que acompanha o contrato é preço, e preço mora na tabela de preços.

O desconto reduz o valor da cobrança: o que nasce em payments, pix_transactions ou boletos já é o valor com desconto, e é sobre ele que a tarifa incide. Para cobrar com cupom, envie couponCode no checkout.

Conferir o código não gasta o resgate — é o que a página chama enquanto o pagador digita. O limite de usos é reservado antes de a cobrança nascer, então dois pagamentos no mesmo instante não gastam o mesmo último cupom; e cobrança recusada devolve o cupom, para quem teve o cartão negado poder tentar de novo com o mesmo desconto.

Desconto que zeraria a cobrança é recusado, e link de assinatura não aceita cupom.

Sua marca na página

Quem abre o link conhece você, não a TrustPay. Envie branding na criação e a página de pagamento passa a exibir o seu nome, o seu logo e a sua cor no botão. O que você configurar volta na listagem, então o próximo link herda a mesma marca.

O logoUrl exige https — endereços http, data: e javascript: são recusados, porque a imagem é carregada numa página de pagamento e um recurso inseguro ali derruba o cadeado do navegador. Se o endereço sair do ar, a página esconde a imagem e mostra o nome.

Você não escolhe a cor do texto do botão: GET /pay/links/{slug} devolve onPrimary junto, calculado a partir da sua cor. Com um fundo claro o texto sai escuro, com um fundo escuro sai branco — assim o botão principal nunca fica ilegível. O rodapé informando que o pagamento é processado pela TrustPay aparece sempre.

Checkout público

Estas duas rotas não exigem autenticação — são o que a página hospedada consome. Use-as se preferir construir seu próprio checkout sobre o link.

Planos e assinaturas

Cobrança recorrente: você define o plano uma vez e a TrustPay cobra no ciclo. No cartão a cobrança liquida na hora; no boleto, Bole-Pix e PIX a TrustPay emite a cobrança e o ciclo só fecha quando o pagamento entra.

O ciclo fecha no pagamento, não na emissão. Em cartão, a cobrança liquida na hora e o ciclo já nasce pago. Em boleto, Bole-Pix e PIX a TrustPay emite a cobrança e o ciclo fica pending: o contador cyclesBilled só avança, e o próximo ciclo só é agendado, quando o dinheiro entra. Consulte o estado em GET /subscriptions/{id}/cycles.

O pagador tem 5 dias para quitar cada ciclo (nunca mais que o próprio intervalo do plano). Enquanto a cobrança estiver em aberto, nenhuma outra é emitida para o mesmo ciclo. Vencer sem pagamento leva a assinatura para past_due e, na terceira vez, suspended. O aniversário da assinatura conta a partir da emissão: quem paga com atraso não empurra os ciclos seguintes.

Dia fixo, para quem cobra todo mundo no mesmo dia. Com billingMode: "fixed_day" a cobrança vence sempre no billingDay do mês. Quem adere no meio do mês não recebe uma cobrança avulsa: o proporcional dos dias corridos entra somado à primeira parcela cheia. Um aluguel de R$ 1.000 que vence dia 5, assinado dia 25, gera no dia 5 uma única cobrança de R$ 1.000 mais os dias. A cobrança emitida sai 5 dias antes do vencimento — nextDueDate é a data que o pagador conhece. Mês curto encosta no último dia e o mês seguinte volta ao dia do plano.

Upgrade e downgrade em POST /subscriptions/{id}/change-plan: a troca vale na hora e a diferença proporcional aos dias restantes entra como crédito ou débito da próxima parcela, nunca como cobrança avulsa. Exige o mesmo meio de pagamento e o mesmo modelo de cobrança, e não roda enquanto houver cobrança em aberto.

Carnês (parcelamento com fim)

Um orçamento fechado vira entrada opcional + N parcelas mensais, cobradas por Bole-Pix, boleto ou PIX. O cronograma inteiro é gravado na criação; a cobrança de cada parcela é emitida automaticamente perto do vencimento, e o carnê termina sozinho na última parcela paga.

A emissão é automática e acontece perto do vencimento. A parcela nasce scheduled, vira issued quando a cobrança é emitida (~10 dias antes de vencer), paid quando o dinheiro entra e overdue quando vence sem pagamento. Boleto vencido continua pagável com multa e juros — o valor registrado é sempre o realmente pago.

Acompanhe pelos webhooks carne.installment_issued, carne.installment_paid, carne.installment_overdue, carne.completed e carne.canceled. Falha operacional de emissão (conta em análise, emissor fora do ar) dispara carne.charge_error e fica em lastChargeError — nenhuma parcela entra em atraso por isso, e a emissão é retentada automaticamente.

Clientes

Cadastrar o pagador é opcional, mas destrava notificações automáticas de cobrança e o histórico por cliente.

Quando a cobrança tem um cliente com contato, a TrustPay avisa esse cliente por e-mail: cobrança emitida, lembrete de vencimento, cobrança em atraso, confirmação de pagamento e renovação de assinatura.

A régua de lembretes é da conta e vale para boleto avulso, parcela de carnê e mensalidade de assinatura. reminderDays são os dias antes do vencimento (padrão [5,1,0], onde 0 é o próprio dia) e overdueDays os dias depois, para cobrança que venceu e continua em aberto (padrão [1,7]). Cada janela avisa uma única vez por cobrança, contando dias corridos no fuso de negócio. Array vazio desliga aquele lado da régua; notificationsEnabled: false desliga todos os avisos da conta.

Parcela de carnê só entra na régua depois de emitida — a emissão acontece perto do vencimento, então janelas muito longas não a alcançam. Em ambiente de teste nenhum aviso é entregue ao pagador.

Saldo e extrato

O saldo é derivado de um livro-razão imutável: não existe campo de saldo editável. Toda movimentação é um lançamento append-only.

{
  "available": 12450.00,
  "pending": 38900.00,
  "reserved": 1200.00,
  "reservedProjected": 3890.00,
  "total": 52550.00
}

Relatórios e performance

Números pré-agregados por dia (fuso de Brasília): dias fechados saem de uma tabela materializada, só o dia corrente é calculado ao vivo — a consulta responde rápido independente do volume histórico.

Todos os relatórios aceitam from/to (YYYY-MM-DD, inclusivos, máximo 366 dias) e product (card | pix | boleto), exigem a permissão report:read e têm uma variante /export.csv no dialeto que o Excel pt-BR abre com duplo clique.

{
  "period": { "from": "2026-06-22", "to": "2026-07-21" },
  "products": {
    "card": {
      "attempts": 120, "paid": 111, "declined": 9,
      "conversionPercent": 92.5,
      "refunds": { "count": 2, "amount": 180.00, "percent": 1.8 },
      "chargebacks": { "count": 1, "amount": 250.00, "percent": 0.9, "amountPercent": 1.1 }
    },
    "pix": {
      "issued": 300, "paid": 204,
      "conversionPercent": 68.0,
      "refunds": { "count": 1, "amount": 90.00, "percent": 0.49 }
    }
  },
  "days": [ { "day": "2026-07-21", "product": "pix", "issued": 12, "paid": 9 } ]
}

Disputas: chargeback e MED

Contestação de cartão (chargeback) e devolução especial de PIX (MED, do BACEN) viram registros com status atualizado automaticamente conforme o provedor avança no caso.

[{
  "id": "cb_91d2…",
  "paymentId": "pay_4a90…",
  "amount": 250.00,
  "reason": "FRAUD",
  "status": "under_review",
  "chargebackReference": "CB-8F31A2B4C5D6E",
  "createdAt": "2026-07-18T14:22:00.000Z",
  "resolvedAt": null
}]

[{
  "id": "med_7bc1…",
  "pix_transaction_id": "pix_4a90…",
  "amount": 250.00,
  "status": "opened",
  "reason": "MED — suspeita de fraude relatada pelo pagador",
  "resolved_at": null,
  "created_at": "2026-07-20T09:15:00.000Z"
}]

Recebíveis e antecipação

Cartão não liquida na hora: a captura cria uma agenda de recebíveis, uma linha por parcela, que vence em D+N. A antecipação troca essa espera por dinheiro hoje, com desconto.

O padrão é D+32, o prazo do adquirente (configurável em settlement_days_card): no parcelado, a 1ª parcela vence nesse prazo e as seguintes de mês em mês. Até vencer, o valor aparece em pending no saldo; um job liquida no vencimento e move para available.

Saques e transferências

Duas saídas de dinheiro: saque (payout) leva o saldo para a sua conta bancária cadastrada; transferência envia para terceiros por PIX ou TED.

{
  "method": "pix",
  "amount": 250.00,
  "receiverName": "João Pereira",
  "pixKey": "joao@exemplo.com.br",
  "pixKeyType": "email",
  "idempotencyKey": "repasse-2026-07-19-001"
}

As tarifas de PIX out e TED são pós-pagas: entram na fatura mensal, e o débito imediato é só o valor enviado. Criar transferência é permissão de Administrador.

Comprovantes

Segunda via sob demanda de qualquer transação concluída, em JSON estruturado ou PDF pronto para o cliente final.

type é um de payment, pix, boleto, transfer ou payout. A permissão exigida é a de leitura do recurso correspondente. Só transações concluídas têm comprovante — pendente ou recusada retorna 400.

Subcontas

No modelo marketplace, cada vendedor da sua plataforma vira uma subconta com saldo, extrato e KYC próprios, sob o seu guarda-chuva.

O que a conta-mãe pode e não pode

Split de pagamento

Divide uma cobrança entre várias contas no momento da liquidação. Funciona igual em cartão, PIX e boleto.

Envie splits na criação da cobrança. Cada regra aceita percentage (0,01 a 100) ou amount fixo, e os dois formatos podem ser misturados na mesma cobrança. O limite é de 20 recebedores.

{
  "amount": 1000.00,
  "paymentMethod": "pix",
  "splits": [
    { "recipientMerchantId": "sub_vendedor_a", "percentage": 70 },
    { "recipientMerchantId": "sub_vendedor_b", "amount": 150.00, "liable": false }
  ]
}

Quando cada parte é creditada

Em cartão, o split segue a agenda D+N: cada parte vira um recebível próprio por parcela e só é creditada ao liquidar — split nunca antecipa liquidação. Em PIX e boleto, as regras são persistidas na criação e recalculadas na confirmação: o percentual incide sobre o valor efetivamente pago (boleto vencido inclui multa e juros) e a tarifa do trilho é rateada proporcionalmente.

Webhooks

Webhooks são a fonte de verdade da sua integração: a TrustPay chama a sua URL a cada evento, com assinatura HMAC, retry automático e histórico consultável.

{
  "url": "https://minhaloja.com.br/webhooks/trustpay",
  "events": [
    "payment.captured",
    "payment.refunded",
    "pix.completed",
    "boleto.paid"
  ]
}

{
  "id": "wh_3d1f…",
  "secret": "whsec_a91c…",
  "status": "active"
}

Validar a assinatura é obrigatório

Cada entrega traz o header X-Webhook-Signature com o HMAC-SHA256 do corpo bruto. Valide antes de qualquer JSON.parse, com comparação de tempo constante.

const crypto = require('crypto');
 
// Use o RAW body — reserializar o JSON quebra a assinatura.
app.post('/webhooks/trustpay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const expected = crypto
      .createHmac('sha256', process.env.TRUSTPAY_WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');
    const received = req.headers['x-webhook-signature'];
 
    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
      return res.status(401).end();   // assinatura inválida → descarte
    }
 
    const event = JSON.parse(req.body);
    // processe de forma IDEMPOTENTE: o mesmo evento pode chegar 2x
    res.status(200).end();            // responda 2xx rápido
  });

Retry e histórico

Entrega que falha — resposta não-2xx ou timeout — volta para a fila com backoff exponencial, até 5 tentativas por padrão.

Eventos disponíveis

{
  "event": "payment.captured",
  "timestamp": "2026-07-19T14:32:07.412Z",
  "data": {
    "id": "pay_c81b…",
    "merchantId": "{merchantId}",
    "amount": 149.90,
    "status": "paid"
  }
}

Cartões de teste

Com a chave gk_test_, use estes números para forçar cada desfecho do adquirente.

Para PIX, use POST /pix/transactions/{id}/confirm para simular o pagamento. Para boleto, POST /boletos/{id}/pay ou /pay-pix. Em transferência, uma chave PIX contendo invalid resulta em failed sem débito, simulando recusa do DICT.

Tarifas

A tabela de tarifas é definida por conta, na proposta comercial: a plataforma não publica preço de prateleira. Consulte as tarifas da sua conta em GET /merchants/{mid}/pricing e simule o líquido de uma operação em GET /merchants/{mid}/pricing/simulate.

SDK e referência Swagger

Duas formas de ir além desta página.

SDK oficial para Node.js

Cliente TypeScript com zero dependências, cobrindo toda a API, com retry idempotente embutido.

import { Orion } from '@trustpay/node';
 
const orion = new Orion({ apiKey: process.env.TRUSTPAY_KEY });
 
const payment = await orion.payments.create('{merchantId}', {
  amount: 149.90,
  paymentMethod: 'pix',
});
 
const receipt = await orion.receipts.get('{merchantId}', 'pix', payment.id);

Referência OpenAPI

O Swagger é gerado direto do código e lista todos os endpoints, incluindo os administrativos que não estão nesta página. Use-o como referência exaustiva e para testar chamadas no navegador: https://api.trustand.com.br/docs. O schema puro, para gerar cliente ou validar payload, fica em https://api.trustand.com.br/openapi.json.

Integrando com apoio de IA

Se você integra com um assistente de código (Claude, Cursor, Copilot), aponte-o para estes endereços em vez de colar trechos desta página — eles descrevem a API inteira e são gerados a cada release, então não ficam para trás do que está no ar. Colar pedaços soltos é o que faz o assistente inventar rota que não existe.