1. Links de pagamento
Bestfy API
  • Sobre a Bestfy
    • Comece aqui
  • Webhooks
    • O que é um Webhook?
  • Tokenização
    • O que é Tokenização?
    • Criar token de cartão
      POST
  • Status de transação
    • Status de Pagamento na Bestfy
  • Transações
    • Anotações
      • Criar anotações
      • Listar anotações
      • Buscar anotação
      • Editar anotação
      • Remover anotação
    • Criar transações
      POST
    • Estornar transação
      POST
    • Buscar transação
      GET
    • Listar transações
      GET
    • Atualizar status de rastreio
      PATCH
    • Obter Token 3DS
      GET
    • Obter configurações do 3DS
      GET
  • Links de pagamento
    • Listar links de pagamento
      GET
    • Criar link de pagamento
      POST
    • Buscar link de pagamento
      GET
    • Atualizar link de pagamento
      PUT
    • Ativar ou desativar link de pagamento
      PATCH
    • Excluir link de pagamento
      DELETE
  • Saldo
    • Buscar saldo
      GET
  • API Key
    • Validar API Key
      GET
  1. Links de pagamento

Listar links de pagamento

GET
https://api.bestfy.io/public-api/payment-link
Use este endpoint para listar os links de pagamento da sua empresa, com paginação e busca por nome. A empresa é identificada pelo header x-api-key — você nunca informa a companyId, e nunca é possível enxergar link de outra empresa.
Um link de pagamento é uma URL de valor fixo que você compartilha com o comprador. Ele paga por PIX ou cartão de crédito e a venda entra no seu dashboard como uma transação comum, com os mesmos webhooks de status. A página de pagamento em si é pública e não exige chave: quem precisa da x-api-key é a gestão dos links, ou seja, estes endpoints.

Regras de uso#

Todos os parâmetros são opcionais e vão na query string. Sem nenhum deles, o endpoint devolve a primeira página com 10 links.
page: número da página, começando em 1. Default 1.
limit: quantidade de links por página. Default 10, máximo 40.
search: filtra pelo nome do link. Busca parcial, sem diferenciar maiúsculas de minúsculas.
Um limit acima de 40 é recusado com 400, não truncado silenciosamente.

Ordenação e escopo#

Os links vêm do mais recente para o mais antigo, por data de criação.
Links inativos aparecem na listagem. Desativar não esconde o link daqui, só impede novos pagamentos — use isActive para distinguir.
Links excluídos não aparecem. A exclusão é lógica: o link sai da listagem, mas as vendas já feitas continuam vinculadas a ele no seu dashboard.

Campos da resposta#

O total é o total de links que atendem ao filtro, não o tamanho da página. Use com o limit para saber quantas páginas existem. Os links vêm em data, cada um com os campos abaixo.
CampoDescrição.
idIdentificador do link, no formato UUID. É o que você usa nos endpoints de buscar, atualizar, ativar/desativar e excluir.
nameNome interno do link. Não é exibido ao comprador — serve para você localizar o link e aparece como nome do produto na venda.
slugIdentificador do link na URL pública, gerado pelo sistema. Nunca muda.
urlURL completa para compartilhar. Vem no seu domínio customizado quando você tem um ativo, e no domínio compartilhado da Bestfy caso contrário.
amountInCentsValor cobrado em centavos (R$ 150,00 = 15000). É o valor final: cupom e desconto por método não se aplicam a link.
pixEnabledSe o link oferece PIX.
bankSlipEnabledSe o link oferece boleto.
bankSlipDueDaysPrazo de vencimento do boleto.
creditCardEnabledSe o link oferece cartão de crédito.
maxInstallmentsParcelamento máximo oferecido no cartão.
maxInterestFreeInstallmentsParcelas sem juros para o comprador — a taxa é absorvida por você.
isActiveSe o link aceita pagamento neste momento.
companyIdIdentificador da sua empresa, no formato UUID.
createdAt, updatedAtDatas em ISO 8601, em UTC.
O método só é efetivamente oferecido ao comprador quando o flag do link está ligado e o método está liberado para a sua empresa. Um link com pixEnabled: true pode não oferecer PIX na página se o PIX não estiver habilitado para a empresa.

Paginação#

Para varrer todos os links, incremente page até somar total registros, usando limit=40 para reduzir o número de chamadas.
Como a ordenação é por data de criação decrescente, criar um link novo no meio de uma varredura desloca os itens para as páginas seguintes. Se a consistência importar, prefira varrer do fim para o começo ou deduplicar pelo id.

Erros comuns#

CódigoMotivo.
400PAGINATION_E001 — page ou limit não é um número.
400PAGINATION_E002 — page ou limit menor que 1.
400PAGINATION_E003 — limit maior que o máximo permitido, que é 40.
401x-api-key ausente ou inválida.
403API_KEY_E001 — chave revogada.
403Links de pagamento não habilitados para a sua conta.
404COMPANY_E002 — empresa não encontrada para a chave informada.
429Acima de 60 requisições por minuto, contadas por empresa e não por IP.
500Erro interno — tente novamente após alguns segundos.
Os erros de paginação seguem o formato { "message": "...", "code": "PAGINATION_E003" }, sem o campo statusCode. Os erros de api-key incluem statusCode no corpo.

Request

Header Params

Responses

🟢200Resposta para listagem bem sucedida
application/json
Bodyapplication/json

🟠401Chave ausente/inválida
🟠403Link de pagamento não habilitador para a conta dona da chave
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.bestfy.io/public-api/payment-link' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json'
Response Response Example
200 - Success
{
    "total": 1,
    "data": [
        {
            "id": "d8aa86fa-056c-4943-b926-e60ca359c9e0",
            "name": "Consultoria 1h",
            "slug": "aB3dE9fGh1k",
            "amountInCents": 15000,
            "pixEnabled": true,
            "bankSlipEnabled": false,
            "bankSlipDueDays": 3,
            "creditCardEnabled": true,
            "maxInstallments": 12,
            "maxInterestFreeInstallments": 1,
            "isActive": true,
            "companyId": "8a64bb7a-4d0a-4d8a-83a5-8aa6fec72a82",
            "createdAt": "2026-01-23T21:43:32.526Z",
            "updatedAt": "2026-09-10T12:04:05.823Z",
            "url": "https://checkout.bestfy.io/pay/aB3dE9fGh1k"
        }
    ]
}
Modified at 2026-09-16 12:59:37
Previous
Obter configurações do 3DS
Next
Criar link de pagamento
Built with