1. Primeiros passos

Este guia mostra a integração de ponta a ponta, na ordem em que as chamadas acontecem, com as respostas e os webhooks de cada etapa. Os ids dos exemplos se repetem de um passo para o outro, para você seguir o mesmo pedido do começo ao fim.

flowchart LR
  A["1. Chaves e webhook"] --> B["2. Receber por Pix"]
  B --> C["3. Sacar por Pix"]
  A --> D["4. Cripto: cadastrar cliente"]
  D --> E["5. Cripto: receber depósito"]
  E --> F["6. Cripto: pagar o cliente"]
  E --> G["7. Cripto: sacar o saldo da loja"]
  C --> H["8. Go-live"]
  F --> H
  G --> H

1. Base URL

Todas as rotas ficam sob https://api.gestaotechnology.com/api. Exemplo: https://api.gestaotechnology.com/api/payments/merchant/transaction/pix. Ver Ambientes.

2. Criar as chaves de API (painel)

No painel, em Credenciais de API, crie:

Chave	Onde usar	Scopes
PUBLIC	Pode ficar no checkout/app	CREATE_PIX_TRANSACTION (criar cobranças e consultar status)
SECRET	Só no seu servidor	Os que você vai usar: READ_BALANCE, CREATE_WITHDRAW, READ_WITHDRAWS, CREATE_REFUND, READ_TRANSACTIONS, READ_ORDERS e, para cripto, CRYPTO_READ e CRYPTO_WRITE

A chave aparece uma única vez. Guarde-a num cofre de segredos. Ver Chaves e scopes.

Teste a chave secreta:

Testar a chave

curl -s https://api.gestaotechnology.com/api/merchant/balance \
  -H "X-Api-Key: <SECRET_KEY>"

200 com o saldo: chave ok. 401: chave errada. 403: falta o scope READ_BALANCE.

3. Cadastrar o webhook (painel)

No painel, em Webhooks, cadastre uma URL HTTPS pública do seu servidor e marque os eventos que vai tratar:

Fluxo	Eventos
Receber por Pix	transaction.paid, transaction.refunded
Sacar por Pix	withdraw.completed, withdraw.failed
Cripto	crypto.customer.updated, crypto.deposit.paid, crypto.deposit.refunded, crypto.payout.processing, crypto.payout.paid, crypto.payout.failed, crypto.withdrawal.processing, crypto.withdrawal.paid, crypto.withdrawal.failed

No cadastro aparece o signingSecret (whsec_…), também uma única vez. Guarde-o: é com ele que você confere que o webhook veio da Gestão Intermediações.

4. Receber e validar o webhook

Todo webhook é um POST com este corpo:

{
  "event": "transaction.paid",
  "occurredAt": "2026-10-15T13:05:12.000Z",
  "data": { "...": "campos do evento" }
}

e os headers X-Shatin-Event, X-Shatin-Timestamp e X-Shatin-Signature. Valide antes de processar:

Receptor de webhook (Node.js + Express)

const crypto = require('crypto');
const express = require('express');
const app = express();

// Corpo cru: a assinatura é calculada sobre os bytes exatos recebidos.
app.post('/webhooks/pagamentos', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.header('x-shatin-timestamp');
  const signature = req.header('x-shatin-signature') || '';
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body.toString('utf8')}`)
    .digest('hex');
  const ok = signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  // Responda 2xx rápido e processe em fila; o mesmo evento pode chegar mais de uma vez.
  enqueue(event);
  res.status(200).end();
});

Regras de entrega:

• Responda 2xx em até 5 segundos; processe em segundo plano.
• Falhou ou demorou: até 5 novas tentativas (≈ 1, 2, 4, 8 e 16 minutos).
• A entrega é at-least-once: o mesmo evento pode chegar duas vezes. Deduplique pelo id do recurso + event (ex.: subTransactionId + transaction.paid).

Ver Assinatura e Retries.

Checklist

• Base URL com /api.
• Chave PUBLIC (se for criar cobrança pelo cliente) e chave SECRET com os scopes certos, guardadas em cofre.
• Webhook HTTPS cadastrado com os eventos dos fluxos que você usa.
• signingSecret guardado e assinatura validada com o corpo cru.
• Receptor responde 2xx rápido e é idempotente.

Próximo: Receber por Pix ou Cripto: cadastrar cliente.