Quickstart

Sua primeira cobrança com o @selectwin/sdk: criar o cliente, cobrar via Pix, tratar erros, paginar e receber a confirmação por webhook.

Sua primeira cobrança com o @selectwin/sdk: criar o cliente, cobrar via Pix, tratar erros, paginar e receber a confirmação por webhook.

1. Instale e configure

npm install @selectwin/sdk

import { Selectwin } from '@selectwin/sdk';

const sw = new Selectwin(process.env.SELECTWIN_API_KEY!); // sk_test_… / sk_live_…

Valores são inteiros em centavos (5000 = R$ 50,00). O customer pode ser um id de cliente salvo ou dados inline (firstName + lastName + email) — nesse caso a API localiza ou cria o cliente antes de cobrar.

const tx = await sw.transactions.create({
  amount: 5000,
  payment: { method: 'pix', currency: 'BRL' },
  customer: {
    firstName: 'João',
    lastName: 'Silva',
    email: '[email protected]',
    document: { type: 'cpf', number: '12345678901' },
  },
});

console.log(tx.id, tx.status); // tra_… pending

A idempotência é automática: cada mutação envia um X-Idempotency-Key. Para reusar sua própria chave (ex.: retry seguro de um pedido), passe { idempotencyKey } nas opções da chamada.

3. Trate os erros

Os erros são tipados por error.code — decida pelo tipo, nunca pela mensagem.

import { SelectwinError, CardError, ValidationError } from '@selectwin/sdk';

try {
  await sw.transactions.create({ /* … */ });
} catch (e) {
  if (e instanceof CardError) {
    console.error('Cartão recusado:', e.message); // 402
  } else if (e instanceof ValidationError) {
    console.error('Dados inválidos:', e.params);   // 422
  } else if (e instanceof SelectwinError) {
    console.error(e.code, e.message);
  } else {
    throw e;
  }
}

4. Pagine

list() devolve um auto-paginador: use for await para iterar todos os itens, ou await para pegar só a primeira página.

for await (const t of sw.transactions.list({ limit: 100 })) {
  console.log(t.id, t.status);
}

const firstPage = await sw.transactions.list({ limit: 20 }); // { data, hasMore, … }

5. Receba a confirmação por webhook

Registre um endpoint para ouvir os eventos (a resposta traz um secret whsec_… — guarde-o):

const endpoint = await sw.webhooks.createEndpoint({
  name: 'Minha loja',
  endpoint: 'https://minhaloja.com/webhooks/selectwin',
  events: ['transaction.approved', 'transaction.failed'],
});

No seu servidor, verifique a assinatura X-Selectwin-Signature com o corpo cru (não o JSON já parseado) antes de confiar no payload:

import express from 'express';
import { constructEvent, SignatureVerificationError } from '@selectwin/sdk';

app.post('/webhooks/selectwin', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = constructEvent(
      req.body, // Buffer cru
      req.headers['x-selectwin-signature'],
      process.env.SELECTWIN_WEBHOOK_SECRET!,
    );
  } catch (e) {
    if (e instanceof SignatureVerificationError) return res.status(400).send('assinatura inválida');
    throw e;
  }

  if (event.type === 'transaction.approved') {
    const tx = event.payload.object; // tipado
    // … dê baixa no pedido
  }

  res.sendStatus(200);
});

Nunca faça polling para saber o resultado — use webhooks. O objeto do recurso vem sempre em event.payload.object.

Próximos passos

Referência da API — todos os endpoints e modelos.
Verificando assinaturas de webhook — detalhes do HMAC.
Idempotência · Paginação · Erros.