> ## Documentation Index
> Fetch the complete documentation index at: https://docs.troqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Links de pagamento

> Crie links Pix reutilizáveis no app e acompanhe cada cobrança pelo seu sistema.

# 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

<Steps>
  <Step title="Crie o produto e o link no app">
    Em [app.troqpay.com](https://app.troqpay.com), crie um produto e gere um link de pagamento associado a ele.
  </Step>

  <Step title="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}`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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`).
  </Step>
</Steps>

## Identificadores

<CardGroup cols={2}>
  <Card title="@handle">
    URL pública da loja com todos os links ativos. Exemplo: `https://pay.troqpay.com/@minha-loja`.
  </Card>

  <Card title="paymentLinkId">
    Identificador do link no formato `plink_<16 hex>`. Exibido no app e usado na URL pública.
  </Card>

  <Card title="checkoutId">
    Identificador da cobrança individual gerada quando alguém paga. Formato `chk_<20 hex>`. É esse ID que você usa para consultar e reconciliar.
  </Card>
</CardGroup>

## Estados do link

<CardGroup cols={2}>
  <Card title="Ativo">
    O link aceita pagamentos e cria checkouts a cada uso.
  </Card>

  <Card title="Inativo">
    O link continua acessível na URL, mas a página renderiza um estado não-pagável. Nenhum checkout é criado.
  </Card>
</CardGroup>

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.

<Info>
  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.
</Info>

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

```bash theme={null}
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):

```json theme={null}
{
  "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"
}
```

<Warning>
  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}`.
</Warning>

### 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).

```bash theme={null}
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

```bash theme={null}
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

<Tip>
  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`.
</Tip>

<Info>
  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.
</Info>

## 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

<CardGroup cols={3}>
  <Card title="Checkouts Pix" href="/flows/checkouts-pix">
    Veja a forma do checkout, que é a mesma para criação direta e via link.
  </Card>

  <Card title="Webhooks" href="/flows/webhooks">
    Aprofunde como ouvir os eventos de pagamento — eles funcionam igual para link.
  </Card>

  <Card title="Abrir o app" href="https://app.troqpay.com">
    Crie produtos e links de pagamento direto no app.
  </Card>
</CardGroup>

## Precisa de ajuda para seguir?

<CardGroup cols={3}>
  <Card title="Quickstart" href="/quickstart">
    Se você ainda não fez a primeira cobrança via API, comece pelo Quickstart.
  </Card>

  <Card title="Glossário" href="/glossary">
    Veja o que `paymentLinkId`, `checkoutId` e os outros termos significam.
  </Card>

  <Card title="API Reference" href="/api-reference">
    Consulte os endpoints públicos do checkout que se aplicam aqui também.
  </Card>
</CardGroup>