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

# Criar Link de Pagamento

> Cria um novo link de pagamento com checkout pré-configurado e URL única com token de segurança. Suporta `CreditCard`, `PIX` e `Boleto`. Compartilhe o campo `url` da resposta diretamente com o cliente.

O campo `config.image` aceita URL pública HTTPS ou string base64 — processado e armazenado automaticamente (fail-soft: se falhar, o link é criado normalmente sem imagem e a resposta incluirá `image_warning`).

Requer o header `account` com o código da conta.


<Note>
  Requer o header `account` com o código da conta. O link gerado é imediatamente ativo e pode ser compartilhado com clientes.
</Note>

<Tip>
  Para definir uma imagem no checkout, envie `config.image` com uma URL pública ou uma string base64. O servidor processa e armazena automaticamente. Se o processamento falhar, o link é criado normalmente e a resposta incluirá o campo `image_warning`.
</Tip>


## OpenAPI

````yaml POST /v1/payment-links
openapi: 3.1.0
info:
  title: 4Selet Pay API
  description: >
    API de processamento de pagamentos da plataforma 4Selet Pay. Suporta
    cobranças únicas, assinaturas recorrentes, PIX, Cartão de Crédito. Todas as
    rotas autenticadas requerem um Bearer Token obtido via `/v1/login`.
  version: 1.0.0
  contact:
    name: 4Selet Pay
    email: suporte@4selet.com.br
servers:
  - url: https://sandbox.4seletpay.com.br/api
    description: Servidor de Sandbox
security:
  - bearerAuth: []
tags:
  - name: Autenticação
    description: Rotas de autenticação e criação de usuários
  - name: Cobranças
    description: Criação, consulta, cancelamento e reembolso de cobranças
  - name: Pedidos
    description: Consulta de pedidos e gerenciamento de confirmações desafiadas
  - name: Cartões
    description: Cadastro e gerenciamento dos cartões salvos de um cliente
  - name: Assinaturas
    description: Criação e gerenciamento de assinaturas recorrentes
  - name: Faturas
    description: Gerenciamento de faturas e pagamento de faturas em atraso
  - name: Clientes Bloqueados
    description: Gerenciamento de lista negra de clientes
  - name: Contas
    description: Criação e gerenciamento de contas na plataforma
  - name: Aplicativo
    description: Endpoints para dashboard e uso via aplicativo mobile
  - name: Notificações Push
    description: Envio e gerenciamento de notificações push
  - name: Utilitários
    description: Endpoints utilitários como listagem de fusos horários
  - name: Gestão
    description: Relatórios gerenciais (acesso restrito a Super Admins)
  - name: Webhooks
    description: Endpoints para receber notificações de gateways de pagamento
  - name: Endpoints de Webhook
    description: >-
      Gerenciamento de endpoints de webhook para receber notificações de eventos
      da plataforma
  - name: Links de Pagamento
    description: Criação e gerenciamento de links de pagamento com checkout pré-configurado
  - name: Análise de Fraude
    description: >-
      API de Risco — consulta o risco de fraude de uma transação (autenticada
      por chave de API)
paths:
  /v1/payment-links:
    post:
      tags:
        - Links de Pagamento
      summary: Criar link de pagamento
      description: >
        Cria um novo link de pagamento com checkout pré-configurado e URL única
        com token de segurança. Suporta `CreditCard`, `PIX` e `Boleto`.
        Compartilhe o campo `url` da resposta diretamente com o cliente.


        O campo `config.image` aceita URL pública HTTPS ou string base64 —
        processado e armazenado automaticamente (fail-soft: se falhar, o link é
        criado normalmente sem imagem e a resposta incluirá `image_warning`).


        Requer o header `account` com o código da conta.
      operationId: createPaymentLink
      parameters:
        - $ref: '#/components/parameters/AccountHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkRequest'
            examples:
              basico:
                summary: Link básico com PIX e cartão
                value:
                  client:
                    name: Hugo Belo
                    email: hugo@exemplo.com.br
                    phone:
                      ddi: '55'
                      ddd: '62'
                      number: '984063942'
                    document:
                      type: CPF
                      number: '71854312120'
                  items:
                    - id: plano-premium
                      description: Plano Mensal Premium
                      amount: 97.99
                      quantity: 1
                  config:
                    payment_types:
                      - CreditCard
                      - PIX
                    expires_at: '2026-12-31 23:59:59'
                    max_uses: 100
                    pix_discount_value: 10
                    pix_discount_type: percentage
                    redirect_url: https://meusite.com.br/obrigado
              com_parcelamento:
                summary: Link com parcelamento e split
                value:
                  client:
                    name: Ana Lima
                    email: ana@exemplo.com.br
                    phone:
                      ddi: '55'
                      ddd: '11'
                      number: '998765432'
                  items:
                    - id: curso-001
                      description: Curso Completo
                      amount: 497
                      quantity: 1
                  config:
                    payment_types:
                      - CreditCard
                      - PIX
                    installments:
                      - count: 1
                        interest_rate: 1
                      - count: 6
                        interest_rate: 1.1047
                      - count: 12
                        interest_rate: 1.2
                    split:
                      - receiver_code: rec_abc123
                        percentage: 80
                      - receiver_code: rec_xyz456
                        percentage: 20
                    link_name: Curso Completo – Turma Maio 2026
                    soft_descriptor: MeuCurso
      responses:
        '201':
          description: Link de pagamento criado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLinkResponse'
              example:
                mensagem: Link de pagamento criado com sucesso
                erro: false
                mensagenserro: []
                codigoretorno: 201
                id: 00000000-0000-0000-0000-000000000000
                data:
                  code: lnk_abc123xyz
                  order_code: ord_abc123xyz
                  token: >-
                    a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
                  url: >-
                    https://checkout.4seletpay.com.br/lnk_abc123xyz?token=a1b2c3d4e5f6...
                  status: InProgress
                  payment_types:
                    - CreditCard
                    - PIX
                  installments:
                    - count: 1
                      interest_rate: 1
                    - count: 2
                      interest_rate: 1
                  obfuscate_client: false
                  obfuscate_items: false
                  expires_at: '2026-12-31T23:59:59.000000Z'
                  max_uses: 100
                  uses_count: 0
                  split: []
                  value: 97.99
                  created_at: '2026-05-27T10:00:00.000000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  parameters:
    AccountHeader:
      name: account
      in: header
      required: true
      description: Código da conta à qual a operação se aplica
      schema:
        type: string
        example: acc_abc123xyz
  schemas:
    CreatePaymentLinkRequest:
      type: object
      required:
        - items
      description: >
        O objeto `client` é opcional. Se omitido, os dados do pagador serão
        coletados no checkout. Se qualquer campo de `client` for enviado, os
        campos `name`, `email`, `phone` e `document` tornam-se obrigatórios.
      properties:
        client:
          type: object
          required:
            - name
            - email
            - phone
            - document
          properties:
            name:
              type: string
              maxLength: 255
              description: Nome completo do pagador
              example: Hugo Belo
            email:
              type: string
              format: email
              maxLength: 255
              description: E-mail do pagador
              example: hugo@exemplo.com.br
            phone:
              type: object
              required:
                - ddi
                - ddd
                - number
              properties:
                ddi:
                  type: string
                  description: Código do país (DDI)
                  example: '55'
                ddd:
                  type: string
                  description: Código de área (DDD)
                  example: '62'
                number:
                  type: string
                  description: Número do telefone
                  example: '984063942'
            document:
              type: object
              required:
                - type
                - number
              properties:
                type:
                  type: string
                  enum:
                    - CPF
                    - CNPJ
                    - passport
                    - undefined
                  description: Tipo do documento
                  example: CPF
                number:
                  type: string
                  description: >-
                    Número do documento (CPF/CNPJ validado com dígito
                    verificador)
                  example: '71854312120'
            gender:
              type: string
              nullable: true
              enum:
                - Male
                - Female
                - Other
                - Undefined
              description: Gênero (opcional)
            birthdate:
              type: string
              format: date
              nullable: true
              description: Data de nascimento (YYYY-MM-DD, opcional)
              example: '1993-07-07'
            address:
              type: object
              nullable: true
              description: >-
                Endereço (todos os campos obrigatórios entre si quando street é
                enviado)
              properties:
                zipcode:
                  type: string
                  maxLength: 20
                  example: '74715280'
                street:
                  type: string
                  maxLength: 255
                  example: Rua Londrina
                number:
                  type: string
                  maxLength: 20
                  example: sn
                neighborhood:
                  type: string
                  maxLength: 255
                  example: Jd. Novo Mundo
                complement:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: casa
                city:
                  type: string
                  maxLength: 255
                  example: Goiânia
                state:
                  type: string
                  maxLength: 2
                  example: GO
                country:
                  type: string
                  maxLength: 255
                  nullable: true
                  example: BR
        items:
          type: array
          minItems: 1
          description: >-
            Produtos ou serviços incluídos no link. Total mínimo (itens + frete)
            = R$ 5,00.
          items:
            type: object
            required:
              - id
              - description
              - amount
              - quantity
            properties:
              id:
                type: string
                description: Identificador do produto (SKU, UUID ou código)
                example: plano-premium
              description:
                type: string
                maxLength: 255
                description: Descrição exibida no checkout
                example: Plano Mensal Premium
              amount:
                type: number
                format: float
                minimum: 0.01
                maximum: 1000000
                description: Valor unitário em reais (ex. 97.99 = R$ 97,99)
                example: 97.99
              quantity:
                type: integer
                minimum: 1
                description: Quantidade de unidades
                example: 1
        config:
          type: object
          nullable: true
          description: Configurações opcionais do link
          properties:
            payment_types:
              type: array
              nullable: true
              description: >-
                Métodos exibidos no checkout. Se omitido, todos os ativos da
                conta são liberados.
              items:
                type: string
                enum:
                  - CreditCard
                  - PIX
                  - Boleto
              example:
                - CreditCard
                - PIX
            installments:
              type: array
              nullable: true
              description: >
                Opções de parcelamento por milestones. Cada milestone define a
                taxa para todas as parcelas desde o milestone anterior até o
                count informado. interest_rate é um fator multiplicador (1.0 =
                sem juros, 1.10 = 10% de acréscimo).
              items:
                type: object
                required:
                  - count
                  - interest_rate
                properties:
                  count:
                    type: integer
                    minimum: 1
                    maximum: 12
                    description: Número de parcelas (milestone)
                    example: 6
                  interest_rate:
                    type: number
                    format: float
                    minimum: 1
                    description: >-
                      Fator multiplicador (ex. 1.1047 = 10,47% de acréscimo
                      total)
                    example: 1.1047
            expires_at:
              type: string
              format: date-time
              nullable: true
              description: >-
                Data/hora de expiração do link (YYYY-MM-DD HH:MM:SS). Deve ser
                futura. null = sem expiração.
              example: '2026-12-31 23:59:59'
            max_uses:
              type: integer
              nullable: true
              minimum: 1
              description: Número máximo de pagamentos aceitos. null = ilimitado.
              example: 100
            freight:
              type: number
              format: float
              nullable: true
              minimum: 0
              description: Valor do frete em reais adicionado ao total
              example: 15.9
            link_name:
              type: string
              nullable: true
              maxLength: 255
              description: Nome interno do link (não exibido no checkout)
              example: Black Friday – Plano Premium
            order_title:
              type: string
              nullable: true
              maxLength: 255
              description: Título exibido no cabeçalho do checkout
              example: Plano Mensal Premium
            soft_descriptor:
              type: string
              nullable: true
              maxLength: 22
              description: Texto exibido na fatura do cartão de crédito
              example: MinhaLoja
            image:
              type: string
              nullable: true
              description: >
                URL pública HTTPS ou string base64 da imagem exibida no topo do
                checkout. Tem prioridade sobre image_url. Processado
                automaticamente (fail-soft). Formatos aceitos: jpg, png, webp,
                gif.
              example: https://exemplo.com/banner.jpg
            image_url:
              type: string
              nullable: true
              maxLength: 1000
              description: >-
                URL de uma imagem já armazenada. Preterido quando image é
                enviado.
              example: https://storage.exemplo.com/payment-links/images/banner.jpg
            pix_expiration:
              type: integer
              nullable: true
              minimum: 1
              description: Tempo de vida do QR Code PIX em horas
              example: 24
            pix_discount_value:
              type: number
              format: float
              nullable: true
              minimum: 0
              description: Valor do desconto para pagamentos PIX
              example: 10
            pix_discount_type:
              type: string
              nullable: true
              enum:
                - percentage
                - fixed
              description: >
                Tipo do desconto PIX. percentage = percentual sobre o total
                (0–100). fixed = valor fixo em reais. Exige PIX em
                payment_types.
              example: percentage
            obfuscate_client:
              type: boolean
              nullable: true
              description: >-
                Mascarar dados do pagador no checkout (iniciais, e-mail parcial,
                dígitos centrais substituídos)
              example: false
            obfuscate_items:
              type: boolean
              nullable: true
              description: Ocultar nomes e valores dos itens no checkout
              example: false
            back_url:
              type: string
              format: uri
              nullable: true
              maxLength: 1000
              description: URL do botão "Voltar" exibido no checkout
              example: https://meusite.com.br/planos
            redirect_url:
              type: string
              format: uri
              nullable: true
              maxLength: 1000
              description: URL de redirecionamento automático após pagamento confirmado
              example: https://meusite.com.br/obrigado
    PaymentLinkResponse:
      type: object
      properties:
        mensagem:
          type: string
          example: Link de pagamento criado com sucesso
        erro:
          type: boolean
          example: false
        mensagenserro:
          type: array
          items:
            type: string
          example: []
        codigoretorno:
          type: integer
          example: 201
        id:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        data:
          $ref: '#/components/schemas/PaymentLinkData'
    PaymentLinkData:
      type: object
      properties:
        code:
          type: string
          description: Código único do link de pagamento
          example: lnk_abc123xyz
        order_code:
          type: string
          nullable: true
          description: Código do pedido gerado na criação
          example: ord_abc123xyz
        token:
          type: string
          description: Token de segurança do checkout (64 caracteres hex)
          example: a1b2c3d4e5f6...
        url:
          type: string
          nullable: true
          description: URL completa do checkout para compartilhar com o cliente
          example: https://checkout.4seletpay.com.br/lnk_abc123xyz?token=...
        status:
          type: string
          description: Status atual do link
          enum:
            - InProgress
            - Canceled
            - Concluded
          example: InProgress
        payment_types:
          type: array
          items:
            type: string
          description: Métodos de pagamento configurados
          example:
            - CreditCard
            - PIX
        installments:
          type: array
          description: >-
            Opções de parcelamento expandidas (uma entrada por parcela de 1 a
            12)
          items:
            type: object
            properties:
              count:
                type: integer
                example: 1
              interest_rate:
                type: number
                format: float
                example: 1
        obfuscate_client:
          type: boolean
          description: Dados do pagador mascarados no checkout
          example: false
        obfuscate_items:
          type: boolean
          description: Itens ocultos no checkout
          example: false
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: Data/hora de expiração ou null
          example: '2026-12-31T23:59:59.000000Z'
        max_uses:
          type: integer
          nullable: true
          description: Limite máximo de pagamentos ou null se ilimitado
          example: 100
        uses_count:
          type: integer
          description: Quantidade de pagamentos realizados via este link
          example: 0
        value:
          type: number
          format: float
          description: Valor total do link em reais
          example: 97.99
        created_at:
          type: string
          format: date-time
          description: Data de criação (ISO 8601)
          example: '2026-05-27T10:00:00.000000Z'
        image_warning:
          type: string
          nullable: true
          description: >-
            Presente apenas quando o processamento da imagem falhou (fail-soft).
            Descreve o motivo.
          example: 'Não foi possível processar a imagem: URL inacessível.'
    ErrorResponse:
      type: object
      properties:
        mensagem:
          type: string
          example: Um erro inesperado acabou de acontecer.
        erro:
          type: boolean
          example: true
        mensagenserro:
          type: array
          items:
            type: string
          example:
            - Detalhe do erro ocorrido.
        codigoretorno:
          type: integer
          example: 400
        id:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        data:
          type: array
          example: []
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            client.email:
              - O campo client.email é obrigatório.
            payment.type:
              - O campo payment.type é obrigatório.
  responses:
    Unauthorized:
      description: Não autorizado — token inválido ou ausente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            mensagem: Unauthenticated.
            erro: true
            mensagenserro: []
            codigoretorno: 401
            id: 00000000-0000-0000-0000-000000000000
            data: []
    ValidationError:
      description: Erro de validação dos dados enviados
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
          example:
            message: The given data was invalid.
            errors:
              client.email:
                - O campo client.email é obrigatório.
    ServerError:
      description: Erro interno do servidor
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            mensagem: Um erro aconteceu.
            erro: true
            mensagenserro:
              - Erro interno. Tente novamente mais tarde.
            codigoretorno: 500
            id: 00000000-0000-0000-0000-000000000000
            data: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
        Bearer <token>`.

````