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

# Create a payment link

> OAuth scope: `payment_link.write`

Create a payment link for collecting payments from your customers. 

This endpoint supports two types of payment links:

**Basket payment links** (`CreateBasketPaymentLink`):
- Include an `items` array with detailed item information, unit prices, and VAT rates
- Use the `reusable` field to control whether the link can be used multiple times
- Required fields: `items`, `reusable`, `potential_payment_methods`

**Invoice payment links** (`CreateInvoicePaymentLink`):
- Include `invoice_id`, `invoice_number`, `debitor_name`, and `amount` fields
- Specifically designed for invoice payments
- Required fields: `invoice_id`, `invoice_number`, `debitor_name`, `amount`, `potential_payment_methods`




## OpenAPI

````yaml post /v2/payment_links
openapi: 3.1.1
info:
  version: v2
  title: Qonto
servers:
  - url: https://thirdparty.qonto.com
    description: Production URL
  - url: https://thirdparty-sandbox.staging.qonto.co
    description: Sandbox URL
security:
  - OAuth:
      - organization.read
      - membership.read
      - membership.write
      - attachment.write
      - internal_transfer.write
      - payment.write
      - supplier_invoice.write
      - supplier_invoice.read
      - client_invoices.read
      - client_invoice.write
      - client.read
      - client.write
      - product.read
      - product.write
      - request_review.write
      - request_review.read
      - team.read
      - team.write
      - request_transfers.write
      - insurance_contract.read
      - insurance_contract.write
      - card.read
      - card.write
      - bank_account.write
      - beneficiary.trust
      - webhook
      - payment_link.write
      - payment_link.read
      - sepa_direct_debit.read
      - sepa_direct_debit.write
      - terminal.read
      - terminal.write
  - SecretKey: []
paths:
  /v2/payment_links:
    parameters:
      - $ref: '#/components/parameters/X-Qonto-Staging-Token'
    post:
      tags:
        - Payment Links
      summary: Create a payment link
      description: >
        OAuth scope: `payment_link.write`


        Create a payment link for collecting payments from your customers. 


        This endpoint supports two types of payment links:


        **Basket payment links** (`CreateBasketPaymentLink`):

        - Include an `items` array with detailed item information, unit prices,
        and VAT rates

        - Use the `reusable` field to control whether the link can be used
        multiple times

        - Required fields: `items`, `reusable`, `potential_payment_methods`


        **Invoice payment links** (`CreateInvoicePaymentLink`):

        - Include `invoice_id`, `invoice_number`, `debitor_name`, and `amount`
        fields

        - Specifically designed for invoice payments

        - Required fields: `invoice_id`, `invoice_number`, `debitor_name`,
        `amount`, `potential_payment_methods`
      operationId: createPaymentLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkRequest'
      responses:
        '201':
          description: The payment link has been created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentLinkResponse'
        '400':
          $ref: '#/components/responses/400-Bad-request'
        '401':
          $ref: '#/components/responses/401-Unauthorized'
        '500':
          $ref: '#/components/responses/500-Internal-Server-Error'
      security:
        - OAuth:
            - payment_link.write
components:
  parameters:
    X-Qonto-Staging-Token:
      name: X-Qonto-Staging-Token
      in: header
      description: >-
        Required only for Sandbox API requests; to get one, please sign up to
        the [Developer Portal](https://developers.qonto.com/).
      schema:
        type: string
  schemas:
    CreatePaymentLinkRequest:
      oneOf:
        - $ref: '#/components/schemas/CreateBasketPaymentLink'
        - $ref: '#/components/schemas/CreateInvoicePaymentLink'
    CreatePaymentLinkResponse:
      type: object
      required:
        - payment_link
      properties:
        payment_link:
          $ref: '#/components/schemas/PaymentLink'
    CreateBasketPaymentLink:
      type: object
      title: CreateBasketPaymentLink
      required:
        - payment_link
      properties:
        payment_link:
          type: object
          required:
            - potential_payment_methods
            - reusable
            - items
          properties:
            potential_payment_methods:
              type: array
              description: The payment methods that can be used to pay the payment link.
              items:
                type: string
                enum:
                  - credit_card
                  - apple_pay
                  - paypal
                  - ideal
                minItems: 1
                example: credit_card
            reusable:
              type: boolean
              description: Whether the payment link can be reused.
              default: false
              example: true
            items:
              type: array
              description: Items that make up the payment link.
              minItems: 1
              items:
                type: object
                required:
                  - title
                  - quantity
                  - unit_price
                  - vat_rate
                properties:
                  title:
                    type: string
                    description: The title of the item.
                    example: Item 1
                  type:
                    type: string
                    description: The type of the item.
                    enum:
                      - good
                      - service
                    example: good
                  description:
                    type: string
                    description: The description of the item.
                    example: Item 1 description
                  quantity:
                    type: number
                    format: double
                    description: The quantity of the item.
                    example: 1
                  measure_unit:
                    type: string
                    description: The unit of measure of the item.
                    example: unit
                  unit_price:
                    type: object
                    required:
                      - value
                      - currency
                    properties:
                      value:
                        type: string
                        description: >-
                          The amount of the item, formatted as a decimal string,
                          with 2 decimal places at most.
                        example: '10.99'
                      currency:
                        type: string
                        description: >-
                          The currency of the item, formatted as an ISO 4217
                          currency code.
                        example: EUR
                  vat_rate:
                    type: string
                    description: The VAT rate of the item, formatted as a decimal string.
                    example: '21.0'
    CreateInvoicePaymentLink:
      type: object
      title: CreateInvoicePaymentLink
      required:
        - payment_link
      properties:
        payment_link:
          type: object
          required:
            - invoice_id
            - invoice_number
            - debitor_name
            - amount
            - potential_payment_methods
          properties:
            invoice_id:
              type: string
              format: uuid
              description: The ID of the invoice.
              example: 550e8400-e29b-41d4-a716-446655440001
            invoice_number:
              type: string
              description: The invoice number for reference.
              example: INV-12345
            debitor_name:
              type: string
              description: Name of the customer/debitor.
              example: John Doe
            amount:
              type: object
              description: Total amount for the invoice payment link.
              required:
                - currency
                - value
              properties:
                currency:
                  type: string
                  description: >-
                    Currency of the amount, formatted as an ISO 4217 currency
                    code.
                  example: EUR
                value:
                  type: string
                  description: Value of the amount, formatted as a decimal string.
                  example: '100.00'
            potential_payment_methods:
              type: array
              description: The payment methods that can be used to pay the payment link.
              items:
                type: string
                enum:
                  - credit_card
                  - apple_pay
                  - paypal
                  - ideal
                minItems: 1
                example: credit_card
    PaymentLink:
      type: object
      required:
        - id
        - status
        - expiration_date
        - potential_payment_methods
        - amount
        - created_at
        - url
        - resource_type
        - reusable
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the payment link.
        status:
          type: string
          description: The status of the payment link.
          enum:
            - open
            - expired
            - canceled
            - paid
            - processing
          example: open
        expiration_date:
          type: string
          format: date-time
          description: >-
            The date and time when the payment link will expire, formatted as an
            ISO 8601 date-time string.
          example: '2021-01-01T00:00:00Z'
        potential_payment_methods:
          type: array
          items:
            type: string
            enum:
              - credit_card
              - apple_pay
              - paypal
              - ideal
            example: credit_card
        amount:
          type: object
          description: The gross amount of the payment link, including VAT.
          required:
            - value
            - currency
          properties:
            value:
              type: string
              description: The amount of the payment link, formatted as a decimal string.
              example: '13.30'
            currency:
              type: string
              description: >-
                The currency of the payment link, formatted as an ISO 4217
                currency code.
              example: EUR
        resource_type:
          type: string
          description: Type of payment link resource.
          enum:
            - Invoice
            - Basket
          example: Basket
        items:
          type:
            - array
            - 'null'
          description: Items for basket payment links. Null for invoice payment links.
          items:
            type: object
            required:
              - title
              - quantity
              - unit_price
              - vat_rate
            properties:
              title:
                type: string
                description: The title of the item.
                example: Item 1
              type:
                type: string
                description: The type of the item.
                enum:
                  - good
                  - service
                example: good
              description:
                type: string
                description: The description of the item.
                example: Item 1 description
              quantity:
                type: number
                format: double
                description: The quantity of the item.
                example: 1
              measure_unit:
                type: string
                description: The unit of measure of the item.
                example: unit
              unit_price:
                type: object
                required:
                  - value
                  - currency
                properties:
                  value:
                    type: string
                    description: The amount of the item.
                    example: '10.99'
                  currency:
                    type: string
                    description: >-
                      The currency of the item, formatted as an ISO 4217
                      currency code.
                    example: EUR
              vat_rate:
                type: string
                description: The VAT rate of the item, formatted as a decimal string.
                example: '21.0'
        reusable:
          type: boolean
          description: >-
            Whether the payment link can be reused. Defaults to false for
            invoice payment links.
          example: true
        invoice_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            The ID of the invoice. Present for invoice payment links, null for
            basket payment links.
          example: 550e8400-e29b-41d4-a716-446655440001
        invoice_number:
          type:
            - string
            - 'null'
          description: >-
            The invoice number. Present for invoice payment links, null for
            basket payment links.
          example: INV-12345
        debitor_name:
          type:
            - string
            - 'null'
          description: >-
            Name of the customer/debitor. Present for invoice payment links,
            null for basket payment links.
          example: John Doe
        created_at:
          type: string
          format: date-time
          description: >-
            The date and time when the payment link was created, formatted as an
            ISO 8601 date-time string.
          example: '2021-01-01T00:00:00Z'
        url:
          type: string
          description: The URL of the payment link.
          example: >-
            https://pay.qonto.com/019788b3-57ab-727c-b26e-86b95c16e93f?resource_id=4c56f862-6117-4b20-a3e3-7fa6fccea029
    BadRequestResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BadRequestError'
      required:
        - errors
    UnauthorizedResponseBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/UnauthorizedError'
      required:
        - errors
    BadRequestError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
        source:
          type: object
          properties:
            pointer:
              type: string
              description: >-
                The property in the request body that caused the error
                (optional).
            parameter:
              type: string
              description: The query parameter that caused the error (optional).
      required:
        - code
        - detail
      x-examples:
        Authorization field missing:
          code: bad_request
          detail: Authorization field missing
    UnauthorizedError:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        detail:
          type: string
          description: Human readable error that explains error `code`.
      required:
        - code
        - detail
      x-examples:
        Invalid credentials:
          code: unauthorized
          detail: Invalid credentials
  responses:
    400-Bad-request:
      description: Returns a bad request error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestResponseBody'
          examples:
            Authorization field missing:
              value:
                errors:
                  - code: bad_request
                    detail: Authorization field missing
    401-Unauthorized:
      description: Returns an unauthorized error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponseBody'
          examples:
            authorization_header_missing:
              value:
                errors:
                  - code: authorization_header_missing
                    detail: authorization header missing
            authorization_token_invalid:
              value:
                errors:
                  - code: authorization_token_invalid
                    detail: authorization token invalid
    500-Internal-Server-Error:
      description: Returns an internal server error.
  securitySchemes:
    OAuth:
      type: oauth2
      description: >
        Bearer authorization header: `Bearer <token>`, where `<token>` is the
        access token received from the authorization server at the end of the
        [OAuth 2.0
        flow](/get-started/business-api/authentication/oauth/oauth-flow).
      flows:
        authorizationCode:
          refreshUrl: https://oauth.qonto.com/oauth2/token
          authorizationUrl: https://oauth.qonto.com/oauth2/auth
          scopes:
            attachment.read: Retrieve attachments
            attachment.write: Upload attachments and remove attachments from transactions
            bank_account.write: Create, update and close bank accounts
            beneficiary.trust: Trust SEPA beneficiaries
            card.read: Retrieve cards
            card.write: Create or update cards
            client.read: Retrieve clients
            client.write: Create clients
            client_invoice.write: Create client invoices
            client_invoices.read: Retrieve client invoices and credit notes
            einvoicing.read: Retrieve e-invoicing settings
            embed_auth_link.write: Create Embed auth links
            insurance_contract.read: Retrieve insurance contracts
            insurance_contract.write: Create and update insurance contracts
            internal_transfer.write: >-
              Create internal transfers (between 2 Qonto accounts of the same
              organization)
            international_transfer.write: Create international transfers
            membership.read: Retrieve the authentified membership
            membership.write: Invite team members
            offline_access: Retrieve a refresh token
            organization.read: >-
              Retrieve organization, bank accounts, transactions, transfers,
              beneficiaries, labels, memberships, requests & statements
            payment.write: Create external transfers and untrust beneficiaries
            payment_link.read: >-
              Retrieve payment links, their payments, and the available payment
              methods
            payment_link.write: >-
              Connect to the payment links provider, create and deactivate
              payment links
            product.read: Retrieve products
            product.write: Create products
            request_cards.write: Create card requests
            request_review.write: Approve or decline requests
            request_transfers.write: Create transfer requests
            sepa_direct_debit.read: View SEPA Direct Debit payments
            sepa_direct_debit.write: Manage SEPA Direct Debit payments
            supplier_invoice.read: Retrieve supplier invoices
            supplier_invoice.write: Create supplier invoices
            team.read: Retrieve teams
            team.write: Create teams
            terminal.read: View your payment terminals
            terminal.write: Configure your terminals and initiate payments
            webhook: >-
              Receive a notification each time a particular event occurs in
              Qonto
          tokenUrl: https://oauth.qonto.com/oauth2/token
    SecretKey:
      type: apiKey
      description: cf. [API key](/get-started/business-api/authentication/api-key)
      name: Authorization
      in: header

````