API da Wallet

Autenticação

Crie a chave em API Wallet, confirme a verificação em duas etapas e guarde o valor wlk_…. Envie a chave no cabeçalho X-Api-Key apenas do seu servidor. A chave completa aparece uma vez; a revogação bloqueia novas chamadas e encerra conexões WebSocket em até 30 segundos.

Cada chave aceita até 120 requisições por minuto, 10 criações de cobrança em 10 minutos e 30 conexões WebSocket por minuto. Na primeira infração, somente essa chave recebe HTTP 429 até o fim da janela. Uma segunda infração distinta em até uma hora limita todas as chaves da mesma Wallet por 15 minutos. O erro informa retry_after em segundos. A resposta segue o envelope da API Amethys: {"success":true,"data":{…}}.

Criar cobranças

POST /payments exige Idempotency-Key única por chave (8–128 caracteres). Repetir a mesma chave com os mesmos dados devolve a cobrança original; reutilizá-la com dados diferentes retorna HTTP 409. Use uma chave por pedido do seu sistema.

curl -X POST https://api.amethys.lat/api/v1/wallet/v1/payments \
  -H 'X-Api-Key: wlk_SUA_CHAVE' \
  -H 'Idempotency-Key: pedido_12345678' \
  -H 'Content-Type: application/json' \
  -d '{"amount_cents":1000,"payment_method":"card","payer_name":"Cliente Exemplo","payer_document":"CPF_OU_CNPJ_VALIDO","description":"Pedido 123"}'

Substitua a chave e o CPF/CNPJ de exemplo por valores válidos antes de executar.

payment_method aceita card ou pix; sem o campo, usa Pix. amount_cents é o valor base antes da taxa, com cobrança final entre 500 e 200.000 centavos no cartão ou 200 e 200.000 no Pix. Envie payer_name, CPF/CNPJ em payer_document e description. A resposta informa payment_method, valores, estado e checkout_url para cartão; no Pix, traz copy_paste e qr_code quando disponíveis. Estados: pending, approved, completed, failed. Cartão aprovado fica em approved até a PagMaster liberar o saldo; somente completed credita a Wallet.

GET /balance consulta o saldo, saque pendente e valor bloqueado; GET /payments?limit=25 lista até 100 cobranças criadas pela própria chave. Uma chave não acessa cobranças de outra.

Polling

Consulte GET /payments/:id para o estado atual. Para vários pagamentos, GET /events?after=EVENT_ID devolve até 100 eventos em ordem com next_cursor. Guarde esse cursor e envie-o na próxima consulta. Aguarde alguns segundos entre consultas e trate IDs repetidos como o mesmo evento.

curl https://api.amethys.lat/api/v1/wallet/v1/payments/ID_DA_COBRANCA \
  -H 'X-Api-Key: wlk_SUA_CHAVE'

curl 'https://api.amethys.lat/api/v1/wallet/v1/events?after=ULTIMO_EVENT_ID' \
  -H 'X-Api-Key: wlk_SUA_CHAVE'

WebSocket

Conecte seu servidor a wss://api.amethys.lat/api/v1/wallet/v1/ws com a chave no cabeçalho X-Api-Key. Passe ?after=EVENT_ID para retomar eventos perdidos. Sem cursor, a conexão começa nos novos eventos. As mensagens trazem event_id, type, created_at e data. Se a conexão cair, reconecte com o último ID persistido. Navegadores não devem receber sua API Key.

import WebSocket from 'ws'

const ws = new WebSocket('wss://api.amethys.lat/api/v1/wallet/v1/ws?after=ULTIMO_EVENT_ID', {
  headers: { 'X-Api-Key': process.env.WALLET_API_KEY }
})
ws.on('message', raw => {
  const event = JSON.parse(raw.toString())
  if (event.event_id) {
    // Processe uma vez pelo event_id e salve o cursor.
    console.log(event.type, event.data)
  }
})

Webhook assinado

Configure uma URL HTTPS pública na chave. O segredo whsec_… aparece uma vez, na criação ou rotação. O worker envia payment.created, payment.approved (cartão), payment.completed e payment.failed em POST JSON. Responda HTTP 2xx apenas após registrar o evento; falhas são tentadas novamente até cinco vezes. O mesmo evento pode ser entregue mais de uma vez.

Verifique o corpo bruto usando HMAC-SHA256(secret, timestamp + "." + rawBody). Compare com X-Amethys-Signature: sha256=…, confira X-Amethys-Timestamp e deduplique pelo id ou X-Amethys-Delivery. O webhook traz identificadores e valores, sem dados do pagador ou cartão.

import { createHmac, timingSafeEqual } from 'node:crypto'

const timestamp = req.headers['x-amethys-timestamp']
const received = req.headers['x-amethys-signature']?.replace(/^sha256=/, '')
const expected = createHmac('sha256', process.env.WALLET_WEBHOOK_SECRET)
  .update(timestamp + '.' + rawBody).digest('hex')
const valid = typeof received === 'string' && /^[0-9a-f]{64}$/.test(received)
  && timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(received, 'hex'))
// Rejeite também timestamps com mais de 5 minutos e deduplique pelo id do evento.
if (!valid) throw new Error('Assinatura inválida')

Taxas e segurança

A chave escolhe quem paga a taxa vigente da Wallet: Minha Wallet desconta a taxa do recebimento; Cliente acrescenta a taxa ao valor cobrado e preserva o valor solicitado como recebimento líquido. A resposta da cobrança mostra o cálculo em centavos. Alterar a opção afeta apenas cobranças futuras.

O saque continua na dashboard, com aprovação e verificação em duas etapas. Não há saque por API Key. Mantenha chave e segredo em variáveis de ambiente do servidor, nunca em JavaScript entregue ao navegador ou em URLs.