Links de pagamento

Um Payment Link é uma página de checkout hospedada e compartilhável — uma URL pronta e assinada que você gera para vender uma ou mais variantes de produto sem precisar construir o próprio fluxo de pagamento. Você cria, consulta, lista, atualiza e remove esses links como um recurso persistente, e a API devolve a URL final (accessFullUrl) para você compartilhar com o comprador.

POST · GET · PATCH · DELETE /v1/checkouts/payment-links

Como funciona

Um payment link encapsula o que vender (os items, que são variantes de produto), onde hospedar (domainId ou domain) e quando vale (a janela availableAt → expiresAt). Quando você cria o link, o servidor:

1. Persiste o link e gera um id público com o prefixo link_ (trate-o como opaco — veja Convenções).
2. Assina os parâmetros do link com HMAC SHA256, devolvendo essa assinatura em signature e já embutida na accessFullUrl (no parâmetro de query sign).
3. Devolve a accessFullUrl — a URL final, pronta para compartilhar.

Quando o comprador abre a accessFullUrl, a página hospedada revalida a assinatura e a janela de validade (availableAt/expiresAt) antes de exibir o checkout. Isso garante que ninguém adulterou os parâmetros e que o link só funciona dentro do período permitido.

Tokenizar / assinar: "assinar" aqui significa gerar um código (HMAC) derivado dos parâmetros do link mais um segredo seu. Se alguém mudar um parâmetro na URL, a assinatura deixa de bater e a página recusa o acesso.

Tipos de link: static vs. dynamic

Para links static, sessionId vem null. Para dynamic, ele identifica a sessão associada.

Quando usar (e quando não usar)

Use Payment Links quando você quer cobrar sem hospedar/construir o próprio checkout: basta gerar a URL e compartilhar (WhatsApp, e-mail, bio de rede social, botão "Comprar"). É a forma mais rápida de começar a vender.

Considere outra abordagem quando você já tem um checkout próprio e só precisa processar o pagamento no backend — nesse caso use diretamente o recurso de Transações, que dá controle total sobre o fluxo (sem página hospedada).

Requisição

Headers

Criar — POST /v1/checkouts/payment-links

curl -X POST "https://api.selectwin.io/v1/checkouts/payment-links" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 1f8d2c6a-7b9e-4a1d-8c3f-0e2b4d6f8a10" \
  -d '{
    "type": "static",
    "name": "Black Friday PIX",
    "items": [ { "id": "var_01hqzvabc", "quantity": 1 } ],
    "domainId": "dmn_abc123",
    "editable": false,
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Campos do corpo

*Use domainId quando o domínio já está cadastrado na Selectwin (recomendado). Use domain apenas para informar a URL completa quando não houver domainId.

Resposta da criação

201 Created

{
  "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"
}

Campos-chave da resposta

Consultar — GET /v1/checkouts/payment-links/{paymentLinkId}

Retorna o objeto completo de um link pelo seu ID (link_...) — mesma forma da resposta de criação (com signature, items, metadata, etc.).

curl -X GET "https://api.selectwin.io/v1/checkouts/payment-links/link_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Listar — GET /v1/checkouts/payment-links

Lista os links de forma paginada. Os itens da lista são projeções leves: cada entrada traz só um subconjunto de campos. Para o objeto completo (com items, signature, metadata…), use a consulta individual.

Parâmetros de query

Veja Paginação para o padrão de limit/offset/page.

curl -X GET "https://api.selectwin.io/v1/checkouts/payment-links?limit=20&status=enabled&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK

{
  "offset": 0,
  "limit": 20,
  "total": 3,
  "page": { "current": 1, "total": 1, "offset": { "first": 0, "prev": null, "next": null, "last": 0 } },
  "data": [
    {
      "id": "link_01hqzvabc",
      "name": "Black Friday PIX",
      "accessId": "acc_01hqzvabc",
      "accessFullUrl": "https://pay.example.com/p/link_01hqzvabc?sign=f62a0cb7...",
      "expiresAt": "2026-12-31T23:59:59.000Z",
      "availableAt": null,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "hasMore": false
}

A projeção da lista expõe id, name, accessId, accessFullUrl, expiresAt, availableAt, createdAt e updatedAt — sem items, signature, metadata, merchant ou _links.

Atualizar — PATCH /v1/checkouts/payment-links/{paymentLinkId}

Atualização parcial: envie apenas os campos que mudam. Os campos não enviados permanecem como estão. Retorna o objeto completo atualizado (200 OK).

Campos atualizáveis: name, items, domainId/domain, expiresAt, availableAt, editable, customInputs, discounts, templateId, metadata.

curl -X PATCH "https://api.selectwin.io/v1/checkouts/payment-links/link_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Campanha atualizada", "expiresAt": "2027-01-31T23:59:59Z" }'

Excluir — DELETE /v1/checkouts/payment-links/{paymentLinkId}

Remove um payment link. Após a exclusão, a accessFullUrl deixa de funcionar para novos compradores. A operação é irreversível — para reativar, crie um novo link.

curl -X DELETE "https://api.selectwin.io/v1/checkouts/payment-links/link_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK (confirmação para clientes legados):

{ "id": "link_01hqzvabc", "resource": "checkout-paymentLink", "deleted": true }

Erros

A API retorna um envelope padrão com error.code estável — trate pelo code, nunca pela message. Em falhas de validação, error.params detalha os campos. Veja Tratamento de Erros.

Catálogo completo e os códigos por recurso: Códigos de Erro.

Boas práticas

• Sempre compartilhe a accessFullUrl da resposta. Ela já vem assinada; não remonte a URL nem altere o parâmetro sign — isso quebra a verificação HMAC e o link para de funcionar.
• Use X-Idempotency-Key ao criar. Um timeout de rede num POST sem chave de idempotência pode gerar links duplicados para a mesma campanha.
• Prefira static para campanhas e dynamic para cobranças personalizadas. Use dynamic quando cada link deve valer para uma única sessão/cliente.
• Defina a janela de validade explicitamente. Combine availableAt (quando começa) e expiresAt (quando termina) para promoções com data marcada; deixe null o lado que não precisa de limite.
• Não confie na lista para o objeto completo. A listagem é uma projeção leve — para ler items, signature ou metadata, faça GET .../{paymentLinkId}.
• No PATCH, envie só o que muda. Reenviar o objeto inteiro é desnecessário e arriscado (pode sobrescrever campos sem querer); a atualização é parcial.
• Trate IDs como opacos (link_, dmn_, var_…): armazene a string inteira, não faça parsing nem confie no comprimento.
• Use metadata / externalReference nos customInputs para correlacionar o link e os dados coletados com o seu próprio sistema.

Veja também

• Visão geral de Checkouts — o recurso, o ciclo de vida do link e a assinatura HMAC.
• Convenções da API — camelCase, centavos, ISO 8601, IDs opacos.
• Autenticação — o header SelectKey.
• Idempotência — evitar criações duplicadas.
• Paginação — limit/offset na listagem.
• Códigos de Erro — error.code por recurso.