Checkouts

O recurso de Checkouts reúne duas formas de vender pela API:

• Checkout Sessions — carrinho hospedado para uma intenção de compra específica (/v1/checkouts/sessions). Você cria a sessão, recebe uma url de checkout e a entrega ao comprador.
• Payment Links — link de checkout reutilizável e compartilhável, com assinatura (/v1/checkouts/payment-links). Recurso persistente que você cria, consulta, lista, atualiza e remove.

#Recursos Disponíveis

#Autenticação

Todos os endpoints de checkout usam o header SelectKey (sk_test_…/sk_live_…) — veja Autenticação.

#URL hospedada e assinatura

Ao criar um link, a resposta traz accessFullUrl — a URL pronta para compartilhar — e uma signature HMAC SHA256 que protege a integridade dos parâmetros do link. A página hospedada revalida a assinatura (e a janela de validade) antes de exibir o checkout.

sequenceDiagram
    autonumber
    participant L as Loja (Backend)
    participant API as Selectwin API
    participant B as Comprador (Browser)

    L->>API: POST /v1/checkouts/payment-links (name, items, ...)
    Note over API: persiste o link e assina (HMAC SHA256)
    API-->>L: 201 { id: link_..., accessFullUrl, signature }
    L-->>B: compartilha accessFullUrl
    B->>API: abre a página de checkout (sign na query)
    Note over API: revalida assinatura + janela (expiresAt/availableAt)
    alt válido
        API-->>B: página de pagamento
    else inválido / expirado
        API-->>B: 4xx (link inválido)
    end

#Itens

Os items referenciam variantes a vender, no formato { id, quantity }:

{
  "items": [
    { "id": "var_01hqzvabc", "quantity": 1 },
    { "id": "var_1234567890abcdef", "quantity": 2 }
  ]
}

#Janela de validade

• expiresAt — instante após o qual o link não pode mais ser usado.
• availableAt — instante a partir do qual o link passa a valer.
• Cada item precisa de quantity ≥ 1.

Detalhes de cada operação (campos, exemplos e respostas) em Payment Links e Checkout Sessions.