Link de Pagamento

Um Link de Pagamento é uma página de checkout hospedada pela FastPay com URL pública. Compartilhe o link (WhatsApp, e-mail, bio social) e o comprador finaliza o pagamento sem que você precise implementar um checkout próprio. O link foi refatorado para suportar múltiplos itens vindos do catálogo de Produtos, além de frete e override de preço. Você pode:

Criar um link expresso com um único produto inline (compatível com o fluxo antigo).
Criar um link com produtos do catálogo (items[]) — vários produtos com quantidade.
Definir frete (none, fixed ou checkout).
Sobrescrever o total via priceOverride (ex.: aplicar um desconto).

Modelo do link

Cada link agora carrega três blocos novos no payload de criação e atualização:

Campo	Tipo	Descrição
`items`	`PaymentLinkItem[]`	Produtos do catálogo associados ao link (multi-item).
`freight`	`Freight`	Modo de frete e valor (quando aplicável).
`priceOverride`	number	Sobrescreve o subtotal calculado a partir dos itens.

`PaymentLinkItem`

{
  "productId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "quantity": 2
}

productId — ID de um produto ativo do catálogo do merchant.
quantity — inteiro positivo (≥ 1).

O preço e o tipo de cada item são derivados ao vivo do produto no momento em que a cobrança é criada. Cada cobrança guarda um snapshot, então alterações posteriores no produto não afetam pagamentos já gerados.

Todos os itens de um link precisam ter o mesmo tipo (physical ou digital). A API rejeita um link misto com 422 Unprocessable Entity.

`Freight`

{
  "mode": "fixed",
  "fixedValue": 19.90
}

`mode`	Quando usar
`none`	Sem frete (produto digital ou retirada).
`fixed`	Valor fixo, somado ao total em todas as cobranças do link.
`checkout`	Calculado no checkout via ferramenta de frete conectada ao merchant.

Regras:

Frete só é aceito em links físicos. Links digitais devem usar mode: "none".
fixedValue é obrigatório quando mode = "fixed".
mode: "checkout" exige uma ferramenta de frete ativa no merchant (consulte a disponibilidade — veja Disponibilidade de frete).

`priceOverride`

Quando definido, substitui o subtotal calculado a partir dos itens. Útil para aplicar um desconto fixo, um valor promocional ou consolidar um valor combinado externamente. O frete, quando houver, continua sendo somado ao priceOverride.

Criar um link com produtos

curl -X POST "https://api-global.fastpaybrasil.com/v1/payment-links" \
  -H "Authorization: Basic <seu_token_base64>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "name": "Kit Verão",
    "currency": "BRL",
    "items": [
      { "productId": "2RhQg9M7ZCg3X3nMb9W1kX8Q", "quantity": 2 },
      { "productId": "2RhVx0e8eR4mJ7cD3p2YqXyZ", "quantity": 1 }
    ],
    "freight": { "mode": "fixed", "fixedValue": 19.90 },
    "priceOverride": 199.00
  }'

O backend valida os produtos, calcula o subtotal a partir do catálogo, aplica o priceOverride (se houver) e persiste o frete escolhido.

Atualizar um link

PUT /v1/payment-links/:id aceita os mesmos blocos. Enviar items substitui a lista completa do link. Você pode enviar apenas freight ou apenas priceOverride para alterar somente esses campos.

curl -X PUT "https://api-global.fastpaybrasil.com/v1/payment-links/{id}" \
  -H "Authorization: Basic <seu_token_base64>" \
  -H "Content-Type: application/json" \
  -d '{
    "freight": { "mode": "checkout" },
    "priceOverride": null
  }'

Detalhar um link

GET /v1/payment-links/:id agora retorna os novos campos. Cada item vem com seu imageUrl assinado (URL temporária pronta para o checkout) e com o productType derivado do catálogo.

{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "name": "Kit Verão",
  "currency": "BRL",
  "price": 199.00,
  "items": [
    {
      "productId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
      "name": "Camiseta Preta P",
      "productType": "physical",
      "price": 89.90,
      "quantity": 2,
      "imageUrl": "https://files.fastpaybrasil.com/products/..."
    },
    {
      "productId": "2RhVx0e8eR4mJ7cD3p2YqXyZ",
      "name": "Boné FastPay",
      "productType": "physical",
      "price": 49.90,
      "quantity": 1,
      "imageUrl": null
    }
  ],
  "freight": {
    "mode": "fixed",
    "fixedValue": 19.90
  },
  "priceOverride": 199.00
}

Disponibilidade de frete

Antes de oferecer mode: "checkout" no formulário do link, consulte se o merchant tem uma ferramenta de frete ativa:

curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-links/freight-availability?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -H "Authorization: Basic <seu_token_base64>"

{ "hasFreightTool": true }

Quando hasFreightTool é false, restrinja a UI ao modo fixed ou none até o merchant conectar uma ferramenta de frete.

Cobranças geradas pelo link

Ao gerar uma cobrança a partir de um link, a FastPay:

Calcula o subtotal a partir dos itens (preço × quantidade, lidos ao vivo do catálogo).
Aplica priceOverride se ele estiver definido — caso contrário, usa o subtotal.
Soma o frete (fixed) ou recebe o valor cobrado no checkout (checkout).
Cria a cobrança com freightAmount igual ao valor de frete aplicado.

O campo freightAmount foi adicionado em POST /v1/charges (opcional, ≥ 0). Você só precisa enviá-lo manualmente quando estiver criando cobranças fora do fluxo nativo do link. Em cobranças geradas pelo próprio link, o valor é calculado pela FastPay.

Checkout do comprador

O checkout hospedado foi redesenhado para suportar o novo modelo:

O resumo do pedido mostra cada item (thumb + nome + quantidade + preço).
Quando há frete, surge uma seção Subtotal · Frete · Total.
O formulário de endereço de entrega aparece automaticamente em links físicos e fica oculto em digitais — o tipo é derivado dos items[].
O layout funciona tanto em desktop (resumo à esquerda) quanto em mobile (resumo expansível no topo).

Você não precisa fazer nada para habilitar o novo checkout: ele é exibido automaticamente para todo link com items[] ou produto inline.

Próximos passos

Veja como cadastrar e atualizar produtos em Produtos.
Consulte os schemas detalhados em API Reference.

Introdução

Autenticação

Recursos

Webhooks

Link de Pagamento

Modelo do link

`PaymentLinkItem`

`Freight`

`priceOverride`

Criar um link com produtos

Atualizar um link

Detalhar um link

Disponibilidade de frete

Cobranças geradas pelo link

Checkout do comprador

Próximos passos

​Modelo do link

​PaymentLinkItem

​Freight

​priceOverride

​Criar um link com produtos

​Atualizar um link

​Detalhar um link

​Disponibilidade de frete

​Cobranças geradas pelo link

​Checkout do comprador

​Próximos passos

Modelo do link

`PaymentLinkItem`

`Freight`

`priceOverride`

Criar um link com produtos

Atualizar um link

Detalhar um link

Disponibilidade de frete

Cobranças geradas pelo link

Checkout do comprador

Próximos passos