Quickstart

Sua primeira cobrança com o SDK selectwin: criar o cliente, cobrar via Pix, tratar erros, paginar e receber a confirmação por webhook. Todos os exemplos são síncronos; o cliente AsyncSelectwin tem a m

Sua primeira cobrança com o SDK selectwin: criar o cliente, cobrar via Pix, tratar erros, paginar e receber a confirmação por webhook. Todos os exemplos são síncronos; o cliente AsyncSelectwin tem a mesma superfície com await.

1. Instale e configure

pip install selectwin

import os
from selectwin import Selectwin

sw = Selectwin(api_key=os.environ["SELECTWIN_API_KEY"])  # sk_test_… / sk_live_…

2. Crie uma transação

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.

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

print(tx.id, tx.status)  # tra_… pending

A idempotência é automática em toda mutação. Os resultados são modelos tipados (atributos como tx.id, tx.status).

3. Trate os erros

Os erros são tipados — capture pelo tipo, nunca pela mensagem.

from selectwin import CardError, ValidationError, SelectwinError

try:
    sw.transactions.create({ ... })
except CardError as e:
    print("Cartão recusado:", e)   # 402
except ValidationError as e:
    print("Dados inválidos:", e)   # 422
except SelectwinError as e:
    print("Erro da API:", e)

4. Pagine

list() devolve um paginador iterável — percorra todos os itens sem gerenciar cursores:

for tx in sw.transactions.list(limit=100):
    print(tx.id, tx.status)

No cliente async, use async for:

async for tx in sw.transactions.list(limit=100):
    ...

5. Receba a confirmação por webhook

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

endpoint = sw.webhooks.create_endpoint({
    "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 (bytes, não o JSON reparseado) antes de confiar no payload. Exemplo com Flask:

import os
from flask import Flask, request
from selectwin import construct_event, SignatureVerificationError

app = Flask(__name__)

@app.post("/webhooks/selectwin")
def selectwin_webhook():
    try:
        event = construct_event(
            request.get_data(),  # corpo CRU (bytes)
            request.headers.get("X-Selectwin-Signature"),
            os.environ["SELECTWIN_WEBHOOK_SECRET"],
        )
    except SignatureVerificationError:
        return "assinatura inválida", 400

    if event.type == "transaction.approved":
        tx = event.payload.object  # dict do recurso
        # … dê baixa no pedido

    return "", 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.