Links de pagamento

Um link de pagamento é uma URL pública e reutilizável que você cria no app para um produto da sua conta. Cada vez que alguém abre o link e paga, a TroqPay cria um checkout novo e ele aparece na lista de cobranças com o mesmo contexto de produto. Links de pagamento podem ser criados e consultados no app e também pela API pública (/v1/payment-links). Criação, listagem e consulta estão disponíveis via REST; atualização, exclusão e ativação/desativação continuam só pelo app.

Como funciona

Crie o produto e o link no app

Em app.troqpay.com, crie um produto e gere um link de pagamento associado a ele.

Compartilhe a URL

A URL do produto tem o formato https://pay.troqpay.com/l/{paymentLinkId}. A loja também pode ter uma URL única: https://pay.troqpay.com/@{handle}.

Cada uso vira um checkout

Quando um comprador abre o link e inicia o pagamento, a TroqPay cria um checkout — exatamente igual aos checkouts criados via POST /v1/checkouts.

Reconcilie pelo seu sistema

O checkout criado a partir do link aparece na sua lista de cobranças e dispara os webhooks normalmente (checkout.created, checkout.paid, checkout.expired).

Identificadores

@handle

URL pública da loja com todos os links ativos. Exemplo: https://pay.troqpay.com/@minha-loja.

paymentLinkId

Identificador do link no formato plink_<16 hex>. Exibido no app e usado na URL pública.

checkoutId

Identificador da cobrança individual gerada quando alguém paga. Formato chk_<20 hex>. É esse ID que você usa para consultar e reconciliar.

Estados do link

Ativo

O link aceita pagamentos e cria checkouts a cada uso.

Inativo

O link continua acessível na URL, mas a página renderiza um estado não-pagável. Nenhum checkout é criado.

Você ativa e desativa o link diretamente no app.

API pública de links de pagamento

A API pública expõe três endpoints REST em /v1/payment-links:

Método e rota	Scope	Descrição
`POST /v1/payment-links`	`PAYMENT_LINK:CREATE`	Cria um link para um produto existente.
`GET /v1/payment-links`	`PAYMENT_LINK:READ`	Lista os links do projeto (paginação por cursor).
`GET /v1/payment-links/{paymentLinkId}`	`PAYMENT_LINK:READ`	Consulta um link específico.

Não há endpoints de atualização, exclusão ou ativação/desativação via API — essas ações continuam só no app.

Os scopes PAYMENT_LINK:CREATE e PAYMENT_LINK:READ são emitidos por padrão em toda chave nova (test e live). Chaves criadas antes do lançamento desses scopes não os possuem e recebem 403 api_key_scope_forbidden nessas rotas até serem reemitidas no app.

Criar um link

POST /v1/payment-links exige o header Idempotency-Key — o paymentLinkId é derivado dela de forma estável, então re-tentativas com a mesma chave devolvem o mesmo link (sem duplicar). No corpo, productId é obrigatório; expiresInSeconds, successUrl e returnUrl são opcionais.

curl -X POST https://api.troqpay.com/v1/payment-links \
  -H "Authorization: Bearer trq_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: link_plano_pro_001" \
  -d '{
    "productId": "plano-pro",
    "expiresInSeconds": 1800,
    "successUrl": "https://minha-loja.com/obrigado",
    "returnUrl": "https://minha-loja.com/planos"
  }'

Exemplo de resposta (201 Created na primeira chamada; 200 OK em reentrega idempotente):

{
  "paymentLinkId": "plink_4a8b3c1d5e6f2a9b",
  "livemode": false,
  "active": true,
  "productId": "plano-pro",
  "amount": 12990,
  "currency": "BRL",
  "name": "Plano Pro",
  "description": "Assinatura mensal do Plano Pro",
  "imageUrl": null,
  "paymentCycle": "ONE_TIME",
  "expiresInSeconds": 1800,
  "successUrl": "https://minha-loja.com/obrigado",
  "returnUrl": "https://minha-loja.com/planos",
  "createdAt": "2026-04-25T14:00:00.000Z",
  "updatedAt": "2026-04-25T14:00:00.000Z"
}

A resposta não inclui um campo url. Monte a URL pública você mesmo a partir do paymentLinkId: https://pay.troqpay.com/l/{paymentLinkId}.

Listar links

GET /v1/payment-links aceita os parâmetros de query limit (1 a 100, padrão 24) e cursor (opaco, para a próxima página).

curl https://api.troqpay.com/v1/payment-links?limit=24 \
  -H "Authorization: Bearer trq_test_xxx"

A resposta traz data (lista de links no mesmo formato acima), hasMore e nextCursor. Para a próxima página, repita a chamada passando cursor=<nextCursor>.

Consultar um link

curl https://api.troqpay.com/v1/payment-links/plink_4a8b3c1d5e6f2a9b \
  -H "Authorization: Bearer trq_test_xxx"

O link é escopado pelo projeto e ambiente da chave: um link de outro projeto ou ambiente devolve 404 payment_link_not_found.

Reconciliação dos checkouts

Quando alguém paga, o link cria um checkout normal:

ele aparece em GET /v1/checkouts/{checkoutId} como qualquer outro checkout
dispara os webhooks de ciclo de vida (checkout.created, checkout.paid, checkout.expired) normalmente

Checkouts criados a partir de um link de pagamento carregam metadados internos que ligam o checkout ao link. Esses metadados são usados pela TroqPay para o produto/painel; você não precisa lê-los para reconciliar — use o checkout.id.

Reenvios da mesma tentativa de pagamento são deduplicados para evitar checkouts duplicados em clique duplo ou retry de rede. Uma nova tentativa do comprador cria um novo checkout.

Quando usar link em vez de criar via API

Cenário	Caminho recomendado
Você tem um produto fixo e quer compartilhar uma URL única (newsletter, link na bio)	Crie um link no app ou via `POST /v1/payment-links`
Você precisa de cobrança dinâmica com valor, descrição ou metadata por compra	`POST /v1/checkouts` direto
Você quer cobrar em massa via campanha de marketing	Link, mais simples de operacionalizar
Você precisa de cobrança por API integrada ao seu fluxo	`POST /v1/checkouts`

Próximos passos

Checkouts Pix

Veja a forma do checkout, que é a mesma para criação direta e via link.

Webhooks

Aprofunde como ouvir os eventos de pagamento — eles funcionam igual para link.

Abrir o app

Crie produtos e links de pagamento direto no app.

Precisa de ajuda para seguir?

Quickstart

Se você ainda não fez a primeira cobrança via API, comece pelo Quickstart.

Glossário

Veja o que paymentLinkId, checkoutId e os outros termos significam.

API Reference

Consulte os endpoints públicos do checkout que se aplicam aqui também.

Fluxos do produto

Mais recursos

Links de pagamento

Links de pagamento

Como funciona

Identificadores

@handle

paymentLinkId

checkoutId

Estados do link

Ativo

Inativo

API pública de links de pagamento

Criar um link

Listar links

Consultar um link

Reconciliação dos checkouts

Quando usar link em vez de criar via API

Próximos passos

Checkouts Pix

Webhooks

Abrir o app

Precisa de ajuda para seguir?

Quickstart

Glossário

API Reference

​Links de pagamento

​Como funciona

​Identificadores

@handle

paymentLinkId

checkoutId

​Estados do link

Ativo

Inativo

​API pública de links de pagamento

​Criar um link

​Listar links

​Consultar um link

​Reconciliação dos checkouts

​Quando usar link em vez de criar via API

​Próximos passos

Checkouts Pix

Webhooks

Abrir o app

​Precisa de ajuda para seguir?

Quickstart

Glossário

API Reference

Links de pagamento

Como funciona

Identificadores

Estados do link

API pública de links de pagamento

Criar um link

Listar links

Consultar um link

Reconciliação dos checkouts

Quando usar link em vez de criar via API

Próximos passos

Precisa de ajuda para seguir?