Links de pagamento

Um Payment Link é uma página de checkout hospedada e compartilhável (URL com assinatura) para vender

Um Payment Link é uma página de checkout hospedada e compartilhável (URL com assinatura) para vender um ou mais itens. Você cria, consulta, lista, atualiza e remove links como um recurso persistente.

Operação	Método	Endpoint
Criar	POST	`/v1/checkouts/payment-links`
Listar	GET	`/v1/checkouts/payment-links`
Consultar	GET	`/v1/checkouts/payment-links/{paymentLinkId}`
Atualizar	PUT	`/v1/checkouts/payment-links/{paymentLinkId}`
Excluir	DELETE	`/v1/checkouts/payment-links/{paymentLinkId}`

Todas as requisições usam o header SelectKey (veja Autenticação). O ID público de um link tem o prefixo link_.

Criar

POST /v1/checkouts/payment-links

curl -X POST "https://api.selectwin.io/v1/checkouts/payment-links" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday PIX",
    "items": [ { "id": "var_01hqzvabc", "quantity": 1 } ],
    "editable": false,
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome de exibição (1–255 caracteres)
`items[]`	array	Sim	Itens do link: `{ id, quantity }` (1–100 itens). `id` é a variante (`var_...` ou `prv_...`); `quantity` é inteiro ≥ 1 (default `1`, máx. 100000)
`discounts[]`	array	Não	Códigos de cupom pré-aplicados (strings, 1–50 caracteres cada, máx. 20). A validação/retenção autoritativa acontece na cobrança
`customInputs[]`	array	Não	Campos de formulário customizados (objetos livres, máx. 50)
`expiresAt`	datetime	Não	A partir deste instante o link não pode mais ser usado
`availableAt`	datetime	Não	Instante a partir do qual o link passa a valer
`editable`	boolean	Não	Permite o cliente editar quantidades na página (default `false`)
`templateId`	string	Não	Template de checkout para visual (`tmpl_...` ou `ckt_...`)
`metadata`	object	Não	Metadados livres

Não há mais campo type. O antigo link "static" foi removido; existe apenas um tipo de link (persistido). Um type enviado por clientes antigos é silenciosamente ignorado. O binding de domainId/integrationId ainda não é aceito na requisição (esses campos retornam null na resposta); o link usa o domínio de checkout padrão.

Resposta 201 Created

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

Campo	Descrição
`id`	ID público do link (`link_*`).
`type`	Palavra de tipo ecoada do banco (compatibilidade).
`enabled`	Se o link está ativo.
`accessId` / `signature` / `accessFullUrl`	Identificador de acesso, assinatura HMAC e URL pronta para compartilhar.
`sessionId`	Sempre `null` (a vinculação link→sessão é resolvida no fluxo público de abertura).
`templateId`	`tmpl_*` quando há template; senão `null`.
`integrationId` / `domainId`	Sempre `null` (binding ainda não exposto).

accessFullUrl é a URL pronta para compartilhar (já assinada). A assinatura HMAC em signature garante a integridade dos parâmetros do link. As respostas de payment link não incluem merchant nem _links.

Consultar

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

Retorna o objeto completo (mesma forma da criação).

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

Listar

GET /v1/checkouts/payment-links

Lista paginada. Cada item traz o objeto completo do link (mesma forma da consulta individual).

Filtros

Parâmetro	Tipo	Descrição
`limit` / `offset` / `sort`	—	Paginação (`limit` default 20, máx. 100; `offset` default 0). Veja Paginação
`status`	enum	`enabled` ou `disabled`
`daterange*`	—	Filtros por intervalo de datas (`daterange`, `daterangegt`, `daterangegte`, `daterangelt`, `daterangelte`)

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",
      "type": "dynamic",
      "enabled": true,
      "accessId": "acc_01hqzvabc",
      "signature": "f62a0cb72d7a5d55052c96301013e64627133231f90c4614b10d0f50b9887f8d",
      "accessFullUrl": "https://pay.example.com/p/link_01hqzvabc?sign=f62a0cb7...",
      "sessionId": null,
      "editable": false,
      "items": [ { "id": "var_01hqzvabc", "quantity": 1 } ],
      "discounts": [],
      "customInputs": [],
      "expiresAt": "2026-12-31T23:59:59.000Z",
      "availableAt": null,
      "templateId": null,
      "integrationId": null,
      "domainId": null,
      "metadata": {},
      "createdAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "hasMore": false
}

A lista não inclui merchant/_links (envelope plano { offset, limit, total, page, data, hasMore }).

Atualizar

PUT /v1/checkouts/payment-links/{paymentLinkId}

Envie apenas os campos a alterar: name, items, discounts, customInputs, expiresAt, availableAt, editable, templateId, metadata. O corpo é estrito — campos não reconhecidos são rejeitados com 400. Retorna o objeto completo (200 OK), mesma forma da criação.

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

Excluir

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

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

Erros

`error.code`	HTTP	Quando
`invalidParameters`	400	Validação de campos (veja `error.params`)
`checkoutPaymentLinkNotFound`	404	Link não encontrado
`variantIdIsInvalid`	422	Algum `items[].id` referencia uma variante inexistente
`checkoutTemplateIdIsInvalid`	422	`templateId` não existe
`checkoutPaymentLinkCreateFailed`	500	Falha ao criar o link

Catálogo geral: Códigos de Erro.

Links de pagamento

On this page