Checkout de e-commerce ponta a ponta

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

Cenário

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

Cadastrar-se ou fazer login
Adicionar/selecionar endereço de entrega
Escolher método de pagamento (cartão, boleto ou PIX)
Visualizar opções de parcelamento
Finalizar a compra
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:

Todas as chamadas à API incluem o header SelectKey: sk_live_... (veja Autenticação). Operações de escrita (ex.: POST /v1/transactions) devem enviar X-Idempotency-Key.

Passo 1: Cadastro/Login do Cliente

// 1. Verificar se o cliente já existe
GET /v1/customers?email=[email protected]

// 2. Se não existir, criar novo cliente
POST /v1/customers
{
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]",
  "document": {
    "type": "cpf",
    "number": "12345678900"
  },
  "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

// 1. Listar endereços existentes
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",
  "customerId": "cus_123456789",
  ...
}

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

// 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",
  "customerId": "cus_123456789",
  "holderName": "JOAO SILVA",
  "firstDigits": "411111",
  "lastDigits": "1111",
  "brand": "visa",
  ...
}

Passo 4: Processamento da Transação

// Criação da transação com cartão de crédito em 3x
POST /v1/transactions
{
  "amount": 10000,
  "currency": "BRL",
  "externalReference": "PEDIDO-123",
  "customer": {
    "id": "cus_123456789"
  },
  "payment": {
    "method": "credit",
    "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",
  ...
}

Notas de contrato:

payment.method aceita credit, pix ou billet.

Para um cartão já salvo, basta payment.card.id. Para cartão inline, envie holderName, expirationMonth, expirationYear, numbering e securityCode dentro de payment.card.

billing.address é necessário para boleto (billet); para crédito/PIX é opcional.

Quando enviar items[], a soma de unitPrice × quantity deve ser igual a amount.

Descontos são por código de cupom: "discounts": [{ "code": "SUMMER10" }].

A transação nasce pending e o resultado chega por webhook (transaction.approved / transaction.failed) — não faça polling.

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

// Configurar webhook para receber notificações de status
POST /v1/webhooks/endpoints
{
  "name": "Notificações de Transações",
  "endpoint": "https://minhalojavirtual.com/webhooks/selectwin",
  "events": [
    "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_...",
  ...
}

Passo 6: 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.

{
  "id": "wbh_123456789",
  "type": "transaction.approved",
  "source": "automatic",
  "payload": {
    "object": {
      "id": "tra_123456789",
      "customId": "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 7: Consulta de Status da Transação

// Para verificar o status atual de uma transação
GET /v1/transactions/tra_123456789

// Resposta
{
  "id": "tra_123456789",
  "status": "approved",
  "timeline": [
    {
      "status": "created",
      "createdAt": "2023-06-15T14:30:45Z"
    },
    {
      "status": "approved",
      "createdAt": "2023-06-15T14:31:15Z"
    }
  ],
  ...
}

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

// Listar todas as transações do cliente para exibir em um painel
GET /v1/transactions?customerId=cus_123456789&sort=descending&limit=10

// Resposta
{
  "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": "PEDIDO-123",
      "amount": 10000,
      "status": "approved",
      "method": "credit",
      "createdAt": "2023-06-15T14:30:45Z"
    },
    {
      "id": "tra_987654321",
      "customId": "PEDIDO-122",
      "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:

Gestão de Clientes: Criação e consulta de perfis de cliente
Gestão de Endereços: Adição e seleção de endereços
Pagamentos: Suporte a cartão, PIX e boleto, com parcelamento no cartão
Processamento de Transações: Execução de pagamentos com diferentes métodos
Notificações em Tempo Real: Configuração de webhooks para receber atualizações de status
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.

Checkout de e-commerce ponta a ponta

On this page