openapi: 3.0.1
servers:
  - description: PAYONE Link API server url
    url: https://onelink.pay1.de/api
info:
  contact:
    email: info@payone.com
    url: https://www.payone.com/kontakt/
  title: PAYONE Link API
  version: v1
  x-apisguru-categories:
    - payment
  x-origin:
    - format: openapi
      url: https://gist.githubusercontent.com/MikeRalphson/b526159dff395f5da394bdf0c1d8b004/raw/ec8e44241fcd114d00c4662a04d2ff5b16f4b95f/payone-openapi.yaml
      version: "3.0"
  x-providerName: pay1.de
  x-serviceName: link
externalDocs:
  description: Find more info here
  url: https://docs.payone.com/display/PLATFORM/Channel+PAYONE+Link
tags:
  - description: Endpoints intended for server-to-server communication.
    name: Link Management
paths:
  /v1/payment-links:
    get:
      operationId: getPaymentLinks
      parameters:
        - in: query
          name: page
          required: false
          schema:
            default: 0
            format: int32
            type: integer
        - in: query
          name: limit
          required: false
          schema:
            default: 25
            format: int32
            type: integer
        - in: query
          name: merchantId
          required: true
          schema:
            pattern: "[0-9]+"
            type: string
        - in: query
          name: accountId
          required: true
          schema:
            pattern: "[0-9]+"
            type: string
        - in: query
          name: portalId
          required: true
          schema:
            pattern: "[0-9]+"
            type: string
        - in: query
          name: mode
          required: true
          schema:
            pattern: live|test
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageLinkResponse"
          description: default response
      security:
        - getMultipleAuth: []
      summary: List all payment links.
      tags:
        - Link Management
    post:
      operationId: createPaymentLink
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkCreateRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkResponse"
          description: default response
      security:
        - createAuth: []
      summary: Create a payment link.
      tags:
        - Link Management
  "/v1/payment-links/{linkId}":
    get:
      operationId: getPaymentLink
      parameters:
        - in: path
          name: linkId
          required: true
          schema:
            pattern: "[0N1RWU4X6F8Z9ALBQC3EG5HJKM2PS7TVDY]{32}"
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkResponse"
          description: default response
      security:
        - getSingleAuth: []
      summary: Get payment link by id.
      tags:
        - Link Management
    put:
      operationId: updatePaymentLink
      parameters:
        - in: path
          name: linkId
          required: true
          schema:
            pattern: "[0N1RWU4X6F8Z9ALBQC3EG5HJKM2PS7TVDY]{32}"
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkCreateRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LinkResponse"
          description: default response
      security:
        - createAuth: []
      summary: Update a payment link.
      tags:
        - Link Management
components:
  schemas:
    AddressDataDto:
      properties:
        addressAddition:
          description: customer additional address line
          example: 7th floor
          maxLength: 50
          minLength: 1
          type: string
        city:
          description: customer city
          example: Kiel
          maxLength: 50
          minLength: 1
          pattern: ^[^\u0000\\!=<>?+;"*\d]+$
          type: string
        company:
          description: customer company name
          example: PAYONE GmbH
          maxLength: 50
          minLength: 2
          type: string
        country:
          description: customer country code (2 letter ISO-3166 code)
          example: DE
          maxLength: 2
          minLength: 2
          pattern: "[A-Z]{2}"
          type: string
        firstName:
          description: customer first name
          example: John
          maxLength: 50
          minLength: 1
          type: string
        lastName:
          description: customer last name
          example: Doe
          maxLength: 50
          minLength: 2
          type: string
        state:
          description: customer state code
          maxLength: 2
          minLength: 2
          pattern: "[A-Z]{2}"
          type: string
        street:
          description: customer street name
          example: Fraunhoferstr. 2-4
          maxLength: 50
          minLength: 2
          type: string
        zip:
          description: customer postcode
          example: "24118"
          maxLength: 10
          minLength: 2
          pattern: "[0-9A-Za-z_.\\-/]{2,10}"
          type: string
      type: object
    CartItemDto:
      properties:
        deliveryDateEnd:
          description: delivery period end date
          example: 2021-01-01
          format: date
          type: string
        deliveryDateStart:
          description: delivery date
          example: 2021-01-01
          format: date
          type: string
        description:
          description: item description
          example: Potatoes
          maxLength: 255
          minLength: 1
          type: string
        number:
          description: item number
          example: 73883HFJ
          maxLength: 32
          minLength: 1
          pattern: "[0-9A-Za-z(){} +\\-_#/:\\[\\]]{1,32}"
          type: string
        price:
          description: gross price of single item
          example: 1999
          format: int64
          maximum: 1999999999
          minimum: -1999999999
          type: integer
        quantity:
          description: total number of ordered items
          example: 1
          format: int64
          maximum: 999999
          minimum: 1
          type: integer
        type:
          description: item type
          enum:
            - goods
            - shipment
            - handling
            - voucher
          example: goods
          type: string
        vatRate:
          description: vat rate (<100 in %, >=100 in bp)
          example: 20
          format: int64
          maximum: 9999
          minimum: 0
          type: integer
      required:
        - number
        - price
        - quantity
        - type
      type: object
    InvoiceInformationDto:
      description: relevant information for the invoice module
      properties:
        invoiceId:
          description: id that should be put on the invoice
          maxLength: 20
          minLength: 0
          type: string
        invoiceText:
          description: short text that should be put after the invoice
          maxLength: 255
          minLength: 0
          type: string
      type: object
    LinkCreateRequest:
      description: a link create request
      properties:
        accountId:
          description: identifier for the subaccount
          example: "12345"
          pattern: "[0-9]+"
          type: string
        active:
          default: true
          description: link activation status
          example: true
          type: boolean
        backgroundImage:
          description: backgroundImage css property
          example: "linear-gradient(to bottom right, #ffffff, #3295d6)"
          format: css
          type: string
        billing:
          $ref: "#/components/schemas/AddressDataDto"
        currency:
          description: currency code
          enum:
            - ALL
            - DZD
            - ARS
            - AUD
            - BSD
            - BHD
            - BDT
            - AMD
            - BBD
            - BMD
            - BTN
            - BOB
            - BWP
            - BZD
            - SBD
            - BND
            - MMK
            - BIF
            - KHR
            - CAD
            - CVE
            - KYD
            - LKR
            - CLP
            - CNY
            - COP
            - KMF
            - CRC
            - HRK
            - CUP
            - CZK
            - DKK
            - DOP
            - SVC
            - ETB
            - ERN
            - FKP
            - FJD
            - DJF
            - GMD
            - GIP
            - GTQ
            - GNF
            - GYD
            - HTG
            - HNL
            - HKD
            - HUF
            - ISK
            - INR
            - IDR
            - IRR
            - IQD
            - ILS
            - JMD
            - JPY
            - KZT
            - JOD
            - KES
            - KPW
            - KRW
            - KWD
            - KGS
            - LAK
            - LBP
            - LSL
            - LRD
            - LYD
            - MOP
            - MWK
            - MYR
            - MVR
            - MUR
            - MXN
            - MNT
            - MDL
            - MAD
            - OMR
            - NAD
            - NPR
            - ANG
            - AWG
            - VUV
            - NZD
            - NIO
            - NGN
            - NOK
            - PKR
            - PAB
            - PGK
            - PYG
            - PEN
            - PHP
            - QAR
            - RUB
            - RWF
            - SHP
            - SAR
            - SCR
            - SLL
            - SGD
            - VND
            - SOS
            - ZAR
            - SSP
            - SZL
            - SEK
            - CHF
            - SYP
            - THB
            - TOP
            - TTD
            - AED
            - TND
            - UGX
            - MKD
            - EGP
            - GBP
            - TZS
            - USD
            - UYU
            - UZS
            - WST
            - YER
            - TWD
            - UYW
            - VES
            - MRU
            - STN
            - CUC
            - ZWL
            - BYN
            - TMT
            - GHS
            - SDG
            - UYI
            - RSD
            - MZN
            - AZN
            - RON
            - CHE
            - CHW
            - TRY
            - XAF
            - XCD
            - XOF
            - XPF
            - XBA
            - XBB
            - XBC
            - XBD
            - XAU
            - XDR
            - XAG
            - XPT
            - XTS
            - XPD
            - XUA
            - ZMW
            - SRD
            - MGA
            - COU
            - AFN
            - TJS
            - AOA
            - BGN
            - CDF
            - BAM
            - EUR
            - MXV
            - UAH
            - GEL
            - BOV
            - PLN
            - BRL
            - CLF
            - XSU
            - USN
          example: EUR
          maxLength: 3
          minLength: 3
          type: string
        description:
          description: free format description of the payment
          example: This payment is awesome!!
          maxLength: 255
          minLength: 0
          type: string
        email:
          description: email the invoice should be delivered to
          maxLength: 254
          minLength: 4
          type: string
        errorUrl:
          description: final redirect after a final payment
          type: string
        expiration:
          description: link expiration date, the link will only be executable until end of that day
          example: 2020-02-20
          format: date
          type: string
        intent:
          default: authorization
          description: designates the type of transaction that will be created
          enum:
            - authorization
            - preauthorization
          type: string
        invoiceInformation:
          $ref: "#/components/schemas/InvoiceInformationDto"
        language:
          description: link ISO language code
          enum:
            - de_DE
            - en_US
          example: en_US
          type: string
        logo:
          description: logo url
          example: https://www.payone.com/wp-content/uploads/2018/12/Payone-Logo-2020.jpg
          format: url
          type: string
        merchantId:
          description: identifier for the merchant
          example: "12345"
          pattern: "[0-9]+"
          type: string
        mode:
          description: execution mode
          enum:
            - live
            - test
          example: live
          type: string
        notifyUrl:
          description: Url where the notification will be send after link was executed
          type: string
        paymentMethods:
          description: list of available payment methods
          example:
            - visa
            - mastercard
          items:
            description: available payment methods
            enum:
              - visa
              - mastercard
              - amex
              - paypal
              - sofort
              - paydirekt
              - postfinance-e
              - postfinance-card
              - bancontact
              - przelewy24
              - alipay
              - ideal
              - eps
              - giropay
              - sepa
            example: visa
            type: string
          type: array
        portalId:
          description: identifier for the portal
          example: "1234567"
          pattern: "[0-9]+"
          type: string
        reference:
          description: payment reference number, has to be unique per merchant and mode
          example: payment_1
          pattern: "[0-9a-zA-Z.\\\\-_/]{1,20}"
          type: string
        shipping:
          $ref: "#/components/schemas/AddressDataDto"
        shoppingCart:
          items:
            $ref: "#/components/schemas/CartItemDto"
          maxItems: 400
          minItems: 1
          type: array
        successUrl:
          description: final redirect after a successful payment
          type: string
        userId:
          description: identifier for the user
          example: "12345678"
          pattern: "[0-9]+"
          type: string
      required:
        - accountId
        - currency
        - merchantId
        - mode
        - portalId
        - reference
        - shoppingCart
      type: object
    LinkResponse:
      properties:
        accountId:
          description: identifier for the subaccount
          example: "12345"
          type: string
        active:
          default: true
          description: link activation status
          example: true
          type: boolean
        amount:
          description: total amount of all shopping cart items in lowest denomination
          example: 799
          format: int64
          maximum: 1999999999
          minimum: 1
          type: integer
        backgroundImage:
          description: backgroundImage css property
          example: "linear-gradient(to bottom right, #ffffff, #3295d6)"
          format: css
          type: string
        billing:
          $ref: "#/components/schemas/AddressDataDto"
        created:
          description: created time in ISO 8601 format
          format: int64
          type: integer
        currency:
          description: currency code
          enum:
            - ALL
            - DZD
            - ARS
            - AUD
            - BSD
            - BHD
            - BDT
            - AMD
            - BBD
            - BMD
            - BTN
            - BOB
            - BWP
            - BZD
            - SBD
            - BND
            - MMK
            - BIF
            - KHR
            - CAD
            - CVE
            - KYD
            - LKR
            - CLP
            - CNY
            - COP
            - KMF
            - CRC
            - HRK
            - CUP
            - CZK
            - DKK
            - DOP
            - SVC
            - ETB
            - ERN
            - FKP
            - FJD
            - DJF
            - GMD
            - GIP
            - GTQ
            - GNF
            - GYD
            - HTG
            - HNL
            - HKD
            - HUF
            - ISK
            - INR
            - IDR
            - IRR
            - IQD
            - ILS
            - JMD
            - JPY
            - KZT
            - JOD
            - KES
            - KPW
            - KRW
            - KWD
            - KGS
            - LAK
            - LBP
            - LSL
            - LRD
            - LYD
            - MOP
            - MWK
            - MYR
            - MVR
            - MUR
            - MXN
            - MNT
            - MDL
            - MAD
            - OMR
            - NAD
            - NPR
            - ANG
            - AWG
            - VUV
            - NZD
            - NIO
            - NGN
            - NOK
            - PKR
            - PAB
            - PGK
            - PYG
            - PEN
            - PHP
            - QAR
            - RUB
            - RWF
            - SHP
            - SAR
            - SCR
            - SLL
            - SGD
            - VND
            - SOS
            - ZAR
            - SSP
            - SZL
            - SEK
            - CHF
            - SYP
            - THB
            - TOP
            - TTD
            - AED
            - TND
            - UGX
            - MKD
            - EGP
            - GBP
            - TZS
            - USD
            - UYU
            - UZS
            - WST
            - YER
            - TWD
            - UYW
            - VES
            - MRU
            - STN
            - CUC
            - ZWL
            - BYN
            - TMT
            - GHS
            - SDG
            - UYI
            - RSD
            - MZN
            - AZN
            - RON
            - CHE
            - CHW
            - TRY
            - XAF
            - XCD
            - XOF
            - XPF
            - XBA
            - XBB
            - XBC
            - XBD
            - XAU
            - XDR
            - XAG
            - XPT
            - XTS
            - XPD
            - XUA
            - ZMW
            - SRD
            - MGA
            - COU
            - AFN
            - TJS
            - AOA
            - BGN
            - CDF
            - BAM
            - EUR
            - MXV
            - UAH
            - GEL
            - BOV
            - PLN
            - BRL
            - CLF
            - XSU
            - USN
          example: EUR
          maxLength: 3
          minLength: 3
          type: string
        description:
          description: free format description of the payment
          example: This payment is awesome!!
          maxLength: 255
          type: string
        email:
          description: customer email for invoices or payment notification
          maxLength: 254
          minLength: 4
          type: string
        errorUrl:
          description: final redirect after a failed payment
          type: string
        expiration:
          description: link expiration date, the link will only be executable until end of that day
          example: 2020-02-20
          format: date
          type: string
        hash:
          description: hash for the client API
          example: a42847abb8bfca62876ca64c0fa981f8
          type: string
        id:
          description: link id
          example: HUENJ5FY124QHUENJ5FY124QHUENJ5FY
          maxLength: 32
          minLength: 32
          type: string
        intent:
          default: authorization
          description: designates the type of transaction that will be created
          enum:
            - authorization
            - preauthorization
          type: string
        invoiceInformation:
          $ref: "#/components/schemas/InvoiceInformationDto"
        language:
          description: link ISO language code
          enum:
            - de_DE
            - en_US
          example: en_US
          type: string
        link:
          description: customer payment link
          type: string
        logo:
          description: logo url
          example: https://www.payone.com/wp-content/uploads/2018/12/Payone-Logo-2020.jpg
          format: url
          type: string
        merchantId:
          description: identifier for the merchant
          example: "12345"
          type: string
        mode:
          description: execution mode
          enum:
            - live
            - test
          example: live
          type: string
        modified:
          description: last modified time in ISO 8601 format
          format: int64
          type: integer
        notifyUrl:
          description: notify url. If unset no notification will be send
          type: string
        paymentMethod:
          description: available payment methods
          enum:
            - visa
            - mastercard
            - amex
            - paypal
            - sofort
            - paydirekt
            - postfinance-e
            - postfinance-card
            - bancontact
            - przelewy24
            - alipay
            - ideal
            - eps
            - giropay
            - sepa
          example: visa
          type: string
        paymentMethods:
          description: list of available payment methods
          example:
            - visa
            - mastercard
          items:
            description: available payment methods
            enum:
              - visa
              - mastercard
              - amex
              - paypal
              - sofort
              - paydirekt
              - postfinance-e
              - postfinance-card
              - bancontact
              - przelewy24
              - alipay
              - ideal
              - eps
              - giropay
              - sepa
            example: visa
            type: string
          type: array
        paymentProcess:
          description: identifier of the created payment process.
          example: "347867997"
          type: string
        portalId:
          description: identifier for the portal
          example: "1234567"
          type: string
        redirectUrl:
          description: redirect url. empty if the payment process does not require a redirect.
          type: string
        reference:
          description: payment reference number, has to be unique per merchant and mode
          example: payment_1
          maxLength: 20
          minLength: 1
          type: string
        shipping:
          $ref: "#/components/schemas/AddressDataDto"
        shoppingCart:
          items:
            $ref: "#/components/schemas/CartItemDto"
          type: array
        status:
          description: link status
          enum:
            - ready
            - created
            - executed
            - expired
            - deactivated
          example: ready
          type: string
        successUrl:
          description: final redirect after a successful payment
          type: string
        userId:
          description: identifier of the created user.
          example: "356845874"
          type: string
      type: object
    PageLinkResponse:
      properties:
        content:
          items:
            $ref: "#/components/schemas/LinkResponse"
          type: array
        empty:
          type: boolean
        first:
          type: boolean
        last:
          type: boolean
        number:
          format: int32
          type: integer
        numberOfElements:
          format: int32
          type: integer
        pageable:
          $ref: "#/components/schemas/Pageable"
        size:
          format: int32
          type: integer
        sort:
          $ref: "#/components/schemas/Sort"
        totalElements:
          format: int64
          type: integer
        totalPages:
          format: int32
          type: integer
      type: object
    Pageable:
      properties:
        offset:
          format: int64
          type: integer
        pageNumber:
          format: int32
          type: integer
        pageSize:
          format: int32
          type: integer
        paged:
          type: boolean
        sort:
          $ref: "#/components/schemas/Sort"
        unpaged:
          type: boolean
      type: object
    Sort:
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean
      type: object
  securitySchemes:
    createAuth:
      description: Base64 encoded (merchantId + accountId + portalId + mode + reference + totalAmount + currency) signed with Portalkey in HmacSHA256
      scheme: payone-hmac-sha256
      type: http
    getMultipleAuth:
      description: Base64 encoded (merchantId + accountId + portalId + mode) signed with Portalkey in HmacSHA256
      scheme: payone-hmac-sha256
      type: http
    getSingleAuth:
      description: Base64 encoded linkId signed with Portalkey in HmacSHA256
      scheme: payone-hmac-sha256
      type: http
