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

# Create a payment link

> Cria um link compartilhável. Use type=one_time com amount, ou type=subscription com plan_uuid.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/payment-links
openapi: 3.0.0
info:
  title: PlugToPay API
  description: API to make payments easy in multiple gateways.
  version: 1.0.0
servers:
  - url: http://localhost:7701
    description: Test Server
security: []
paths:
  /api/v1/payment-links:
    post:
      tags:
        - Payment Links
      summary: Create a payment link
      description: >-
        Cria um link compartilhável. Use type=one_time com amount, ou
        type=subscription com plan_uuid.
      parameters:
        - $ref: '#/components/parameters/XClientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                title:
                  type: string
                  maxLength: 255
                  example: Curso Premium
                description:
                  type: string
                  nullable: true
                type:
                  type: string
                  enum:
                    - one_time
                    - subscription
                  description: Imutável depois de criado.
                amount:
                  type: integer
                  minimum: 1
                  nullable: true
                  description: Centavos. Obrigatório em one_time, proibido em subscription.
                plan_uuid:
                  type: string
                  format: uuid
                  nullable: true
                  description: Obrigatório em subscription, proibido em one_time.
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                  example: BRL
                payment_method:
                  type: string
                  enum:
                    - card
                    - pix
                  nullable: true
                  description: Omitir aceita ambos. Forçado para card em assinaturas.
                items:
                  type: array
                  nullable: true
                  items:
                    $ref: '#/components/schemas/PaymentLinkItem'
                slug:
                  type: string
                  minLength: 3
                  maxLength: 100
                  pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
                  nullable: true
                  description: Único por empresa. Habilita a URL legível do checkout.
                success_url:
                  type: string
                  format: uri
                  maxLength: 2048
                  nullable: true
                  description: >-
                    Apenas https; não pode apontar para localhost, .local ou IPs
                    privados.
                cancel_url:
                  type: string
                  format: uri
                  maxLength: 2048
                  nullable: true
                is_active:
                  type: boolean
                expires_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: Precisa ser futura. Sem valor = nunca expira.
              type: object
              required:
                - title
                - type
      responses:
        '201':
          description: Link criado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '401':
          description: Unauthorized — Invalid API Key
        '422':
          description: >-
            Erro de validação (ex.: amount em link de assinatura, slug
            duplicado, URL não-https)
      security:
        - ApiKeyAuth: []
components:
  parameters:
    XClientId:
      name: x-client-id
      in: header
      description: Client identifier for the company in the request.
      required: true
      schema:
        type: string
        example: client_abc123
  schemas:
    PaymentLinkItem:
      type: object
      properties:
        name:
          type: string
          example: Curso Premium
        description:
          type: string
          nullable: true
          example: Acesso vitalício
        quantity:
          type: integer
          minimum: 1
          example: 1
        unit_price:
          type: integer
          description: Preço unitário em centavos
          example: 29900
        image_url:
          type: string
          format: uri
          nullable: true
      required:
        - name
        - quantity
        - unit_price
    PaymentLink:
      type: object
      properties:
        token:
          type: string
          example: pl_live_a1b2c3d4e5f6
        slug:
          type: string
          nullable: true
          example: curso-premium
        title:
          type: string
          example: Curso Premium
        description:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - one_time
            - subscription
        amount:
          type: integer
          nullable: true
          description: Centavos. Nulo em links de assinatura.
          example: 29900
        currency:
          type: string
          example: BRL
        payment_method:
          type: string
          enum:
            - card
            - pix
          nullable: true
          description: Nulo aceita cartão e PIX.
        plan_id:
          type: integer
          nullable: true
        plan_uuid:
          type: string
          format: uuid
          nullable: true
        items:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PaymentLinkItem'
        success_url:
          type: string
          format: uri
          nullable: true
        cancel_url:
          type: string
          format: uri
          nullable: true
        is_active:
          type: boolean
          example: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        checkout_url:
          type: string
          format: uri
          example: https://checkout.plugtopay.com/minha-empresa/curso-premium
        created_at:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Company API key. Send in the X-API-Key header.
      name: X-API-Key
      in: header

````