> ## 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.

# Criar um link de pagamento

> Operação sobre links de pagamento da conta.

Envie `title` e `line_items` com os IDs dos preços da conta. O link nasce publicado (`status: active`) e a resposta traz `url`, pronto para compartilhar. Use `status: draft` para revisar no painel antes de publicar. Publicar exige conta aprovada para receber pagamentos.

Requer `payment_links:write` ou `write`. O cabeçalho `Idempotency-Key` é obrigatório. Repita a chave apenas para retomar a mesma solicitação; cada edição usa uma chave diferente. Veja [campos, relacionamentos e eventos](https://docs.hubfy.io/api-reference/payment-links/object.md).


## OpenAPI

````yaml api/v1/openapi.yaml POST /v1/payment_links
openapi: 3.1.0
info:
  title: Hubfy API
  version: 1.0.0
  description: >-
    API pública da Hubfy para produtos, preços, arquivos, clientes, pedidos e
    links de pagamento. Autenticação por chave da conta. GET consulta; POST
    cria, atualiza ou executa ações; DELETE remove ou desativa. O ambiente usa
    dados reais, sem sandbox separado. Consulte os fundamentos, os objetos e os
    eventos em https://docs.hubfy.io/api-reference/introduction.
servers:
  - url: https://api.hubfy.io
security:
  - apiKeyAuth: []
tags:
  - name: Produtos
    description: Objeto Product. Campos e relacionamentos na visão geral.
  - name: Preços
    description: Objeto Price. Campos e relacionamentos na visão geral.
  - name: Arquivos
    description: Objeto Asset. Campos e relacionamentos na visão geral.
  - name: Clientes
    description: Objeto Customer. Campos e relacionamentos na visão geral.
  - name: Pedidos
    description: Objeto Order. Campos e relacionamentos na visão geral.
  - name: Links de pagamento
    description: Objeto PaymentLink. Campos e relacionamentos na visão geral.
  - name: Fundamentos da API
    description: Conexão e identificação da API.
paths:
  /v1/payment_links:
    post:
      tags:
        - Links de pagamento
      summary: Criar um link de pagamento
      description: >-
        Envie `title` e `line_items`. O link nasce publicado (`status: active`)
        e a resposta traz `url`; use `status: draft` para revisar no painel
        antes de publicar.


        Um link vende de 1 a 20 preços de produtos distintos, todos avulsos ou
        todos assinaturas com o mesmo período. Publicar (`status: active`) exige
        conta aprovada para receber pagamentos e valida os itens: preços ativos,
        fixos, em reais, sem cobrança por uso, período grátis ou taxa de adesão,
        com total entre R$ 5,00 e R$ 999.999,99. Assinaturas exigem
        `payment_methods: ["credit_card"]` e `max_installments: 1`. `line_items`
        substitui a lista inteira; `metadata` substitui o objeto inteiro. Cada
        abertura de `url` cria uma sessão de compra com as condições vigentes.


        Permissão: `payment_links:write` ou `write`. Consulte a [visão
        geral](/api-reference/payment-links/object) para campos e
        relacionamentos.
      operationId: createPaymentLink
      parameters:
        - name: Idempotency-Key
          in: header
          schema:
            type: string
            minLength: 1
            maxLength: 255
          description: >-
            Chave única por operação lógica, de 1 a 255 caracteres ASCII
            imprimíveis, sem espaços. Reutilize-a somente para repetir a mesma
            operação.
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLinkCreate'
            example:
              line_items:
                - price: prc_1234567890abcdef
                  quantity: 1
              title: Curso de exemplo
      responses:
        '200':
          description: Operação concluída
          headers:
            X-Request-Id:
              description: Identifier of this HTTP request
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
              example:
                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
        '400':
          $ref: '#/components/responses/ApiFailure'
        '401':
          $ref: '#/components/responses/ApiFailure'
        '403':
          $ref: '#/components/responses/ApiFailure'
        '404':
          $ref: '#/components/responses/ApiFailure'
        '409':
          $ref: '#/components/responses/ApiFailure'
        '429':
          $ref: '#/components/responses/ApiFailure'
        '500':
          $ref: '#/components/responses/ApiFailure'
        '502':
          $ref: '#/components/responses/ApiFailure'
        '503':
          $ref: '#/components/responses/ApiFailure'
      security:
        - apiKeyAuth: []
components:
  schemas:
    PaymentLinkCreate:
      type: object
      additionalProperties: false
      required:
        - line_items
        - title
      properties:
        allow_discount_codes:
          description: Permite informar códigos de desconto na página.
          type: boolean
        cancel_url:
          description: Destino HTTPS ao cancelar a compra. null remove.
          format: uri
          type:
            - string
            - 'null'
        checkout_experience:
          additionalProperties: false
          description: >-
            Apresentação, banner, dados exigidos e mensagem final. Campos
            visuais null herdam o padrão.
          properties:
            banner:
              additionalProperties: false
              properties:
                ends_at:
                  format: date-time
                  type:
                    - string
                    - 'null'
                highlight:
                  maxLength: 120
                  type:
                    - string
                    - 'null'
                tag:
                  maxLength: 40
                  type:
                    - string
                    - 'null'
                text:
                  maxLength: 500
                  type: string
                tone:
                  enum:
                    - neutral
                    - urgent
                    - success
                  type: string
                variant:
                  enum:
                    - strip
                    - highlight
                    - countdown
                    - marquee
                  type: string
              type:
                - object
                - 'null'
            confirmation_message:
              maxLength: 1000
              type:
                - string
                - 'null'
            footer_expanded:
              type: boolean
            header_shows_logo:
              type:
                - boolean
                - 'null'
            installment_teaser_mode:
              enum:
                - hidden
                - maximum_installment
                - lowest_installment
                - null
              type:
                - string
                - 'null'
            order_summary_mode:
              enum:
                - expanded
                - collapsible
                - compact
                - hidden
                - null
              type:
                - string
                - 'null'
            product_description_mode:
              enum:
                - hidden
                - summary
                - full
                - null
              type:
                - string
                - 'null'
            product_image_mode:
              enum:
                - hidden
                - thumbnail
                - hero
                - null
              type:
                - string
                - 'null'
            require_billing_address:
              type:
                - boolean
                - 'null'
            require_document:
              type:
                - boolean
                - 'null'
            require_phone:
              type:
                - boolean
                - 'null'
            summary_style:
              enum:
                - product
                - subscription
                - null
              type:
                - string
                - 'null'
          type: object
        discount:
          description: >-
            Desconto disponível na conta de pagamentos. null remove o desconto
            automático.
          pattern: ^disc_[A-Za-z0-9]+$
          type:
            - string
            - 'null'
        has_surcharge:
          description: Repassa tarifas ao comprador. Apenas compras avulsas.
          type: boolean
        interest_payer:
          description: 'Quem absorve os juros do parcelamento: comprador ou conta.'
          enum:
            - buyer
            - organization
          type: string
        line_items:
          description: Substitui a lista inteira de itens. Cada produto aparece uma vez.
          items:
            $ref: '#/components/schemas/PaymentLinkLineItemInput'
          maxItems: 20
          minItems: 1
          type: array
        max_installments:
          description: Máximo de parcelas no cartão.
          maximum: 12
          minimum: 1
          type: integer
          default: 12
        metadata:
          additionalProperties: true
          description: Substitui o objeto inteiro; use {} para limpar.
          type: object
        optional_items:
          description: >-
            Até três ofertas adicionais avulsas, de produtos diferentes dos
            itens principais.
          items:
            additionalProperties: false
            properties:
              call_to_action:
                maxLength: 120
                type: string
              compare_at_amount:
                minimum: 1
                type:
                  - integer
                  - 'null'
              description:
                maxLength: 1000
                type:
                  - string
                  - 'null'
              price:
                type: string
                pattern: ^prc_[a-z0-9]{16}$
              tag:
                enum:
                  - recommended
                  - special_offer
                  - null
                type:
                  - string
                  - 'null'
              title:
                maxLength: 120
                type: string
            type: object
            required:
              - call_to_action
              - price
              - title
          maxItems: 3
          type: array
        payment_method_collection:
          description: >-
            Coleta do cartão nas assinaturas: sempre ou apenas quando houver
            pagamento imediato.
          enum:
            - always
            - if_required
          type: string
        payment_methods:
          description: Meios de pagamento. Assinaturas recorrentes usam credit_card.
          items:
            enum:
              - credit_card
              - pix
              - boleto
            type: string
          maxItems: 2
          minItems: 1
          type: array
        status:
          description: Publicar exige conta aprovada e itens válidos.
          enum:
            - draft
            - active
            - inactive
          type: string
        subscription_data:
          additionalProperties: false
          description: >-
            Condições da assinatura. O link aceita período grátis em dias; data
            final absoluta de trial pertence a sessões individuais.
          properties:
            trial_period_days:
              maximum: 3650
              minimum: 1
              type:
                - integer
                - 'null'
            trial_settings:
              additionalProperties: false
              properties:
                end_behavior:
                  additionalProperties: false
                  properties:
                    missing_payment_method:
                      enum:
                        - cancel
                        - pause
                        - create_invoice
                      type: string
                  type: object
              type: object
          type:
            - object
            - 'null'
        success_url:
          description: >-
            Destino HTTPS após concluir a página; não confirma pagamento. Aceita
            {CHECKOUT_SESSION_ID}.
          type:
            - string
            - 'null'
        template:
          description: Layout da página. null usa o padrão da conta.
          enum:
            - split
            - sidebar
            - stacked
            - null
          type:
            - string
            - 'null'
        title:
          description: Título exibido na página.
          maxLength: 120
          minLength: 1
          type: string
      example:
        line_items:
          - price: prc_1234567890abcdef
            quantity: 1
        title: Curso de exemplo
    PaymentLink:
      type: object
      additionalProperties: false
      required:
        - id
        - allow_discount_codes
        - amount
        - cancel_url
        - checkout_experience
        - created_at
        - currency
        - discount
        - has_surcharge
        - interest_payer
        - line_items
        - max_installments
        - metadata
        - object
        - optional_items
        - payment_method_collection
        - payment_methods
        - recurring
        - status
        - subscription_data
        - success_url
        - template
        - title
        - total_orders
        - updated_at
        - url
      properties:
        id:
          description: >-
            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.
          pattern: ^chk_[a-z0-9]{16}$
          type: string
        allow_discount_codes:
          description: Permite informar códigos de desconto na página.
          type: boolean
        amount:
          description: >-
            Subtotal em centavos, calculado com os preços atuais dos itens.
            Somente leitura.
          minimum: 0
          type: integer
        cancel_url:
          description: Destino HTTPS ao cancelar a compra. null remove.
          format: uri
          type:
            - string
            - 'null'
        checkout_experience:
          additionalProperties: false
          description: >-
            Apresentação, banner, dados exigidos e mensagem final. Campos
            visuais null herdam o padrão.
          properties:
            banner:
              additionalProperties: false
              properties:
                ends_at:
                  format: date-time
                  type:
                    - string
                    - 'null'
                highlight:
                  maxLength: 120
                  type:
                    - string
                    - 'null'
                tag:
                  maxLength: 40
                  type:
                    - string
                    - 'null'
                text:
                  maxLength: 500
                  type: string
                tone:
                  enum:
                    - neutral
                    - urgent
                    - success
                  type: string
                variant:
                  enum:
                    - strip
                    - highlight
                    - countdown
                    - marquee
                  type: string
              type:
                - object
                - 'null'
            confirmation_message:
              maxLength: 1000
              type:
                - string
                - 'null'
            footer_expanded:
              type: boolean
            header_shows_logo:
              type:
                - boolean
                - 'null'
            installment_teaser_mode:
              enum:
                - hidden
                - maximum_installment
                - lowest_installment
                - null
              type:
                - string
                - 'null'
            order_summary_mode:
              enum:
                - expanded
                - collapsible
                - compact
                - hidden
                - null
              type:
                - string
                - 'null'
            product_description_mode:
              enum:
                - hidden
                - summary
                - full
                - null
              type:
                - string
                - 'null'
            product_image_mode:
              enum:
                - hidden
                - thumbnail
                - hero
                - null
              type:
                - string
                - 'null'
            require_billing_address:
              type:
                - boolean
                - 'null'
            require_document:
              type:
                - boolean
                - 'null'
            require_phone:
              type:
                - boolean
                - 'null'
            summary_style:
              enum:
                - product
                - subscription
                - null
              type:
                - string
                - 'null'
          type: object
        created_at:
          type: string
          format: date-time
          description: >-
            Data e hora da criação, em ISO 8601 com fuso horário. Somente
            leitura.
        currency:
          description: Sempre BRL.
          enum:
            - BRL
          type: string
        discount:
          description: >-
            Desconto disponível na conta de pagamentos. null remove o desconto
            automático.
          pattern: ^disc_[A-Za-z0-9]+$
          type:
            - string
            - 'null'
        has_surcharge:
          description: Repassa tarifas ao comprador. Apenas compras avulsas.
          type: boolean
        interest_payer:
          description: 'Quem absorve os juros do parcelamento: comprador ou conta.'
          enum:
            - buyer
            - organization
          type: string
        line_items:
          description: Itens vendidos pelo link, na ordem de exibição.
          items:
            $ref: '#/components/schemas/PaymentLinkLineItem'
          maxItems: 20
          minItems: 1
          type: array
        max_installments:
          description: Máximo de parcelas no cartão. Assinaturas não parcelam.
          maximum: 12
          minimum: 1
          type: integer
          default: 12
        metadata:
          additionalProperties: true
          description: Objeto JSON livre para referências da integração, limitado a 16 KB.
          type: object
        object:
          const: payment_link
          type: string
        optional_items:
          description: >-
            Até três ofertas adicionais avulsas, de produtos diferentes dos
            itens principais.
          items:
            additionalProperties: false
            properties:
              call_to_action:
                maxLength: 120
                type: string
              compare_at_amount:
                minimum: 1
                type:
                  - integer
                  - 'null'
              description:
                maxLength: 1000
                type:
                  - string
                  - 'null'
              price:
                type: string
                pattern: ^prc_[a-z0-9]{16}$
              tag:
                enum:
                  - recommended
                  - special_offer
                  - null
                type:
                  - string
                  - 'null'
              title:
                maxLength: 120
                type: string
            type: object
            required:
              - call_to_action
              - price
              - title
          maxItems: 3
          type: array
        payment_method_collection:
          description: >-
            Coleta do cartão nas assinaturas: sempre ou apenas quando houver
            pagamento imediato.
          enum:
            - always
            - if_required
          type: string
        payment_methods:
          description: Meios de pagamento. Assinaturas recorrentes usam credit_card.
          items:
            enum:
              - credit_card
              - pix
              - boleto
            type: string
          maxItems: 2
          minItems: 1
          type: array
        recurring:
          additionalProperties: false
          description: >-
            Período de renovação quando os itens são assinaturas; null em
            compras avulsas. Somente leitura.
          properties:
            interval:
              enum:
                - day
                - week
                - month
                - year
              type: string
            interval_count:
              minimum: 1
              type: integer
          required:
            - interval
            - interval_count
          type:
            - object
            - 'null'
        status:
          description: >-
            draft não abre compras; active está publicado; inactive foi
            desativado.
          enum:
            - draft
            - active
            - inactive
          type: string
        subscription_data:
          additionalProperties: false
          description: >-
            Condições da assinatura. O link aceita período grátis em dias; data
            final absoluta de trial pertence a sessões individuais.
          properties:
            trial_period_days:
              maximum: 3650
              minimum: 1
              type:
                - integer
                - 'null'
            trial_settings:
              additionalProperties: false
              properties:
                end_behavior:
                  additionalProperties: false
                  properties:
                    missing_payment_method:
                      enum:
                        - cancel
                        - pause
                        - create_invoice
                      type: string
                  type: object
              type: object
          type:
            - object
            - 'null'
        success_url:
          description: >-
            Destino HTTPS após concluir a página; não confirma pagamento. Aceita
            {CHECKOUT_SESSION_ID}.
          type:
            - string
            - 'null'
        template:
          description: Layout da página. null usa o padrão da conta.
          enum:
            - split
            - sidebar
            - stacked
            - null
          type:
            - string
            - 'null'
        title:
          description: Título exibido na página.
          maxLength: 120
          type: string
        total_orders:
          description: Compras confirmadas por este link. Somente leitura.
          minimum: 0
          type: integer
        updated_at:
          type: string
          format: date-time
          description: >-
            Data e hora da última alteração, em ISO 8601 com fuso horário.
            Somente leitura.
        url:
          description: >-
            URL confirmada do checkout hospedado. Pode usar o domínio
            configurado. Não construa a URL a partir do ID.
          type:
            - string
            - 'null'
      example:
        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
    PaymentLinkLineItemInput:
      type: object
      additionalProperties: false
      required:
        - price
      properties:
        adjustable_quantity:
          additionalProperties: false
          description: >-
            Permite alterar quantidade; a quantidade inicial deve estar dentro
            dos limites.
          properties:
            enabled:
              type: boolean
            maximum:
              maximum: 99
              minimum: 1
              type: integer
            minimum:
              maximum: 99
              minimum: 0
              type: integer
          type:
            - object
            - 'null'
        price:
          description: ID de um preço ativo da conta.
          pattern: ^prc_[a-z0-9]{16}$
          type: string
        quantity:
          default: 1
          description: Quantidade vendida, de 1 a 99.
          maximum: 99
          minimum: 1
          type: integer
    PaymentLinkLineItem:
      type: object
      additionalProperties: false
      required:
        - adjustable_quantity
        - price
        - product
        - quantity
        - unit_amount
      properties:
        adjustable_quantity:
          additionalProperties: false
          description: >-
            Permite alterar quantidade; a quantidade inicial deve estar dentro
            dos limites.
          properties:
            enabled:
              type: boolean
            maximum:
              maximum: 99
              minimum: 1
              type: integer
            minimum:
              maximum: 99
              minimum: 0
              type: integer
          type:
            - object
            - 'null'
        price:
          description: ID do preço vendido.
          pattern: ^prc_[a-z0-9]{16}$
          type: string
        product:
          description: ID do produto do preço. Somente leitura.
          pattern: ^pro_[a-z0-9]{16}$
          type: string
        quantity:
          description: Quantidade vendida.
          maximum: 99
          minimum: 1
          type: integer
        unit_amount:
          description: Valor unitário atual do preço, em centavos. Somente leitura.
          minimum: 0
          type: integer
    ApiError:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - doc_url
            - message
            - param
            - type
          properties:
            code:
              type: string
            doc_url:
              type:
                - string
                - 'null'
            message:
              type: string
            param:
              type:
                - string
                - 'null'
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - rate_limit_error
                - api_error
      example:
        error:
          code: invalid_parameter
          doc_url: null
          message: The request contains invalid parameters
          param: null
          type: invalid_request_error
  responses:
    ApiFailure:
      description: A operação não foi concluída
      headers:
        X-Request-Id:
          description: Identifier of this HTTP request
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: invalid_parameter
              doc_url: null
              message: The request contains invalid parameters
              param: null
              type: invalid_request_error
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key

````

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