Quickstart

Sua primeira cobrança em poucos minutos. Você vai: autenticar, criar uma transação PIX, e receber a

Sua primeira cobrança em poucos minutos. Você vai: autenticar, criar uma transação PIX, e receber a confirmação por webhook.

1. Obtenha sua chave

No Painel Administrativo → Configurações → API & Webhooks, copie uma chave:

Sandbox: sl_test_... · Produção: sl_live_...

Toda requisição envia a chave no header SelectKey. Guarde-a como variável de ambiente.

2. Faça sua primeira chamada

Liste transações (deve retornar uma lista paginada vazia ou existente):

curl "https://api.selectwin.io/v1/transactions" \
  -H "SelectKey: sl_test_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

3. Crie uma transação (PIX)

Valores são inteiros em centavos (5000 = R$ 50,00):

curl -X POST "https://api.selectwin.io/v1/transactions" \
  -H "SelectKey: sl_test_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 2dfc6a63-5df5-4900-baca-e49d91ef393e" \
  -d '{
    "amount": 5000,
    "currency": "BRL",
    "customId": "PEDIDO-1001",
    "customer": {
      "firstName": "João",
      "lastName": "Silva",
      "email": "[email protected]",
      "document": { "type": "cpf", "number": "12345678901" }
    },
    "payment": { "method": "pix" }
  }'

Resposta (resumida):

{
  "id": "tra_01hqzvabc",
  "status": "pending",
  "amount": 5000,
  "method": "pix",
  "currency": "BRL"
}

A transação PIX nasce pending e vira approved quando o pagamento é confirmado. Não faça polling para descobrir isso — use webhooks (passo 4). Veja o ciclo de status.

4. Receba a confirmação por webhook

Registre um endpoint para ouvir os eventos de transação:

curl -X POST "https://api.selectwin.io/v1/webhooks/endpoints" \
  -H "SelectKey: sl_test_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Minha loja",
    "endpoint": "https://minhaloja.com/webhooks/selectwin",
    "events": ["transaction.approved", "transaction.refused"]
  }'

A resposta traz um secret (whsec_...) — guarde-o para verificar a assinatura das entregas. Quando o pagamento for confirmado, seu endpoint recebe:

{
  "id": "wbh_01hqzvabc",
  "type": "transaction.approved",
  "resource": "transaction",
  "resourceId": "tra_01hqzvabc",
  "data": { "id": "tra_01hqzvabc", "status": "approved", "amount": 5000 }
}

⚠️ Sempre verifique a assinatura X-Selectwin-Signature antes de confiar no payload — veja Verificando Assinaturas de Webhook.

Próximos passos

Convenções — centavos, datas, IDs opacos
Cartões de teste — para testar crédito no sandbox
Transações — crédito, captura, estorno, disputa
Tratamento de Erros + Catálogo de Códigos
Idempotência — repita requisições com segurança