Skip to main content

​
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

1

Crie o produto e o link no app

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

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}.
3

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.
4

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.

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. A API pública expõe três endpoints REST em /v1/payment-links:
Método e rotaScopeDescrição
POST /v1/payment-linksPAYMENT_LINK:CREATECria um link para um produto existente.
GET /v1/payment-linksPAYMENT_LINK:READLista os links do projeto (paginação por cursor).
GET /v1/payment-links/{paymentLinkId}PAYMENT_LINK:READConsulta 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.
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}.
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>. 
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.
CenárioCaminho 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 compraPOST /v1/checkouts direto
Você quer cobrar em massa via campanha de marketingLink, mais simples de operacionalizar
Você precisa de cobrança por API integrada ao seu fluxoPOST /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.