SelectwinSelectwin

Exemplo de Caso de Uso Completo: Implementação de Checkout para E-commerce

Cenário

Uma loja virtual precisa implementar um processo de checkout completo, permitindo ao cliente:

  1. Cadastrar-se ou fazer login
  2. Adicionar/selecionar endereço de entrega
  3. Escolher método de pagamento (cartão, boleto ou PIX)
  4. Visualizar opções de parcelamento
  5. Finalizar a compra
  6. Receber notificações sobre o status da transação

Fluxo de Implementação com a API Selectwin

O diagrama abaixo resume a sequência de chamadas dos passos a seguir — do cadastro do cliente à confirmação assíncrona via webhook:

sequenceDiagram
    autonumber
    participant C as Cliente (Browser)
    participant L as Loja (Backend)
    participant API as Selectwin API
    participant WH as Webhook (Loja)

    C->>L: Inicia checkout
    L->>API: GET /v1/customers?email=...
    alt cliente não existe
        L->>API: POST /v1/customers
        API-->>L: cus_...
    end
    L->>API: POST /v1/addresses
    API-->>L: addr_...
    opt cartão de crédito
        L->>API: POST /v1/cards
        API-->>L: card_...
        L->>API: GET /v1/simulators/installments?amount=...
        API-->>L: tabela de parcelas
    end
    L->>API: POST /v1/transactions
    API-->>L: tra_... (201, status: pending)
    opt PIX ou boleto
        API-->>WH: POST webhook · transaction.pending (QR Code ou linha digitável)
        WH-->>API: 200 OK
    end
    API-->>WH: POST webhook · transaction.approved (assíncrono)
    WH-->>API: 200 OK
    Note over L,WH: O resultado vem pelo webhook (não faça polling). Um GET pontual é opcional.

Passo 1: Cadastro/Login do Cliente

JavaScript
// 1. Verificar se o cliente já existe
GET /v1/customers?email=cliente@exemplo.com

// 2. Se não existir, criar novo cliente
POST /v1/customers
{
  "firstName": "João",
  "lastName": "Silva",
  "email": "cliente@exemplo.com",
  "document": {
    "type": "cpf",
    "number": "12345678909"
  },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999998888"
  }
}

// Resposta (salvar ID para próximos passos)
{
  "id": "cus_123456789",
  "firstName": "João",
  "lastName": "Silva",
  ...
}

Passo 2: Gerenciamento de Endereço

JavaScript
// 1. Listar endereços existentes do cliente (o filtro é customerid, tudo minúsculo)
GET /v1/addresses?customerid=cus_123456789

// 2. Se não houver endereço ou o cliente desejar cadastrar um novo
POST /v1/addresses
{
  "customerId": "cus_123456789",
  "street": "Avenida Paulista",
  "number": "1000",
  "complement": "Apto 123",
  "district": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "postcode": "01310-100",
  "primary": true
}

// Resposta (salvar ID para a transação)
{
  "id": "addr_123456789",
  "ownerType": "customer",
  "ownerId": "cus_123456789",
  ...
}

Passo 3: Criação do Cartão (quando aplicável)

JavaScript
// Se o cliente optar por salvar o cartão para futuras compras
POST /v1/cards
{
  "customerId": "cus_123456789",
  "holderName": "JOAO SILVA",
  "numbering": "4111111111111111",
  "expirationMonth": 12,
  "expirationYear": 2030,
  "securityCode": "123"
}

// Resposta (salvar ID para a transação)
{
  "id": "card_123456789",
  "holderName": "JOAO SILVA",
  "firstDigits": "411111",
  "lastDigits": "1111",
  "brand": "visa",
  ...
}

Passo 4: Opções de Parcelamento (cartão)

Para mostrar as parcelas ao cliente, simule a tabela para o valor do pedido:

JavaScript
GET /v1/simulators/installments?amount=10000

// Resposta (resumida): uma linha por número de parcelas, até o máximo da conta
{
  "resource": "credit",
  "installments": [
    { "installment": 1, "installmentAmountCents": 10000, "totalAmountCents": 10000,
      "extraFee": false, "description": "sem juros" },
    { "installment": 3, "installmentAmountCents": 3333, "totalAmountCents": 10000,
      "extraFee": false, "description": "sem juros" },
    { "installment": 6, "installmentAmountCents": 1783, "totalAmountCents": 10700,
      "extraFee": true, "description": "com juros" },
    ...
  ],
  ...
}
  • installmentAmountCents é o valor de cada parcela e totalAmountCents, o total que o cliente paga; extraFee: true marca as linhas com juros do comprador (os configurados na conta).
  • Na cobrança, envie o amount do pedido (sem juros) e o número de installments escolhido: a API aplica o mesmo cálculo da simulação e cobra o total daquela linha (payment.financeInstallments, ligado por padrão). Com juros, o amount da transação passa a ser o total financiado, e o originalAmount guarda o valor do pedido.
  • Pedir mais parcelas do que a tabela oferece responde 422.

Passo 5: Processamento da Transação

Cartão de crédito

JavaScript
// Criação da transação com cartão de crédito em 3x
POST /v1/transactions
{
  "amount": 10000,
  "externalReference": "PEDIDO-123",
  "customer": {
    "id": "cus_123456789"
  },
  "payment": {
    "method": "credit",
    "currency": "BRL",
    "installments": 3,
    "card": {
      "id": "card_123456789"
    }
  },
  "billing": {
    "address": {
      "id": "addr_123456789"
    }
  },
  "items": [
    {
      "name": "Smartphone XYZ",
      "unitPrice": 10000,
      "quantity": 1
    }
  ],
  "metadata": {
    "source": "website",
    "campaign": "summer_sale"
  }
}

// Resposta da transação (a criação é ASSÍNCRONA: nasce "pending")
{
  "id": "tra_123456789",
  "amount": 10000,
  "status": "pending",
  "method": "credit",
  ...
}

O desfecho chega por webhook: transaction.approved ou transaction.failed.

PIX

JavaScript
// PIX: o QR Code vale 30 minutos
POST /v1/transactions
{
  "amount": 10000,
  "externalReference": "PEDIDO-124",
  "customer": {
    "id": "cus_123456789"
  },
  "payment": {
    "method": "pix",
    "currency": "BRL",
    "pix": {
      "expiresInMinutes": 30
    }
  },
  "items": [
    {
      "name": "Smartphone XYZ",
      "unitPrice": 10000,
      "quantity": 1
    }
  ]
}

// Resposta: nasce "pending", ainda sem o QR Code
{
  "id": "tra_223456789",
  "amount": 10000,
  "status": "pending",
  "method": "pix",
  ...
}

O QR Code chega logo depois, no webhook transaction.pending, e fica na leitura da transação (GET /v1/transactions/{id}):

JSON
{
  "type": "transaction.pending",
  "payload": {
    "object": {
      "id": "tra_223456789",
      "externalReference": "PEDIDO-124",
      "status": "pending",
      "method": "pix",
      "payment": {
        "pixQrCodeEmv": "000201010212...",
        "pixQrCodeUrl": "https://...",
        "expirationDate": "2023-06-15T15:00:45Z"
      }
    }
  }
}
  • Mostre ao cliente o copia e cola (payment.pixQrCodeEmv) e gere a imagem do QR Code a partir dele: a API não gera a imagem (payment.pixQrCodeImage vem sempre null).
  • Sem pix.expiresInMinutes, vale o prazo configurado na conta (o padrão é 30 minutos).
  • Pago, chega transaction.approved. Vencido sem pagamento, transaction.canceled; se o pagamento ainda chegar depois disso, a transação é aprovada (transaction.approved).

Boleto

JavaScript
// Boleto: vence em 3 dias; o endereço de cobrança é obrigatório
POST /v1/transactions
{
  "amount": 10000,
  "externalReference": "PEDIDO-125",
  "customer": {
    "id": "cus_123456789"
  },
  "payment": {
    "method": "billet",
    "currency": "BRL",
    "billet": {
      "expiresInDays": 3
    }
  },
  "billing": {
    "address": {
      "id": "addr_123456789"
    }
  },
  "items": [
    {
      "name": "Smartphone XYZ",
      "unitPrice": 10000,
      "quantity": 1
    }
  ]
}

// Resposta: nasce "pending", ainda sem a linha digitável
{
  "id": "tra_323456789",
  "amount": 10000,
  "status": "pending",
  "method": "billet",
  ...
}

Como no PIX, os dados do boleto chegam no webhook transaction.pending e ficam na leitura da transação: a linha digitável em payment.billetBarcode, o link do boleto em payment.billetUrl e o vencimento em payment.expirationDate. Pago, chega transaction.approved. O boleto fica pending até o vencimento e não é cancelado automaticamente quando vence: continua pending até ser pago (transaction.approved, inclusive com atraso) ou baixado (transaction.canceled).

Passo 6: Configuração de Webhook para Notificações

Uma vez só, antes da primeira cobrança:

JavaScript
// Configurar webhook para receber notificações de status
POST /v1/webhooks
{
  "name": "Notificações de Transações",
  "endpoint": "https://minhalojavirtual.com/webhooks/selectwin",
  "events": [
    "transaction.pending",
    "transaction.approved",
    "transaction.failed",
    "transaction.canceled",
    "transaction.refunded"
  ]
}

// Resposta (traz o `secret` whsec_... — guarde-o para verificar a assinatura)
{
  "id": "wbe_123456789",
  "name": "Notificações de Transações",
  "endpoint": "https://minhalojavirtual.com/webhooks/selectwin",
  "secret": "whsec_...",
  ...
}

O transaction.pending traz o QR Code do PIX e a linha digitável do boleto (passo 5).

Passo 7: Recebimento e Processamento de Eventos

O servidor da loja virtual deverá implementar um endpoint para receber as notificações via webhook. Exemplo de evento recebido:

O objeto do recurso é entregue em payload.object (mesma estrutura da leitura do recurso) — não há chave data/resource no nível raiz.

JSON
{
  "id": "wbh_123456789",
  "type": "transaction.approved",
  "source": "automatic",
  "payload": {
    "object": {
      "id": "tra_123456789",
      "externalReference": "PEDIDO-123",
      "amount": 10000,
      "status": "approved",
      "method": "credit",
      "payment": {
        "cardFirstDigits": "411111",
        "cardLastDigits": "1111",
        "cardBrand": "visa",
        "installments": 3
      },
      "customer": {
        "id": "cus_123456789",
        "firstName": "João",
        "lastName": "Silva"
      }
    }
  },
  "createdAt": "2023-06-15T14:35:30Z"
}

Passo 8: Consulta de Status da Transação

JavaScript
// Para verificar o status atual de uma transação (uma consulta pontual, não polling)
GET /v1/transactions/tra_123456789

// Resposta (resumida)
{
  "id": "tra_123456789",
  "externalReference": "PEDIDO-123",
  "status": "approved",
  "method": "credit",
  "payment": {
    "installments": 3,
    "paidAt": "2023-06-15T14:31:15Z",
    ...
  },
  ...
}

Passo 9: Listagem de Transações para Painel do Cliente

JavaScript
// Listar as transações do cliente para exibir em um painel (a mais recente primeiro)
GET /v1/transactions?customerId=cus_123456789&limit=10

// Resposta (cada item é uma projeção leve: amount vem como string, e customId é o identificador gerado pela API)
{
  "offset": 0,
  "limit": 10,
  "total": 2,
  "page": {
    "offset": {
      "first": 0,
      "prev": 0,
      "next": 0,
      "last": 0
    },
    "current": 1,
    "total": 1
  },
  "hasMore": false,
  "data": [
    {
      "id": "tra_123456789",
      "customId": "E5D4C3B2A1",
      "customerId": "cus_123456789",
      "amount": "10000",
      "status": "approved",
      "method": "credit",
      "createdAt": "2023-06-15T14:30:45Z"
    },
    {
      "id": "tra_987654321",
      "customId": "K7M8N9P2Q3",
      "customerId": "cus_123456789",
      "amount": "5000",
      "status": "approved",
      "method": "pix",
      "createdAt": "2023-06-10T11:22:33Z"
    }
  ]
}

Considerações Finais

Este caso de uso demonstra como utilizar os diferentes recursos da API Selectwin de forma integrada para criar uma experiência de checkout completa. Os principais aspectos implementados incluem:

  1. Gestão de Clientes: Criação e consulta de perfis de cliente
  2. Gestão de Endereços: Adição e seleção de endereços
  3. Pagamentos: Suporte a cartão, PIX e boleto, com parcelamento no cartão
  4. Processamento de Transações: Execução de pagamentos com diferentes métodos
  5. Notificações em Tempo Real: Configuração de webhooks para receber atualizações de status
  6. Consulta de Histórico: Listagem e verificação de transações anteriores

A flexibilidade da API permite personalizar cada etapa de acordo com as necessidades específicas do negócio, oferecendo uma solução completa e robusta para processamento de pagamentos online.

AnteriorReenviar entrega

Atualizado em 21 de outubro de 2026

Preferências de cookies

Hoje o site usa só cookies essenciais: nenhuma ferramenta de medição ou de anúncios está ligada, e nada é compartilhado com terceiros. Se isso mudar, você decide aqui antes de qualquer coisa ser carregada.

  • Essenciais

    Mantêm o site funcionando: segurança, a sua escolha sobre cookies e preferências como a versão da documentação. Não dependem de consentimento.

    Sempre ativos
Política de privacidade