Criar link de pagamento

Use este endpoint para criar um link de pagamento: uma URL que cobra um valor fixo do comprador. A empresa é identificada pelo header x-api-key — não existe campo companyId no payload.

O slug e a url são gerados pela Bestfy e devolvidos na resposta. Eles nunca mudam, mesmo que você edite o nome ou o valor depois, então é seguro compartilhar a URL assim que o link é criado.

Regras de uso

Todos os campos do payload são obrigatórios. Não existe campo opcional aqui.

Além da validação de formato, o link precisa passar nas regras de negócio:

Ao menos um método de pagamento habilitado, entre pixEnabled, creditCardEnabled e bankSlipEnabled.

O método habilitado precisa estar permitido para a sua empresa. Os toggles do checkout não interferem: o link tem regras próprias.

maxInterestFreeInstallments não pode exceder maxInstallments.

Com cartão habilitado, amountInCents / maxInstallments precisa ser no mínimo 500, ou seja R$ 5,00 por parcela.

Campos do payload

Campo	Regra.
`name`	Nome interno, no máximo 100 caracteres. Não é exibido ao comprador — serve para você localizar o link e aparece como nome do produto na venda. Único por empresa.
`amountInCents`	Valor em centavos (R$ 150,00 = `15000`), de `100` a `100000000`. É o valor final: cupom e desconto por método não se aplicam a link.
`pixEnabled`	Se o link aceita PIX.
`bankSlipEnabled`	Se o link aceita boleto. Opcional: ausente = false
`bankSlipDueDays`	Prazo de vencimento do boleto. Opcional: ausente = 3
`creditCardEnabled`	Se o link aceita cartão de crédito.
`maxInstallments`	Parcelamento máximo no cartão, de 1 a 12. Envie `1` quando o cartão estiver desabilitado.
`maxInterestFreeInstallments`	Parcelas sem juros para o comprador, de 1 a 12 — a taxa é absorvida por você. Acima disso vale a tabela de juros da sua empresa.
`isActive`	Se o link já nasce aceitando pagamento. Criado com `false`, o link existe e tem URL, mas a página não cobra até você ativá-lo.

Sobre o nome ser único: repetir um nome já usado responde 409 com PAYMENT_LINK_E002. Isso torna um retry seguro — se você não recebeu a resposta e repetiu a chamada, a segunda tentativa falha em vez de criar um link duplicado.

O que fazer com a resposta

A resposta 201 devolve o link de pagamento inteiro, não apenas uma mensagem de confirmação. Você não precisa de um GET em seguida para descobrir a URL ou o id: tudo que o link tem no momento da criação já vem aqui.

{
  "id": "0198f3a1-5c2e-7b3a-9f4d-6e1c8a2b7d05",
  "name": "Consultoria 1h",
  "slug": "aB3dE9fGh1k",
  "url": "https://checkout.bestfy.io/pay/aB3dE9fGh1k",
  "amountInCents": 15000,
  "pixEnabled": true,
  "bankSlipEnabled": true,
  "bankSlipDueDays": 1
  "creditCardEnabled": true,
  "maxInstallments": 12,
  "maxInterestFreeInstallments": 3,
  "isActive": true,
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "createdAt": "2026-09-14T12:00:00.000Z",
  "updatedAt": "2026-09-14T12:00:00.000Z"
}

Campo	O que é.
`id`	Identificador do link. É ele que vai no path dos endpoints de buscar, atualizar, ativar/desativar e excluir. Guarde este campo.
`url`	A URL que você entrega ao comprador. Não muda nunca, mesmo depois de editar nome ou valor.
`slug`	O trecho final da `url`, gerado pela Bestfy. Serve para identificar o link em logs e nos webhooks; para cobrar, use a `url` pronta.
`name`	O nome que você enviou, já com espaços das pontas removidos — é por isso que vale ler o valor de volta em vez de assumir o que você mandou.
`amountInCents`, `pixEnabled`, `bankSlipEnabled`, `bankSlipDueDays`, `creditCardEnabled`, `maxInstallments`, `maxInterestFreeInstallments`, `isActive`	A configuração efetiva do link, como ficou gravada.
`companyId`	A empresa dona do link, resolvida a partir da sua `x-api-key`. Útil para conferir a qual conta a chave pertence.
`createdAt` / `updatedAt`	Datas em ISO 8601 UTC. Na criação vêm iguais.

Os dois campos que valem persistir do seu lado são o id e a url: com o id você opera o link depois, e com a url você cobra. O resto você pode sempre reler com o GET.

Erros comuns

Código	Motivo.
`400`	Requisição inválida, por campo ausente ou valor fora dos limites.
`400`	`PAYMENT_LINK_E003` — método de pagamento não permitido para esta empresa.
`400`	`PAYMENT_LINK_E004` — habilite ao menos um método de pagamento no link.
`400`	`PAYMENT_LINK_E005` — parcelas sem juros acima do parcelamento máximo.
`400`	`PAYMENT_LINK_E006` — valor por parcela abaixo do mínimo de R$ 5,00.
`401`	`x-api-key` ausente ou inválida.
`403`	`API_KEY_E001` — chave revogada.
`403`	Links de pagamento não habilitados para a sua conta.
`404`	`COMPANY_E002` — empresa não encontrada para a chave informada.
`409`	`PAYMENT_LINK_E002` — já existe um link de pagamento com este nome.
`429`	Acima de 60 requisições por minuto, contadas por empresa e não por IP.
`500`	Erro interno — tente novamente após alguns segundos.

Atenção ao formato do corpo, porque ele muda conforme a origem do erro. O erro de validação traz message como lista e um campo error, sem code: { "message": ["..."], "error": "Bad Request", "statusCode": 400 }. O erro de regra de negócio traz code e não traz statusCode: { "message": "...", "code": "PAYMENT_LINK_E002" }. Um cliente que decide pelo code precisa tratar a ausência dele.

Criar link de pagamento

Regras de uso#

Campos do payload#

O que fazer com a resposta#

Erros comuns#

Request

Responses

Regras de uso

Campos do payload

O que fazer com a resposta

Erros comuns