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

# Links de pagamento

> Objeto payment_link: configuração e URL de checkout hospedado.

A Hubfy administra os produtos e publica um link hospedado pelo serviço de pagamentos. Cada abertura cria uma sessão independente. Compartilhe exatamente a `url` retornada: domínio e caminho podem variar. O ID `chk_` identifica a oferta dentro da Hubfy.

Por exemplo, publique um curso de R\$ 99 com Pix e cartão e envie a URL retornada ao comprador. Concluir a página de Pix não confirma o pagamento: a entrega depende da confirmação financeira recebida pela Hubfy.

## Objeto completo

```json theme={null}
{
  "id": "chk_1234567890abcdef",
  "allow_discount_codes": false,
  "amount": 4990,
  "cancel_url": null,
  "checkout_experience": {
    "banner": null,
    "confirmation_message": "Sua compra foi confirmada. Enviaremos as instruções de acesso por email.",
    "footer_expanded": false,
    "header_shows_logo": null,
    "installment_teaser_mode": null,
    "order_summary_mode": null,
    "product_description_mode": null,
    "product_image_mode": null,
    "require_billing_address": null,
    "require_document": null,
    "require_phone": null,
    "summary_style": null
  },
  "created_at": "2030-01-01T00:00:00.000Z",
  "currency": "BRL",
  "discount": null,
  "has_surcharge": false,
  "interest_payer": "buyer",
  "line_items": [
    {
      "adjustable_quantity": null,
      "price": "prc_1234567890abcdef",
      "product": "pro_1234567890abcdef",
      "quantity": 1,
      "unit_amount": 4990
    }
  ],
  "max_installments": 1,
  "metadata": {},
  "object": "payment_link",
  "optional_items": [],
  "payment_method_collection": "always",
  "payment_methods": [
    "credit_card",
    "pix"
  ],
  "recurring": null,
  "status": "active",
  "subscription_data": null,
  "success_url": null,
  "template": null,
  "title": "Curso de exemplo",
  "total_orders": 0,
  "updated_at": "2030-01-01T00:00:00.000Z",
  "url": "https://checkout.example.com/pay/link-example"
}
```

## Campos

**id** `string`

Identificador público estável, com prefixo chk\_. É o mesmo ID do checkout no painel. Use a URL retornada; não construa o endereço a partir do ID.

**allow\_discount\_codes** `boolean`

Permite informar códigos de desconto na página.

**amount** `integer`

Subtotal em centavos, calculado com os preços atuais dos itens. Somente leitura.

**cancel\_url** `string`

Destino HTTPS ao cancelar a compra. null remove.

**checkout\_experience** `object`

Apresentação, banner, dados exigidos e mensagem final. Campos visuais null herdam o padrão.

**created\_at** `string`

Data e hora da criação, em ISO 8601 com fuso horário. Somente leitura.

**currency** `string`

Sempre BRL.

**discount** `string`

Desconto disponível na conta de pagamentos. null remove o desconto automático.

**has\_surcharge** `boolean`

Repassa tarifas ao comprador. Apenas compras avulsas.

**interest\_payer** `string`

Quem absorve os juros do parcelamento: comprador ou conta.

**line\_items** `array`

Itens vendidos pelo link, na ordem de exibição.

**max\_installments** `integer`

Máximo de parcelas no cartão. Assinaturas não parcelam.

**metadata** `object`

Objeto JSON livre para referências da integração, limitado a 16 KB.

**object** `string`

Informação retornada pela oferta.

**optional\_items** `array`

Até três ofertas adicionais avulsas, de produtos diferentes dos itens principais.

**payment\_method\_collection** `string`

Coleta do cartão nas assinaturas: sempre ou apenas quando houver pagamento imediato.

**payment\_methods** `array`

Meios de pagamento. Assinaturas recorrentes usam credit\_card.

**recurring** `object,null`

Período de renovação quando os itens são assinaturas; null em compras avulsas. Somente leitura.

**status** `string`

draft não abre compras; active está publicado; inactive foi desativado.

**subscription\_data** `object`

Condições da assinatura. O link aceita período grátis em dias; data final absoluta de trial pertence a sessões individuais.

**success\_url** `string,null`

Destino HTTPS após concluir a página; não confirma pagamento. Aceita {CHECKOUT_SESSION_ID}.

**template** `string`

Layout da página. null usa o padrão da conta.

**title** `string`

Título exibido na página.

**total\_orders** `integer`

Compras confirmadas por este link. Somente leitura.

**updated\_at** `string`

Data e hora da última alteração, em ISO 8601 com fuso horário. Somente leitura.

**url** `string`

URL confirmada do checkout hospedado. Pode usar o domínio configurado. Não construa a URL a partir do ID.

## Escrita

A criação exige `title`, `line_items` e o cabeçalho `Idempotency-Key`. Reutilize a mesma chave apenas para repetir a mesma solicitação. Para alterações, envie uma chave diferente. Um rascunho pode ter `url: null`; publicar exige ativação aprovada. Produtos e preços precisam pertencer à conta. Compras avulsas e assinaturas não se misturam nos itens principais.

`checkout_experience` é mesclado por campo nas atualizações. As listas `line_items` e `optional_items` são substituídas por inteiro. Itens adicionais usam preço avulso positivo e geram seus próprios acessos. O título, a capa e a descrição dos produtos vêm do catálogo.

Não há campos `appearance`, `cover_url`, `description`, `collect_phone`, `collect_address`, `confirmation_message` ou `expires_at` no nível principal. Use `checkout_experience` para a coleta de dados e a mensagem final. Links reutilizáveis não expiram por data; desative a oferta para encerrar vendas.

Cores, fontes, tema e cantos da conta são administrados em Configurações → Branding. Logos completos, rodapé, domínio e padrões da plataforma são configuração operacional.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.