> ## 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. # Consultar link de pagamento > Retorna um link de pagamento específico. O link é escopado por projeto e ambiente da chave — um link de outro projeto ou ambiente não é visível. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/payment-links/{paymentLinkId} openapi: 3.1.0 info: title: TroqPay API description: >- API da TroqPay para criar cobranças Pix, ler saldo, solicitar saques em produção e processar eventos por webhook. version: 1.0.0 servers: - url: https://api.troqpay.com description: >- Use a mesma URL-base para teste e produção. O ambiente é definido pela chave utilizada (`trq_test_` ou `trq_live_`). security: - bearerAuth: [] tags: - name: Checkouts description: Criação e consulta de cobranças Pix. - name: Payment Links description: >- Criação, listagem e consulta de links de pagamento a partir de produtos cadastrados. - name: Saldo description: >- Leitura do saldo agregado da conta TroqPay (valores em decimal, todos em BRL). - name: Saques description: Criação e consulta de saques em produção. - name: Webhooks description: Eventos enviados pela TroqPay quando um checkout muda de estado. - name: Status description: Endpoints públicos para verificar disponibilidade da API. paths: /v1/payment-links/{paymentLinkId}: get: tags: - Payment Links summary: Consultar link de pagamento description: >- Retorna um link de pagamento específico. O link é escopado por projeto e ambiente da chave — um link de outro projeto ou ambiente não é visível. operationId: getPaymentLink parameters: - name: paymentLinkId in: path required: true description: Identificador do link de pagamento retornado na criação. schema: type: string example: pl_4a8b3c1d5e6f2a9b0c1d - $ref: '#/components/parameters/RequestIdHeader' responses: '200': description: Link de pagamento encontrado. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/PaymentLink' examples: found: summary: Link ativo value: paymentLinkId: pl_4a8b3c1d5e6f2a9b0c1d livemode: false active: true productId: plano-pro amount: 12990 currency: BRL name: Plano Pro description: Assinatura mensal do Plano Pro imageUrl: null paymentCycle: MONTHLY expiresInSeconds: 1800 successUrl: https://loja.example.com/obrigado returnUrl: https://loja.example.com/carrinho createdAt: '2026-04-25T14:00:00.000Z' updatedAt: '2026-04-25T14:00:00.000Z' '401': $ref: '#/components/responses/Unauthorized' '403': description: Chave sem permissão para consultar links de pagamento. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingPermission: summary: Chave sem permissão de leitura de link value: error: type: auth_error code: api_key_scope_forbidden message: >- API key does not have permission to access this resource. requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f '404': description: Link de pagamento não encontrado para este projeto. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: Link inexistente value: error: type: not_found_error code: payment_link_not_found message: Payment link not found for this project. requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f '429': $ref: '#/components/responses/RateLimited' x-codeSamples: - lang: cURL label: cURL source: >- curl https://api.troqpay.com/v1/payment-links/pl_4a8b3c1d5e6f2a9b0c1d \ -H "Authorization: Bearer trq_test_xxx" - lang: JavaScript label: JavaScript source: |- const response = await fetch( "https://api.troqpay.com/v1/payment-links/pl_4a8b3c1d5e6f2a9b0c1d", { headers: { "Authorization": "Bearer trq_test_xxx" } } ); const paymentLink = await response.json(); components: parameters: RequestIdHeader: name: Request-Id in: header required: false description: >- Identificador opcional fornecido pelo cliente para correlação. A API aceita também `X-Request-Id`. O valor é ecoado de volta no header de resposta `Request-Id`. Se nenhum dos dois é enviado, a API gera `req_<24 hex>`. schema: type: string example: req_4a8b3c1d5e6f2a9b0c1d2e3f headers: RequestIdResponseHeader: description: >- Identificador da requisição. Sempre presente. Ecoa o valor enviado em `Request-Id` ou `X-Request-Id`, ou um identificador gerado pela API no formato `req_<24 hex>`. schema: type: string example: req_4a8b3c1d5e6f2a9b0c1d2e3f schemas: PaymentLink: type: object required: - paymentLinkId - livemode - active - productId - amount - currency - name - description - imageUrl - paymentCycle - expiresInSeconds - successUrl - returnUrl - createdAt - updatedAt description: >- Link de pagamento. A resposta **não** inclui uma URL pronta para compartilhar — apenas o `paymentLinkId` e os dados do link/produto. Para uma URL hospedada, use o produto hospedado do app. properties: paymentLinkId: type: string description: Identificador do link de pagamento. example: pl_4a8b3c1d5e6f2a9b0c1d livemode: type: boolean description: '`true` para chaves `trq_live_`; `false` para `trq_test_`.' example: false active: type: boolean description: Indica se o link está ativo. example: true productId: type: string description: Identificador (slug) do produto associado ao link. example: plano-pro amount: type: integer description: Valor do produto em centavos de BRL. example: 12990 currency: type: string description: Moeda do link. Hoje, sempre `BRL`. enum: - BRL example: BRL name: type: string description: Nome do produto associado ao link. example: Plano Pro description: type: - string - 'null' description: Descrição do produto, quando informada. example: Assinatura mensal do Plano Pro imageUrl: type: - string - 'null' description: URL da imagem do produto, quando informada. example: null paymentCycle: type: string description: Ciclo de cobrança do produto associado ao link. example: MONTHLY expiresInSeconds: type: integer description: Tempo de expiração, em segundos, das cobranças geradas pelo link. example: 1800 successUrl: type: - string - 'null' description: URL de redirecionamento após o pagamento, quando definida. example: https://loja.example.com/obrigado returnUrl: type: - string - 'null' description: URL de retorno sem concluir o pagamento, quando definida. example: https://loja.example.com/carrinho createdAt: type: string format: date-time description: Quando o link foi criado. updatedAt: type: string format: date-time description: Quando o link foi atualizado pela última vez. ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' ErrorBody: type: object required: - type - code - message - requestId description: >- Corpo padronizado de erro da API. As mensagens em `message` chegam em inglês — é o que a API emite literalmente. properties: type: type: string description: Categoria do erro. enum: - auth_error - validation_error - business_error - not_found_error - conflict_error - provider_error - rate_limit_error - internal_error example: validation_error code: type: string description: Código estável para tratar a falha no seu backend. example: invalid_request_body message: type: string description: Mensagem legível do erro (em inglês, literal). example: Number must be greater than 0 requestId: type: string description: Identificador da requisição para logs e investigação. example: req_4a8b3c1d5e6f2a9b0c1d2e3f responses: Unauthorized: description: >- Chave ausente, mal formatada, inválida ou revogada. A API sempre devolve `code: "unauthorized"` em 401. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer ausente ou inválido value: error: type: auth_error code: unauthorized message: invalid or missing bearer token requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f RateLimited: description: Limite de requisições excedido. Faça retry com backoff. headers: Request-Id: $ref: '#/components/headers/RequestIdResponseHeader' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: Limite excedido value: error: type: rate_limit_error code: rate_limit_exceeded message: Too many requests. Please retry with backoff. requestId: req_4a8b3c1d5e6f2a9b0c1d2e3f securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key ````