openapi: 3.0.3
info:
  title: LOGPAY Token API
  version: '1.0'
  contact:
    name: LOGPAY Financial Services GmbH
    url: https://logpay.de
  description: >-
    # Getting started


    This reference is key for your comprehensive understanding of LOGPAY Token
    Service.


    LOGPAY's APIs make use of RESTful conventions when possible and where it
    makes sense. All calls use the standard HTTP verbs to express access
    semantics, like `GET`, `POST`, `PATCH`, and `DELETE`. Other related
    conventions for our API can be found in the section below.


    ## JSON Conventions


    - Resources are addressable by a UUIDv4 `id` property.

    - Property names are always in `snake_case`.

    - The API does not support empty strings. To unset a string value, use an
    explicit `null` value instead.

    - Temporal data is encoded in [ISO
    8601](https://en.wikipedia.org/wiki/ISO_8601) strings.


    ## Authentication


    API keys are supported to authenticate requests.


    The keys are passed in via the HTTP header `x-api-key`.


    ```bash

    curl --header 'X-API-Key: <SECRET>' \
      --request POST 'https://test.token.logpay.de/...'
    ```


    The keys must be handled with care and kept secure. Never hardcode the API
    keys in your source code, but keep them solely on your backend systems.


    ## API Use


    ## Pagination


    Endpoints that return lists of objects support cursor-based pagination
    requests. By default, the API returns up to 50 objects per API call. If the
    number of objects in a response from a support endpoint exceeds the default,
    then an integration can use pagination to request a specific set of the
    results and/or to limit the number of returned objects.


    If an endpoint supports pagination, the response body follows this
    structure:


    ```json Response Samle

    {
      "current_page": 1,
      "page_size": 50,
      "total_items": 200,
      "total_pages": 4,
      "data": [...]
    }

    ```


    The single pages can be requested with query parameters:


    | Parameter | Type      |
    Description                                             |

    | :-------- | :-------- |
    :------------------------------------------------------ |

    | `limit`   | `integer` | The maximum amount of objects to be returned on a
    page. |

    | `page`    | `integer` | The requested number of the page to
    return.             |


    ### Request Errors


    The API uses the standard errors to indicate the client errors on the
    service level.


    {% tabs %}
      {% tab label="Invalid Requests - HTTP 4xx" %}
        The response payload for processing errors follows a standard format.

        ```json
        {
          "status": "the HTTP status code",
          "classifier": "the classifer of the error",
          "message": "interesting for humans..."
        }
        ```
      {% /tab %}
      {% tab label="Unprocessable Content - HTTP 422" %}
        The response payload for processing errors follows a standard 
        format which includes the validation errros.

        ```json
        {
          "status": "the HTTP status code",
          "classifier": "the classifer of the error",
          "message": "interesting for humans...",
          "validation_errors": [
            {
              "path": "a JSON path pointing to the wrong data",
              "message": "something interesting for humans..."
            }
          ]
        }
        ```
      {% /tab %}
    {% /tabs %}


    ### Business Errors


    The processing errors refer to the primary functions of the LOGPAY Token
    Service and not necessarily to the related business logic. For example, a
    failed authorization due to insufficient funds will result in a 200
    response, as the payment layer could successfully process the request (even
    though the business result is negative).
servers:
  - url: https://test.token.logpay.de
    description: Sandbox
x-tagGroups:
  - name: Integration Layer
    tags:
      - integration_payone
  - name: Tokens
    tags:
      - tokens_create
      - tokens_management
      - network_tokens
tags:
  - name: tokens_create
    x-displayName: Create LOGPAY Tokens
    description: >
      LOGPAY Tokens are powerful instrument to manage card holder data in a
      PCI/DSS compliant way.


      {% cards %}
        {% card title="Compliance as a Service" %}
          Achieve PCI / DSS compliance in almost no time using our certified managed compliance service. 
        {% /card %}
        {% card title="No Acquirer Lock-In" %}
          Transparently use the cardholder data across all connected processors to implement 
          a non lock-in acquiring setup.
        {% /card %}
        {% card title="Network Tokens" %}
          For every card which is tokenized, network-tokens can be automatically provisioned. 
          This allows for more secure transactions, better conversion, and ultimately lower processing cost.
        {% /card %}
      {% /cards %}
  - name: tokens_management
    x-displayName: Token Management
    description: >
      All cards stored with LOGPAY can be managed via the endpoints in this
      section.


      The CVC2 security code is only kept in an ephemeral cache for a few
      minutes. The API allows to manage this resource with these endpoints:
        - check if the CVC2 is still availble
        - request a new session to renew the CVC2 with our SDK
        - consume the token after a successful authorization on an external processor
  - name: network_tokens
    x-displayName: Network Tokens
    description: >
      LOGPAY supports Network Tokens with major card schemes.


      The lifecycle of network tokens is automatically managed. When activated a
      network token 

      is automatically provisioned and maintained through its life-cycle.


      {% admonition type="info" %}
        The use of Network Tokens requires prior activation by your account manager.
      {% /admonition %}
  - name: compliance_service
    x-displayName: Compliance Service
  - name: integration_payone
    x-displayName: PAYONE
paths:
  /tokens/session:
    post:
      summary: Request a token session
      description: |
        Create a session to start LOGPAY Tokenization using our SDK.
      operationId: create_tokenization_session
      tags:
        - tokens_create
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenSessionCreate'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenSession'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /cde-import:
    post:
      summary: Create token from FPAN
      description: |
        Import cardholder-data in exchange for a LOGPAY token.

        {% admonition type="warning" name="Compliance Check Required" %}
          In order to use this endpoint you need to prove a certain level of compliance with PCI/DSS with us.
          Reach out to your account manager for more information.
        {% /admonition %}
      operationId: import_cardholder_data
      tags:
        - tokens_create
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardholderData'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogpayToken'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Token_Notification'
  /tokens:
    get:
      summary: Get tokens
      description: |
        Get a list of all LOGPAY Tokens that belong to this account.


        The results are grouped into pages. The caller can specify how many
        customers per page shall be listed (maximum is 500).
      operationId: list_tokenized_cards
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: query
          name: limit
          description: >-
            The desired amount of records per page. The parameter defaults to 50
            if it is omitted and has a maximum of 500.
          schema:
            type: integer
            minimum: 1
            maximum: 500
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 1
          required: false
        - in: query
          name: from
          description: Return only network tokens created from this date (YYYY-MM-DD).
          schema:
            type: string
            format: date-time
          required: false
        - in: query
          name: to
          description: Return only network tokens created up to this date (YYYY-MM-DD).
          schema:
            type: string
            format: date-time
          required: false
        - in: query
          name: sort
          description: >
            It allows sorting the result by created_at. e.g
            `sort=created_at+asc` or `sort=created_at+desc`
          schema:
            type: string
          required: false
        - in: query
          name: network_token_status
          description: >-
            Requested status in list format e.g `network_token_status=active` or
            `network_token_status=active,inactive`
          schema:
            $ref: '#/components/schemas/NetworkTokenStatus'
          required: false
        - in: query
          name: scheme
          description: >-
            Requested card schemes in list format e.g `scheme=VISA` or
            `scheme=VISA,MASTERCARD`
          schema:
            $ref: '#/components/schemas/CardScheme'
          required: false
        - in: query
          name: business_key
          description: >-
            Request tokens which the exact match of this value.


            The business key is a reference of the original ID under which the
            cardholder data was stored on the system from which it was imported
            to LOGPAY.
          schema:
            type: string
          required: false
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogpayTokenList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /tokens/{id}:
    get:
      summary: Get token details
      description: Get a LOGPAY token by its identifer.
      operationId: get_tokenized_card
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogpayToken'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    delete:
      summary: Delete a token
      description: >
        Remove a Logpay token and all associated information (e.g. network
        tokens).


        {% admonition type="warning" name="Warning" %}
          This operation cannot be undone.
        {% /admonition %}
      operationId: remove_tokenized_card
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '204':
          description: Success response (No Content)
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Token_Notification'
  /tokens/{id}/security-code:
    get:
      summary: Check CVC2
      description: >
        Get an indicator if security information for a stored LOGPAY token is
        still available.
      operationId: get_tokenized_card_security_information
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityCode'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens/{id}/refresh-session:
    post:
      summary: Refresh CVC2
      description: >
        Create a session to update the Security Code from a LOGPAY Token using
        our SDK.
      operationId: refresh_secutiry_token_session
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenSession'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens/{id}/consume:
    post:
      summary: Consume a token
      description: >-
        Tell LOGPAY after successful use of the token for an payment
        authorization, that the CVC2 can be removed from cache.
      operationId: consume_security_code
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '204':
          description: Success response (No Content)
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens/{id}/payment-data:
    post:
      summary: Request a cryptogram
      description: Request a TAVV cryptogram for a LOGPAY token.
      operationId: request_payment_data
      tags:
        - network_tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentDataRequest'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentData'
              examples:
                success:
                  summary: Success Case
                  value:
                    id: 00000000-0000-0000-0000-000000000000
                    amount: 10000
                    currency_code: EUR
                    created_at: '2023-10-01T00:00:00Z'
                    encrypted_authentication_data: eyJhbGc...
                    merchant_id: 00000000-0000-0000-0000-000000000000
                    reference: '1234567890'
                    success: true
                    token_id: 00000000-0000-0000-0000-000000000000
                failure:
                  summary: Failure Case
                  value:
                    id: 00000000-0000-0000-0000-000000000000
                    amount: 10000
                    currency_code: EUR
                    created_at: '2023-10-01T00:00:00Z'
                    failure_details:
                      - classifier: SOME_ERROR
                        scheme_code: Do not honor
                        message: Scheme rejected the request
                        source: scheme
                    merchant_id: 00000000-0000-0000-0000-000000000000
                    reference: '1234567890'
                    success: false
                    token_id: 00000000-0000-0000-0000-000000000000
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
    get:
      summary: Get cryptograms
      description: List all cryptograms requested by the Token
      operationId: list_payment_data
      tags:
        - network_tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
        - in: query
          name: limit
          description: >-
            The desired amount of records per page. The parameter defaults to 50
            if it is omitted and has a maximum of 500.
          schema:
            type: integer
            minimum: 1
            maximum: 500
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 1
          required: false
        - in: query
          name: sort
          description: >
            It allows sorting the result by created_at. e.g
            `sort=created_at+asc` or `sort=created_at+desc`
          schema:
            type: string
          required: false
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentDataList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens/{id}/provisions:
    post:
      summary: Update a network token
      description: >
        If the provisioning of a network token status is `failed` or
        `not_available`

        for any reason, this endpoint can be used to provision a network token.
      operationId: network_token_provision
      tags:
        - network_tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the LOGPAY token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogpayToken'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /integrations/payone/obtain-ppan:
    post:
      summary: Obtain Pseudo PAN
      description: Exchange a LOGPAY Token for a Pseudo PAN (PPAN) with Payone.
      operationId: payone_obtain_ppan
      tags:
        - integration_payone
      security:
        - APIKeyAuth: []
      parameters:
        - in: header
          name: x-payone-aid
          schema:
            type: string
          required: true
        - in: header
          name: x-payone-hash
          schema:
            type: string
          required: true
        - in: header
          name: x-payone-mid
          schema:
            type: string
          required: true
        - in: header
          name: x-payone-portalid
          schema:
            type: string
          required: true
      x-badges:
        - name: Beta
          position: after
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token_id:
                  type: string
                  description: The ID of the LOGPAY Token for which a PPAN is requested
                  format: uuid
              required:
                - token_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - VALID
                      - INVALID
                      - ERROR
                  cardtype:
                    type: string
                    example: V
                  cardexpiredate:
                    type: string
                    example: '1230'
                  pseudocardpan:
                    type: string
                    example: '9410010000038248746'
                  truncatedcardpan:
                    type: string
                    example: 411111XXXXXX1111
                  tcdata:
                    type: string
                    enum:
                      - 'yes'
                      - 'no'
                  tcprovider:
                    type: string
                    example: Degussa
                  tcinvoice:
                    type: string
                    exmple: 'no'
        '400':
          description: ERROR
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - VALID
                      - INVALID
                      - ERROR
                  errorcode:
                    type: number
                    description: >-
                      In case of error the PAYONE Platform returns an error code
                      for your internal usage.
                  errormessage:
                    type: string
                    description: >-
                      In case of error the PAYONE Platform returns an error
                      message for your internal usage.
                  customermessage:
                    type: string
                    description: >-
                      The customermessage is returned to your system in order to
                      be displayed to the customer.
        '407':
          $ref: '#/components/responses/407_ProxyAuthenticationRequiredError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
        '502':
          $ref: '#/components/responses/502_BadGatewayError'
        '503':
          $ref: '#/components/responses/503_ServiceUnavailableError'
        '504':
          $ref: '#/components/responses/504_GatewayTimeoutError'
components:
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
  schemas:
    TokenSessionCreate:
      type: object
      properties:
        bypass_identification:
          type: boolean
          description: Skips ID&V during tokenization if set to true
          default: false
        expiration_time:
          type: integer
          description: >
            The expiry time is used to specify after how many seconds a LOGPAY
            token should be automatically deleted.


            This type of tokens is useful for short-lived operations (guest
            checkout) that require a token to be used only once or for a limited
            time.

            Information: If a token is created with an expiration time, no
            network-token will be provisioned.
          minimum: 1
          maximum: 2592000
    TokenSession:
      type: object
      properties:
        session_id:
          description: |
            The ID of the session which needs to be used to initialize the SDK.
          type: string
          format: uuid
      required:
        - session_id
    ErrorStatusCode:
      type: integer
      description: The corresponding HTTP status code for the error
    ErrorClassifier:
      type: string
      description: Technical code that helps to identify the error
    ErrorMessage:
      type: string
      description: Human readable representation of the error
    ErrorGeneric:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
    CardholderData:
      type: object
      properties:
        cardholder_name:
          type: string
          description: |
            The name of the owner of the card
        expiry_month:
          type: integer
          description: The number of month in a year (e.g. April is 4)
        expiry_year:
          type: integer
          description: The year given as four digit number (e.g. 2023)
        account_number:
          type: string
          description: The full PAN of the card
        security_code:
          type: string
          description: >
            The security code of the card


            Information: LOGPAY will not permanently store the security code,
            but keep it in a ephemeral position for immediate use.
      required:
        - account_number
        - expiry_month
        - expiry_year
      example:
        cardholder_name: John Doe
        expiry_month: 4
        expiry_year: 2033
        account_number: '4242424242424242'
        security_code: '123'
    ISO3166-2-CountryCode:
      type: string
      description: |
        A two letter country code.
        [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
    NetworkTokenStatus:
      type: string
      description: >
        The status of the associated network token.

        | **Status** | **Description** |

        |------------|---------------------------------------------------------------------------------------------------------------------|

        | `active`   | The network token is active and can be used. |

        | `inactive` | The network token is inactive, which prevents using it.
        The reason can be for example suspended network token.      |

        | `pending` | A network token is currently being provisioned. As soon as
        this is available, the status is changed to `active`.

        | `failed` | A network token failed to be provisioned.

        | `deleted`  | The network token is deleted and cannot be used again.
        It  is also not possible to activate the network token again. |

        | `not_available` | A network token can not be provisioned with the
        current configuration.  |
      enum:
        - active
        - inactive
        - pending
        - deleted
        - failed
        - not_available
    NetworkTokenStatusReason:
      type: object
      properties:
        scheme_code:
          type: integer
          description: The code returned by the Scheme Network
        classifier:
          type: string
          description: Technical code that helps to identify the error
        message:
          type: string
          description: >
            The error message describing why the network token failed during the
            Network Token creation in Scheme Network.
    CardScheme:
      type: string
      description: The scheme in which the card was issued
      enum:
        - VISA
        - Mastercard
        - American Express
        - Discover
        - Diners Club
        - JCB
        - UnionPay
        - Unknown
    LogpayTokenAuthenticationData:
      type: object
      properties:
        acs_transaction_id:
          type: string
          description: The ID of the transaction of the access control server.
          format: uuid
        transaction_status:
          deprecated: true
          type: string
          description: |
            The status of Authentication Transaction

            Transaction Statuses:

              * `Y` - Authentication / Account verified with success
              * `N` - Not authentication / Account not verified
              * `U` - Authentication / Account verification not available
              * `A` - Payment Attempt Processed: Authentication not confirmed, but verification attempted
              * `C` - Challenge required
              * `R` - Authentication / Account verification has been rejected
              * `D` - Challenge required via Decoupled Authentication
              * `I` - Informational only
        status:
          type: string
          description: |
            The status of Authentication Transaction

            Transaction Statuses:

              * `Y` - Authentication / Account verified with success
              * `N` - Not authentication / Account not verified
              * `U` - Authentication / Account verification not available
              * `A` - Payment Attempt Processed: Authentication not confirmed, but verification attempted
              * `C` - Challenge required
              * `R` - Authentication / Account verification has been rejected
              * `D` - Challenge required via Decoupled Authentication
              * `I` - Informational only
        transaction_status_reason:
          deprecated: true
          type: string
          description: >
            The additional information about why the Transaction Status has the
            specified value


            Transaction Status Reasons:

              * `01` - Card authentication failed
              * `02` - Unknown Device
              * `03` - Unsupported Device
              * `04` - Exceeds authentication frequency limit
              * `05` - Expired card
              * `06` - Invalid card number
              * `07` - Invalid transaction
              * `08` - No Card record
              * `09` - Security failure
              * `10` - Stolen card
              * `11` - Suspected fraud
              * `12` - Transaction not permitted to cardholder
              * `13` - Cardholder not enrolled in service
              * `14` - Transaction timed out at the ACS
              * `15` - Low confidence
              * `16` - Medium confidence
              * `17` - High confidence
              * `18` - Very High confidence
              * `19` - Exceeds ACS maximum challenges
              * `20` - Non-Payment transaction not supported
              * `21` - 3RI transaction not supported
              * `22` - ACS technical issue
              * `23` - Decoupled Authentication required by ACS but not requested by 3DS Requestor
              * `24` - 3DS Requestor Decoupled Max Expiry Time exceeded
              * `25` - Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
              * `26` - Authentication attempted but not performed by the cardholder
        status_reason_code:
          type: string
          description: >
            The additional information about why the Transaction Status has the
            specified value


            Transaction Status Reasons:

              * `01` - Card authentication failed
              * `02` - Unknown Device
              * `03` - Unsupported Device
              * `04` - Exceeds authentication frequency limit
              * `05` - Expired card
              * `06` - Invalid card number
              * `07` - Invalid transaction
              * `08` - No Card record
              * `09` - Security failure
              * `10` - Stolen card
              * `11` - Suspected fraud
              * `12` - Transaction not permitted to cardholder
              * `13` - Cardholder not enrolled in service
              * `14` - Transaction timed out at the ACS
              * `15` - Low confidence
              * `16` - Medium confidence
              * `17` - High confidence
              * `18` - Very High confidence
              * `19` - Exceeds ACS maximum challenges
              * `20` - Non-Payment transaction not supported
              * `21` - 3RI transaction not supported
              * `22` - ACS technical issue
              * `23` - Decoupled Authentication required by ACS but not requested by 3DS Requestor
              * `24` - 3DS Requestor Decoupled Max Expiry Time exceeded
              * `25` - Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt
              * `26` - Authentication attempted but not performed by the cardholder
    LogpayToken:
      type: object
      properties:
        id:
          type: string
          description: The ID of the LOGPAY Token
          format: uuid
        cardholder_name:
          type: string
          description: The name of the owner of the card
        card_art_url:
          type: string
          description: The url linking to the card art endpoint
        created_at:
          type: string
          description: The date-time the payment-method was created (following ISO 8601)
          format: date-time
        expiry_month:
          type: integer
          description: The number of month in a year (e.g. April is 4)
        expiry_year:
          type: integer
          description: The year given as four digit number (e.g. 2023)
        expires_at:
          type: string
          description: >-
            The date-time when the token will expire. Applicable only for
            ephemeral tokens.
          format: date-time
        invalidated_at:
          type: string
          format: date-time
          description: >-
            The time the LOGPAY Token was invalidated, because the underlying
            payment instrument was invalidated by the scheme.
        issuer_identification_number:
          type: string
          description: The issuer idenfication number (IIN) - also known as BIN
        account_number_last_four:
          type: string
          description: Last four digits of the card number
        account_number_length:
          type: integer
          description: The total number of digits in the card number
        masked_account_number:
          type: string
          description: >-
            The full lenght of the card number, but masked to conform to PCI/DSS
            requirments
        bank_name:
          type: string
          description: Issuer bank name
        segment:
          type: string
          description: Card segment
          enum:
            - business
            - consumer
            - commercial
            - other
        status:
          type: string
          description: The status of this LOGPAY token.
          enum:
            - active
            - invalid
        type:
          type: string
          description: Card type
          enum:
            - credit
            - debit
        country_code:
          $ref: '#/components/schemas/ISO3166-2-CountryCode'
        network_token_status:
          $ref: '#/components/schemas/NetworkTokenStatus'
        network_token_status_reason:
          $ref: '#/components/schemas/NetworkTokenStatusReason'
        scheme:
          $ref: '#/components/schemas/CardScheme'
        identity_and_verification:
          type: string
          description: The type of ID&V submitted during the creation of the LOGPAY token..
          enum:
            - none
            - checked
            - skipped
        authentication_data:
          $ref: '#/components/schemas/LogpayTokenAuthenticationData'
        supports_device_binding:
          type: boolean
        business_key:
          type: string
          description: >-
            This attribute holds the original business key under which the
            cardholder data was stored on the system from which it was imported
            to Logpay.


            It can be used for reconciliation or reference purposes.
        import_provider:
          type: string
          description: >-
            The source from which the cardholder data was imported from.


            The `business_key` attribute will refer to the original ID at this
            provider.
      required:
        - id
        - created_at
        - expiry_month
        - expiry_year
        - masked_account_number
        - issuer_identification_number
        - scheme
      example:
        id: 5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d
        cardholder_name: John Doe
        card_art_url: >-
          https://test.token.logpay.de/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b
        created_at: '2023-10-01T00:00:00Z'
        expiry_month: 4
        expiry_year: 2033
        expires_at: '2023-10-07T00:00:00Z'
        issuer_identification_number: '424242'
        masked_account_number: 424242******4242
        network_token_status: active
        scheme: VISA
    ErrorValidation:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
        validation_errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
                description: Json-path in the request which points to the validation error
              message:
                type: string
                description: Human readable validation message
    Pagination:
      type: object
      description: >
        The meta-data describing lists of data from the LOGPAY API. The pages
        are indexed from 1 up to the total_pages.
      properties:
        current_page:
          type: integer
          description: The index of the current page
        page_size:
          type: integer
          description: >
            The maximum number of items on a page (relates to the limit query
            parameter)
        total_items:
          type: integer
          description: The total quantity of items regardless of the pages
        total_pages:
          type: integer
          description: The total amount of pages the data is segmented into
      example:
        current_page: 1
        page_size: 1
        total_items: 1
        total_pages: 1
    LogpayTokenList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LogpayToken'
        pagination:
          $ref: '#/components/schemas/Pagination'
    SecurityCode:
      type: object
      properties:
        security_code_available:
          type: boolean
          description: Security Data available in the system
    Amount:
      type: integer
      minimum: 0
      description: >
        The amount given in minor units (e.g. use 700 for 7€).

        Some currencies do not support minor units (e.g. Japanese Yen). In this
        case send in the full value, .i.e. 100 for 100 JPY.
    CurrencyCode:
      type: string
      description: |
        The three letter currency code.
        See: [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes)
    EncryptedAuthenticationData:
      type: string
      description: >
        JWE encrypted JSON string containing authentication data.



        Encrypted in a symmetric way with the shared encryption key using

        "alg"=A256GCMKW and "enc"="A256GCM". For decryption make sure the shared
        secret is hashed with a sha256 digest.



        The decrypted JSON has the following format:


        ```json

        {
            network_token: {
              token: "token_value",
              expiry_year: 2023,
              expiry_month: 12
            },
            cryptogram: "cryptogram_value",
            eci: "eci_value"
        }

        ```


        - The field `network_token` contains the value of the token, the year of
        expiry and the month of expiry of the token and is always included.

        - The field `cryptogram` contains the value of the cryptogram and is
        always included.

        - The field `eci` can instead have a value if there was an Electronic
        Commerce Indicator assigned, or it can be `null` if no information was
        provided.
    PaymentData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The id of the requested payment data
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        created_at:
          type: string
          format: date-time
          description: The date-time the payment-data was created (following ISO 8601)
        encrypted_authentication_data:
          $ref: '#/components/schemas/EncryptedAuthenticationData'
        failure_details:
          type: array
          description: >
            The reasons why the processing failed. 

            There are two categories of errors that can happen in this context
            (the `source` field indicates the category):

              1. Scheme errors: errors that are returned by the scheme. 
              2. Configuration errors: errors that are caused by the configuration with respect to the scheme.
          items:
            type: object
            properties:
              classifier:
                type: string
              scheme_code:
                type: string
                description: >
                  Sometimes schemes provide a code that describe a reason why a
                  request failed.
              message:
                type: string
              source:
                type: string
                enum:
                  - scheme
                  - configuration
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
        reference:
          type: string
          description: Reference in calling system
        success:
          type: boolean
          description: >
            The result of the processing of the request. 

            If true, the processing was successfully completed. In case it is
            false,  the processing failed and the `failure_details` field
            contains more information about the failure.
        token_id:
          type: string
          format: uuid
          description: The ID of the token on LOGPAY
      required:
        - id
        - amount
        - currency_code
        - merchant_id
        - reference
        - success
        - token_id
    PaymentDataList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentData'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PaymentDataRequest:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
        reference:
          type: string
          description: A reference to the payment
      required:
        - amount
        - currency_code
        - reference
      example:
        amount: 10000
        currency_code: EUR
        merchant_id: 00000000-0000-0000-0000-000000000000
        reference: '1234567890'
  responses:
    401_UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 401
            message: No valid means of authentication was provided
            classifier: UNAUTHORIZED
    403_ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 403
            message: Not allowed to access this resource or feature
            classifier: FORBIDDEN
    422_ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorValidation'
          example:
            code: 422
            classifier: VALIDATION_ERROR
            message: Validation error
            validation_errors:
              - path: json-path
                message: human readable error message
    404_NotFoundError:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 404
            message: The requested resource was not found.
            classifier: NOT_FOUND
    407_ProxyAuthenticationRequiredError:
      description: No valid means of authentication was provided for the proxy
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 407
            message: Proxy authentication required
            classifier: PROXY_AUTHENTICATION_REQUIRED
    502_BadGatewayError:
      description: A non-processable response was received from the upstream server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 502
            message: Bad gateway
            classifier: BAD_GATEWAY
    503_ServiceUnavailableError:
      description: The server is currently not able to handle the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 503
            message: Service unavailable
            classifier: SERVICE_UNAVAILABLE
    504_GatewayTimeoutError:
      description: The server did not receive any response in time from the upstream server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 504
            message: Gateway timeout
            classifier: GATEWAY_TIMEOUT
  callbacks:
    Token_Notification:
      '{notification_endpoint}':
        post:
          summary: Token Master Notification
          description: >-
            This endpoint is used to notify the integration server about changes
            in the token state.
          security: []
          parameters:
            - in: path
              name: notification_endpoint
              schema:
                type: string
              description: >-
                The endpoint of the notification callback. The endpoint is
                provided by the integration server during the account creation.
              required: true
            - in: header
              name: x-hmac-signature
              schema:
                type: string
              description: >-
                The signature of request body calculated based on the secret
                HMAC key of the account
          requestBody:
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: >-
                        A unique ID of the event which caused the notifcation
                        callback
                    created_at:
                      type: string
                      format: date-time
                      description: >-
                        The date-time the event was occurred (following ISO
                        8601)
                    event_type:
                      type: string
                      enum:
                        - token.created
                        - token.updated
                        - token.deleted
                    token:
                      $ref: '#/components/schemas/LogpayToken'
                  required:
                    - id
                    - created_at
                    - event_type
                example:
                  id: b21ecb35-6c95-46d9-afb2-c130cdf1750f
                  created_at: '2023-01-01T00:00:00Z'
                  event_type: token.created
                  token:
                    id: 5d6b2c9a-9b0b-4b0c-8c7d-9e9d5d7e9d5d
                    cardholder_name: John Doe
                    card_art_url: >-
                      https://test.token.logpay.de/tokens/card-art/374c911a-8125-40eb-acb8-a26efd25f02b
                    created_at: '2023-10-01T00:00:00Z'
                    expiry_month: 4
                    expiry_year: 2033
                    issuer_identification_number: '424242'
                    masked_account_number: 424242******4242
                    network_token_status: active
                    scheme: VISA
          responses:
            '200':
              description: >
                Confirmation of receipt. For other status codes, LOGPAY will try
                to redeliver.
            '400':
              description: Bad request
