Visão geral

Checkouts é o recurso que gera payment links: páginas de pagamento hospedadas pela Selectwin, com URL pronta para compartilhar, para vender uma ou mais variantes de produto sem você precisar construir um checkout próprio. Use quando quiser cobrar por link (WhatsApp, e-mail, bio, QR Code) em vez de integrar um formulário de pagamento na sua aplicação.

O recurso oferece dois fluxos de checkout hospedado: o Payment Link — uma URL reutilizável com CRUD completo sob /v1/checkouts/payment-links (detalhado nesta página) — e a Checkout Session — um carrinho hospedado para uma intenção de compra específica, sob /v1/checkouts/sessions. Esta página foca no objeto Payment Link: o que é, como ele funciona por baixo, seu ciclo de vida e onde encontrar cada operação em detalhe.

O que é um Payment Link

Um payment link é um recurso persistente: você o cria uma vez e ele fica disponível para ser consultado, atualizado ou removido. Ao criar, a API:

1. Persiste o link com os items (variantes + quantidades) que você quer vender;
2. Gera um identificador público link_... e um accessId (acc_...);
3. Calcula uma assinatura HMAC SHA256 (signature) sobre os parâmetros do link;
4. Devolve a accessFullUrl — a URL completa, já assinada, pronta para o comprador abrir.

Quando alguém abre essa URL, a página hospedada revalida a assinatura e a janela de validade (availableAt/expiresAt) antes de mostrar o checkout. Isso impede que parâmetros do link sejam adulterados na query string.

"Tokenizar/assinar" aqui significa anexar à URL um código (sign=...) derivado por HMAC do conteúdo do link. Sem a chave secreta da Selectwin é inviável forjar uma URL válida.

Modelo do objeto

JSON de um payment link como retornado por criar, consultar e atualizar (resposta completa):

{
  "id": "link_01hqzvabc",
  "name": "Black Friday PIX",
  "accessId": "acc_01hqzvabc",
  "signature": "f62a0cb72d7a5d55052c96301013e64627133231f90c4614b10d0f50b9887f8d",
  "accessFullUrl": "https://pay.example.com/p/link_01hqzvabc?sign=f62a0cb7",
  "type": "static",
  "sessionId": null,
  "editable": false,
  "customInputs": [],
  "discounts": [],
  "items": [
    { "id": "var_01hqzvabc", "quantity": 1 }
  ],
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "availableAt": null,
  "templateId": null,
  "integrationId": null,
  "domainId": "dmn_abc123",
  "metadata": {},
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Valores monetários em toda a API são inteiros em centavos (9900 = R$ 99,00) e datas são ISO 8601 em UTC. Veja Convenções.

Tipos de link

Janela de validade

Dois campos controlam quando o link aceita pagamentos:

• availableAt — instante a partir do qual o link começa a valer. null significa "válido desde já".
• expiresAt — instante após o qual o link deixa de valer.

A página hospedada verifica essa janela junto com a assinatura. Fora da janela (antes de availableAt ou depois de expiresAt), o comprador recebe um erro de link inválido/expirado em vez do checkout.

Ciclo de vida

Depois de criado, o link permanece válido até você o atualizar (ex.: estender expiresAt), excluir ou até passar de expiresAt. A exclusão devolve uma confirmação { id, resource: "checkout-paymentLink", deleted: true }.

Operações

Base URL: https://api.selectwin.io/v1. Todas as requisições exigem o header SelectKey — veja Autenticação.

A criação e a leitura são detalhadas em Payment Links (campos, exemplos curl e respostas completas).

Filtros da listagem

A listagem aceita paginação e filtros (mais em Paginação):

Relações com outros recursos

• Variantes (var_...) — cada item de items aponta para uma variante de produto que define preço e cobrança. Os valores são herdados da variante.
• Domínios (dmn_...) — domainId define onde o link é hospedado. Alternativamente, passe domain (URL completa) sem domainId.
• Templates de checkout (tmpl_...) — templateId controla o visual da página hospedada.
• Descontos / Cupons — discounts pré-aplica cupons ou regras ao link.
• Integrações — integrationId vincula o link a uma integração configurada.

Conceitos-chave

• Assinatura (HMAC): garante que ninguém altere os parâmetros do link na URL. Você não precisa validá-la — a página hospedada faz isso.
• Idempotência: em escritas (POST/PATCH), envie X-Idempotency-Key para evitar duplicar links em caso de retry. Veja Chave de Idempotência.
• IDs opacos: trate link_..., acc_..., var_..., dmn_... como strings opacas — não dependa do formato interno.

Erros

Os endpoints de checkout retornam o envelope de erro padrão; trate sempre pelo error.code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Guarde o id (link_...), não a accessFullUrl. A URL pode ser regerada; o id é a chave estável para consultar, atualizar ou excluir o link.
• Use expiresAt em campanhas com prazo. Em vez de excluir o link manualmente, deixe-o expirar — assim ninguém paga fora da janela.
• Prefira static para "um link, vários compradores" e dynamic para cobranças individuais de uso único.
• Não exponha a signature nem tente recalculá-la no cliente — a validação é feita na página hospedada.
• Em PATCH, envie só o que muda. O endpoint é parcial; reenviar items substitui a lista inteira de itens.
• Use X-Idempotency-Key ao criar links disparados por ações de usuário, para não gerar duplicatas em retries de rede.
• Para o objeto completo, consulte por id — a listagem traz só uma projeção leve (sem items, signature, metadata).

Veja também

• Payment Links — referência completa de cada operação (criar, listar, consultar, atualizar, excluir).
• Checkout Sessions — carrinho hospedado para uma intenção de compra específica (alternativa ao link reutilizável).
• Autenticação — header SelectKey.
• Convenções — dinheiro em centavos, datas ISO 8601, IDs opacos, camelCase.
• Paginação — limit/offset/sort e filtros de data.
• Chave de Idempotência — escritas seguras contra retry.
• Tratamento de Erros e Códigos de Erro.