openapi: 3.0.3
info:
  title: Hellgate API
  version: '2.0'
  contact:
    name: Starfish GmbH & Co. KG
    email: hello@starfish.team
    url: https://hellgate.io
  license:
    name: Hellgate® API Terms
    url: https://hellgate.io/terms-and-conditions-24-04
  description: "# Getting started\n\nThis reference is key for your comprehensive understanding of Hellgate® and, as such, essential for the successful use of our payment orchestration products.\n\nHellgate® 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.\n\n## JSON Conventions\n\n- Resources are addressable by a UUIDv4 `id` property.\n- Property names are always in `snake_case`.\n- Hellgate® does not support empty strings. To unset a string value, use an explicit `null` value instead.\n- Temporal data is encoded in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) strings.\n\n## Authentication\n\nWhen you sign up for an account, you can authenticate with either OpenID Connect (OAuth 2.0), or Secret API keys. Unless explicitly stated, all endpoints require authentication using either your OIDC or Secret API Keys.\n\n### API Key\n\nHellgate® supports API keys to authenticate requests.\n\nThe keys are passed in via the HTTP header `x-api-key`.\n\n```bash\ncurl --header 'X-API-Key: <SECRET>' \\\n  --request POST 'https://api.hellgate.io/...'\n```\n\nThe 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.\n\n### OpenID Connect\n\nHellgate® also supports OIDC id-tokens to authenticate requests. This option should be used when humans are interacting with the system. This is specifically the case when, for example, a front-end application is used to analyse data or modify the system state (for instance, our payment operations tool\_**Ubersicht**).\n\nThe authentication information is then passed in as a bearer token.\n\n```bash\ncurl --header 'Authorization: Bearer <SECRET>' \\\n  --request POST 'https://api.hellgate.io/...'\n```\n\nDue to the fact that human users can be associated with many Hellgate® accounts, some requests require sending also a `x-hellgate-account` header to specify the context of the request.\n\n## API Use\n\n### API Versions\n\nHellgate® API will be updated regularly, to include new features and updates to existing ones. We package these changes into versions that can be addressed using a header field (`x-hellgate-version`). \n\nIf the there is no version specified in the header, the most recent version is being used.\n\n```bash\ncurl --header 'x-hellgate-version: <SELECTED VERSION>' \\\n  --request POST 'https://api.hellgate.io/...'\n```\n\nHellgate® sets the `x-hellgate-version` header on API responses, to tell the integrator which version is in use.\n\n### Idempotency\n\nTo prevent your system from handling requests twice and thus, for example, charging a customer twice, Hellgate® supports idempotency on requests to the API. \n\nThe behavior is controlled via the header field `x-idempotency-Key`.\n\n```bash\ncurl --header 'x-idempotency-key: <key>' ...\n```\n\n### Pagination\n\nEndpoints that return lists of objects support cursor-based pagination requests. By default, Hellgate® 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.\n\nIf an endpoint supports pagination, the response body follows this structure:\n\n```json Response Samle\n{\n  \"current_page\": 1,\n  \"page_size\": 50,\n  \"total_items\": 200,\n  \"total_pages\": 4,\n  \"data\": [...]\n}\n```\n\nThe single pages can be requested with query parameters:\n\n| Parameter | Type      | Description                                             |\n| :-------- | :-------- | :------------------------------------------------------ |\n| `limit`   | `integer` | The maximum amount of objects to be returned on a page. |\n| `page`    | `integer` | The requested number of the page to return.             |\n\n### Processing Errors\n\nHellgate® uses the status codes to indicate the processing errors of the gateway operation as well as the results of connected services. \n\nThe response payload for processing errors follows a standard format:\n\n```json\n{\n  \"status\": \"the HTTP status code\",\n  \"classifier\": \"the classifer of the error\",\n  \"message\": \"interesting for humans...\",\n  \"validation_errors\": []\n}\n```\n\nThe error object contains the `classifier,` which allows you to identify the error as well as a human-readable `message`. In case the error refers back to a badly formed request, `validation_errors` is included.\n\nValidation errors itself hold a `message` describing the erroneous validation result and a `path` to point to the attribute in the JSON, which caused the problem.\n\n### Business Errors\n\nThe processing errors refer to the primary functions of Hellgate® 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://sandbox.hellgate.io
    description: Hellgate® Sandbox
  - url: https://api.hellgate.io
    description: Hellgate® Production
tags:
  - name: Network Tokens
    description: >
      This API allows the utilization of network tokens to securely request
      cryptograms for authentication.
  - name: Compliance Service
    description: >
      This API enables secure communication for exchanging Hellgate® tokens with
      original cardholder data.
  - name: Tokens
    description: >
      This API allows you to manage cardholder data in compliance with the rules
      of PCI/DSS and to provision network tokens. 
  - name: Merchants
    description: >
      This API is used to manage merchants so that they can make use of network
      tokenization. The full lifecycle of a merchant is supported, from creation
      to deletion.
x-tagGroups:
  - name: Authentications
    tags:
      - Customer Initiated Authentication
      - Merchant Initiated Authentication
      - Network Tokens
      - Authentication Management
  - name: Payment Processing
    tags:
      - Authentications
      - Compliance Service
  - name: Stored Payment Data
    tags:
      - Merchants
      - Tokens
  - name: Automation
    tags:
      - Stripe Backup
  - name: Reporting
    tags:
      - Reconciliation
paths:
  /encryption-key:
    post:
      summary: Returns the encryption key
      description: |
        Returns the encryption key to be used during the tokenization
      operationId: get_encryption_key
      tags:
        - Tokenization
      security:
        - APIKeyAuth: []
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptionKey'
        '400':
          $ref: '#/components/responses/400_BadRequestError'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
  /authentications/cof:
    post:
      summary: Standard
      description: |
        Authenticate a payment using credentials on file (COF).
      operationId: create_authentication_cof
      tags:
        - Customer Initiated Authentication
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationCofRequest'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /authentications/recurring:
    post:
      summary: Initial recurring
      description: |
        Authenticate for a recurring payment using Credentials on File (COF).
      operationId: create_recurring_authentication
      tags:
        - Customer Initiated Authentication
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationRecurringRequest'
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /authentications/recurring/{id}/subsequent:
    post:
      summary: Subsequent recurring
      description: >
        Authenticate for a subsequent recurring payment using Credentials on
        File (COF).
      operationId: create_subsequent_recurring_authentication
      tags:
        - Merchant Initiated Authentication
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Prior Recurring Authentication
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationSubsequentCreationRequest'
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /authentications/installment:
    post:
      summary: Initial installment
      description: |
        Authenticate for a installment payment using Credentials on File (COF).
      operationId: create_installment_authentication
      tags:
        - Customer Initiated Authentication
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationInstallmentRequest'
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /authentications/installment/{id}/subsequent:
    post:
      summary: Subsequent installment
      description: >
        Authenticate for a installment recurring payment using Credentials on
        File (COF).
      operationId: create_installment_recurring_authentication
      tags:
        - Merchant Initiated Authentication
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Prior Installment Authentication
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticationSubsequentCreationRequest'
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /authentications:
    get:
      summary: Get authentications
      description: >
        Get a list of all the authentications for this account.

        The results are grouped into pages. The caller can specify how many
        customers per page shall be listed (maximum is 500).
      operationId: get_authentications
      tags:
        - Authentication Management
      security:
        - APIKeyAuth: []
      parameters:
        - in: query
          name: type
          description: Parameter to filter the authentication types
          schema:
            type: string
          required: false
        - 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
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /authentications/{id}:
    get:
      summary: Get authentication details
      description: |
        Return the details of an authentication referenced by its id
      operationId: get_authentications_detail
      tags:
        - Authentication Management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the authentication.
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /reports/tokens:
    get:
      summary: Token Import Report
      description: >
        This report gives allowes to reconcile imported tokens from third-party
        sources.


        The report contains all Hellgate® tokens of the current account. The
        tokens are annotated with a `import_provider` and the corresponding
        `business_key` (i.e. the ID of the cardholder data at the provider).
      operationId: tokens_report
      tags:
        - Reconciliation
      security:
        - Bearer: []
        - APIKeyAuth: []
      responses:
        '200':
          description: Success response
          content:
            text/csv:
              schema:
                type: string
              example: >-
                id,import_provider,business_key,created_at

                "d3e14053-52c0-4b4a-9b24-6931a1eb2eb5",,,"2024-08-13
                15:44:26.559568"

                "cbc2c85f-53ce-4cd2-b7cf-d74c7c3983c2",,,"2024-08-13
                14:59:25.67196"

                "1d15fcbf-78f0-4a7f-b114-c918f6f7b144",,,"2024-08-13
                15:00:38.871148"

                "364073f3-47fd-4210-bb8a-5bc3d38bee3c","stripe","pm_1PsSCYCJ5AfyAmaKo4RuyX6v","2024-09-10
                10:04:27.018267"

                "fe2aaa36-d3fd-487a-8dfb-7735611a222e","stripe","pm_1PsSCBCJ5AfyAmaKNKtGoK0k","2024-09-10
                10:04:34.842439"

                "d1717e32-1324-4933-962f-0da7b21eebee","stripe","pm_1PsSC5CJ5AfyAmaKZoxU2bzz","2024-09-10
                10:04:36.802841"

                "a7ac16ab-a519-4986-931c-3d328fc8329f","stripe","pm_1PsSCOCJ5AfyAmaKudXbrJRE","2024-09-10
                10:04:30.382309"
          headers:
            Content-Disposition:
              schema:
                type: string
              example: attachment; filename="token_export.csv"
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /cde-import:
    post:
      summary: Import cardholder data
      description: >
        Import PAN data in exchange for a Hellgate® token.


        This endpoint allows a PCI DSS compliant entity to import PAN data in
        exchange for a Hellgate® token.
      operationId: import_cardholder_data
      tags:
        - Tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: header
          name: x-idempotency-key
          description: An optional idempotency key for safely retrying requests.
          schema:
            type: string
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardholderData'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HellgateToken'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Token_Notification'
  /tokens/session:
    post:
      summary: Request a token session
      description: |
        Create a session to start Hellgate® Tokenization using our SDK.
      operationId: create_tokenization_session
      tags:
        - Tokens
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenSessionCreate'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /tokens/{id}/refresh-session:
    post:
      summary: Request a CVC2 session
      description: >
        Create a session to update the Security Code from a Hellgate® Token
        using our SDK.
      operationId: refresh_secutiry_token_session
      tags:
        - Tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate® token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens:
    get:
      x-internal: false
      summary: Get tokens
      description: >
        Get a list of all Hellgate® 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
      security:
        - Bearer: []
        - 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 Hellgate®.
          schema:
            type: string
          required: false
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HellgateTokenList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /tokens/{id}:
    get:
      summary: Get token details
      description: Get a Hellgate® token by its identifer.
      operationId: get_tokenized_card
      tags:
        - Tokens
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate® token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HellgateToken'
        '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 Hellgate® token

        > 🚧 Warnings
        >
        > - This operation cannot be undone
        > - This operation will also delete enrollments of the token on devices
      operationId: remove_tokenized_card
      tags:
        - Tokens
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate® 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 availability
      description: >
        Get an indicator if security information for a stored Hellgate® token is
        still available.
      operationId: get_tokenized_card_security_information
      tags:
        - Tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate® 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}/consume:
    post:
      summary: Invalidate CVC2
      description: Invalidate the cache for Hellgate® CVC2.
      operationId: consume_security_code
      tags:
        - Tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate® 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 cryptogram (i.e. TAVV) for a Hellgate® token
      operationId: request_payment_data
      tags:
        - Network Tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: header
          name: x-idempotency-key
          description: An optional idempotency key for safely retrying requests.
          schema:
            type: string
          required: false
        - in: path
          name: id
          description: The ID of the Hellgate® 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
                    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
                    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'
  /tokens/{id}/provisions:
    post:
      summary: Network Token provision
      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:
        - Tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate® token
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HellgateToken'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens/card-art/{id}:
    get:
      summary: Request card art
      description: |
        Fetches a card art binary
      operationId: card_art_binary
      tags:
        - CardArt
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the card art.
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/CardArtBinary'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens/imports:
    post:
      summary: Request a token import
      description: >
        Requests the import of cardholder data from a third-party vault
        (currently supported source is stripe.com).


        The import processed in the background and its status can be queried by
        the returned import ID.

        During preparation and processing of a job it is not possible to create
        another import.
      operationId: tokens_import
      tags:
        - Stripe Backup
      security:
        - Bearer: []
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokensImportCreate'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensImport'
              examples:
                Preparing:
                  $ref: '#/components/examples/import_preparing'
                Running:
                  $ref: '#/components/examples/import_running'
                Finished:
                  $ref: '#/components/examples/import_finished'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /tokens/imports/{id}:
    get:
      summary: Get import details
      description: Show details of a token import
      operationId: get_tokens_details
      tags:
        - Stripe Backup
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the import.
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensImport'
              examples:
                Preparing:
                  $ref: '#/components/examples/import_preparing'
                Running:
                  $ref: '#/components/examples/import_running'
                Finished:
                  $ref: '#/components/examples/import_finished'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /tokens/imports/{id}/abort:
    post:
      summary: Abort an import
      description: |
        Abort a running token import.

        This is possible while the import is not finished or already aborted.
      operationId: tokens_import_abort
      tags:
        - Stripe Backup
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the import.
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensImport'
              example:
                value:
                  id: 63820065-af1a-42fa-b96f-8d928fc6c2ec
                  created_at: '2023-10-10T00:00:00Z'
                  finished_at: '2023-10-10T01:00:00Z'
                  provider: stripe
                  status: aborted
                  stripe:
                    api_key: '[REDACTED]'
                  attemts: 47
                  successes: 1
                  failures: 46
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /tokens/imports/{id}/failures:
    get:
      x-internal: false
      summary: Get import failures
      operationId: get_token_import_failures
      tags:
        - Stripe Backup
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the import.
          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
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokensImportFailureList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /forward:
    post:
      summary: Forward cardholder data
      description: >
        This endpoint allows to securely forward cardholder data to a certified
        third-party provider.

        It will inject sensitive cardholder data, referenced by a Hellgate®
        token, into the request before forwarding it.


        Hellgate requires certain HTTP headers for this feature. These headers
        are reserved and cannot be used by the caller:
          - `x-api-key` - **required** for request authentication
          - `x-hellgate-token` - **required** to identify the Hellgate token to use for the request
          - `x-destination-url` - **required** to define the target URL to which the request shall be forwarded
          - `x-hellgate-version` - **optional** to define the API version to use for the request

        In order to use the same header keys for the third-party provider,
        Hellgate allows to define key-value pairs with are resolved 

        and injected as HTTP headers before forwarding to the third-party
        provider. The following example illustrates the use:


        ```curl

        curl --location 'https://sandbox.hellgate.io/forward' \

        --header 'x-api-key: hlg-sbx-9876...'

        --header 'x-own-header-name: x-api-key' \

        --header 'x-own-header-value: 123456...' \

        ...

        ```


        The caller defines a custom header `x-own-header-name` with the value
        `x-api-key` which was previously reserved by Hellgate.

        The key-value pairs are matched on the term `x-own-header` in the
        example above.
      operationId: forward_request
      tags:
        - Compliance Service
      security:
        - APIKeyAuth: []
      parameters:
        - in: header
          name: x-hellgate-token
          description: The ID of the Hellgate token to use for the request.
          schema:
            type: string
            format: uuid
          required: true
        - in: header
          name: x-destination-url
          description: |
            The target URL to which the request shall be forwarded.

            Only allowed target URLs by the merchant can be request.
          schema:
            type: string
            format: uri
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: >
                The payload the caller wants to forward to the third party
                provider.


                In order to inject sensitive cardholder data templates can be
                used.


                | Placeholder              |
                Description                                          |

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

                | `{{ account_number }}`   | The actual full account number of
                the stored card.   |

                | `{{ expiration_year }}`  | Four digit year of the expiration
                date.              |

                | `{{ expiration_month }}` | Two digit month of the expiration
                date.              |

                | `{{ security_code }}`    | The security code of the card in
                case it is present. |
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: >
                The content-type can also be `x-www-form-urlencoded`, the
                payload is the same as the

                `application/json`


                In order to inject sensitive cardholder data templates can be
                used.


                | Placeholder              |
                Description                                          |

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

                | `{{ account_number }}`   | The actual full account number of
                the stored card.   |

                | `{{ expiration_year }}`  | Four digit year of the expiration
                date.              |

                | `{{ expiration_month }}` | Two digit month of the expiration
                date.              |

                | `{{ security_code }}`    | The security code of the card in
                case it is present. |
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                description: The response from the third party provider.
        '400':
          $ref: '#/components/responses/400_BadRequestError'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '407':
          $ref: '#/components/responses/407_ProxyAuthenticationRequiredError'
        '502':
          $ref: '#/components/responses/502_BadGatewayError'
        '503':
          $ref: '#/components/responses/503_ServiceUnavailableError'
        '504':
          $ref: '#/components/responses/504_GatewayTimeoutError'
  /merchants:
    post:
      summary: Create a merchant
      description: >
        Create a new merchant.


        Merchants represent legal entities which are interacting with the card
        networks.

        Onboarding merchants for an account is a prerequisite for creating
        network tokens. Depending on the setup of the account, this allows to 
        render complex ecommerce ecosystem setups.
      operationId: onboard_merchant
      tags:
        - Merchants
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: header
          name: x-idempotency-key
          description: An optional idempotency key for safely retrying requests.
          schema:
            type: string
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantOnboarding'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantFirstTime'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
    get:
      summary: Get merchants
      description: >
        Get a list of all merchants 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_merchants
      tags:
        - Merchants
      security:
        - Bearer: []
        - 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: sort
          description: >
            It allows sorting the result by legal_name or created_at. e.g
            `sort=legal_name+asc` or `sort=legal_name+desc`
          schema:
            type: string
          required: false
        - in: query
          name: from
          description: Return only merchants created from this date (YYYY-MM-DD).
          schema:
            type: string
            format: date-time
          required: false
        - in: query
          name: to
          description: Return only merchants created up to this date (YYYY-MM-DD).
          schema:
            type: string
            format: date-time
          required: false
        - in: query
          name: country_code
          description: >-
            Contry code in a list format e.g country_code=DE,
            country_code=US,AUS.
          schema:
            $ref: '#/components/schemas/CountryCode_3166_2'
          required: false
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /merchants/{id}:
    get:
      summary: Get merchant details
      description: Get the information of a merchant.
      operationId: get_merchant
      tags:
        - Merchants
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the merchant
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    patch:
      summary: Update merchant details
      description: Update the information of a merchant.
      operationId: update_merchant
      tags:
        - Merchants
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the merchant
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantUpdate'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Merchant'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    delete:
      summary: Delete a merchant
      description: |
        Remove a merchant from Hellgate.

        > 🚧 Warning
        >
        > This action is irreversible.
      operationId: remove_merchant
      tags:
        - Merchants
      security:
        - Bearer: []
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the merchant
          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'
components:
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    Bearer:
      type: apiKey
      name: OIDC id-token
      in: header
      description: 'The id-token with the `Bearer: ` prefix, e.g. "Bearer abcde12345".'
    WalletSessionAuth:
      type: apiKey
      name: X-Session-Token
      in: header
  schemas:
    EncryptionKey:
      type: object
      properties:
        jwk:
          type: object
          description: The key to be used when encrypting cardholder information.
        api_key:
          type: string
          description: >-
            An API-Key necessary to call the CDE service, this API expires in 15
            minutes.
      required:
        - encryption_key
        - api_key
    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'
    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)
    AuthenticationCofRequest:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        challenge_preference:
          type: string
          description: |
            The preference with respect to an eventual challenge.

            There is no guarantee that the preference can be fulfilled.
          default: CHALLENGE
          enum:
            - CHALLENGE
            - NO_PREFERENCE
            - NO_CHALLENGE
        purchase_date:
          type: string
          description: |
            The data when the purchase was made. Requires the 
            format `yyyyMMddHHmmss` and defaults to now.
        token_id:
          type: string
          description: The ID of the Hellgate® token which holds the credentials on file.
          format: uuid
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
      required:
        - amount
        - currency_code
        - token_id
    ActionRequirement:
      type: object
      properties:
        type:
          type: string
          description: The type of action requirement
          enum:
            - redirect
            - use_sdk
        target_url:
          type: string
          format: uri
          description: The target URL to redirect to
        session_id:
          type: string
          format: uuid
          description: The id of the session to use for the SDK
      required:
        - type
    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.
    Authentication:
      type: object
      properties:
        id:
          type: string
          description: The ID of the authentication
          format: uuid
        action_requirement:
          $ref: '#/components/schemas/ActionRequirement'
        amount:
          $ref: '#/components/schemas/Amount'
        authentication_result:
          type: object
          description: >
            The final result of the authentication.

            It holds in the cardholder authentication data (CAVV) and if there
            is a network token present, the token authentication data (TAVV).
          properties:
            cardholder_data:
              type: object
              description: The CAVV from the 3-D Secure authentication.
              properties:
                authentication_value:
                  type: string
                ds_transaction_id:
                  type: string
                eci:
                  type: string
                acs_transaction_id:
                  type: string
                challenge_cancel_reason:
                  type: string
                status:
                  type: string
                status_reason_code:
                  type: string
                version:
                  type: string
              required:
                - authentication_value
                - ds_transaction_id
                - eci
            encrypted_token_data:
              $ref: '#/components/schemas/EncryptedAuthenticationData'
          required:
            - cardholder_data
        challenge_preference:
          type: string
          description: |
            The preference with respect to an eventual challenge.

            There is no guarantee that the preference can be fulfilled.
          default: CHALLENGE
          enum:
            - CHALLENGE
            - NO_PREFERENCE
            - NO_CHALLENGE
        created_at:
          type: string
          description: The date-time the authentication was created (following ISO 8601)
          format: datetime
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        recurring_expiry:
          type: string
          description: |
            The date when the latest subsequent authentication can happen.
            Requires the format `yyyyMMdd`.
        recurring_frequency:
          type: integer
          description: Indicates the minimum number of days between authentications.
        failure_details:
          type: array
          description: >
            The reasons why an authentication failed during processing in
            Hellgate.
          items:
            type: object
            properties:
              classifier:
                type: string
              message:
                type: string
            required:
              - classifier
              - message
        finished_at:
          type: string
          description: The date-time the authentication was finished (following ISO 8601)
          format: datetime
        original_authentication:
          type: string
          format: uuid
          description: >-
            The ID of the original authentication in case of subsequent
            authentications
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
        number_of_installments:
          type: integer
          description: >-
            Indicates the maximum number of authorisations permitted for
            installment payments.
        purchase_date:
          type: string
          description: |
            The data when the purchase was made. Requires the
            format `yyyyMMddHHmmss` and defaults to now.
        status:
          type: string
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
        token_id:
          type: string
          description: The ID of the Hellgate® token which holds the credentials on file.
          format: uuid
        type:
          type: string
          enum:
            - COF_PAYMENT
            - RECURRING_PAYMENT
            - INSTALLMENT_PAYMENT
            - SUBSEQUENT_PAYMENT
      required:
        - amount
        - created_at
        - currency_code
        - id
        - status
        - token_id
        - type
    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
    ISO3166-3-CountryCode:
      type: string
      description: |
        A three letter country code.
        [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
    EMVCoAddressRecord:
      type: object
      description: A EMVCo compatible address record
      properties:
        city:
          type: string
        country:
          $ref: '#/components/schemas/ISO3166-3-CountryCode'
        line_1:
          type: string
        line_2:
          type: string
        line_3:
          type: string
        postal_code:
          type: string
        state:
          type: string
    CardholderInformation:
      type: object
      properties:
        addresses_match:
          type: boolean
          description: Indication that the billing address matches the shipping address
        billing_address:
          type: object
          properties:
            first_usage:
              type: string
              format: date-time
            address_details:
              $ref: '#/components/schemas/EMVCoAddressRecord'
        email:
          type: string
        home_phone:
          type: object
          properties:
            country_code:
              type: string
            number:
              type: string
        mobile_phone:
          type: object
          properties:
            country_code:
              type: string
            number:
              type: string
        shipping_address:
          type: object
          properties:
            name_matches_cardholder:
              type: boolean
              description: >-
                Indicates that the cardholder name is identical to the shipping
                name
            first_usage:
              type: string
              description: The date the shipping address was used the first time
              format: date-time
            address_details:
              $ref: '#/components/schemas/EMVCoAddressRecord'
        work_phone:
          type: object
          properties:
            country_code:
              type: string
            number:
              type: string
    AuthenticationRecurringRequest:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        challenge_preference:
          type: string
          description: |
            The preference with respect to an eventual challenge.

            There is no guarantee that the preference can be fulfilled.
          default: CHALLENGE
          enum:
            - CHALLENGE
            - NO_PREFERENCE
            - NO_CHALLENGE
        purchase_date:
          type: string
          description: |
            The data when the purchase was made. Requires the
            format `yyyyMMddHHmmss` and defaults to now.
        recurring_expiry:
          type: string
          description: |
            The date when the recurring should expiry. Requires
            the format `yyyyMMdd`.
        recurring_frequency:
          type: integer
          description: Indicates the minimum number of days between authorisations.
        token_id:
          type: string
          description: The ID of the Hellgate® token which holds the credentials on file.
          format: uuid
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
        cardholder_information:
          $ref: '#/components/schemas/CardholderInformation'
      required:
        - amount
        - currency_code
        - token_id
        - recurring_expiry
        - recurring_frequency
    AuthenticationSubsequentCreationRequest:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
      required:
        - amount
        - currency_code
    AuthenticationInstallmentRequest:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        challenge_preference:
          type: string
          description: |
            The preference with respect to an eventual challenge.

            There is no guarantee that the preference can be fulfilled.
          default: CHALLENGE
          enum:
            - CHALLENGE
            - NO_PREFERENCE
            - NO_CHALLENGE
        number_of_installments:
          type: integer
          description: >
            Indicates the maximum number of authorisations permitted for
            installment payments.
        purchase_date:
          type: string
          description: |
            The date when the purchase was made. Requires the
            format `yyyyMMddHHmmss` and defaults to now.
        recurring_expiry:
          type: string
          description: |
            The date when the recurring should expire. Requires
            the format `yyyyMMdd`.
        recurring_frequency:
          type: integer
          description: Indicates the minimum number of days between authorisations.
        token_id:
          type: string
          description: The ID of the Hellgate® token which holds the credentials on file.
          format: uuid
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
        cardholder_information:
          $ref: '#/components/schemas/CardholderInformation'
      required:
        - amount
        - currency_code
        - number_of_installments
        - token_id
        - recurring_expiry
        - recurring_frequency
    Pagination:
      type: object
      description: >
        The meta-data describing lists of data from the Hellgate® 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
    AuthenticationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Authentication'
        pagination:
          $ref: '#/components/schemas/Pagination'
    CardholderData:
      type: object
      properties:
        cardholder_name:
          type: string
          description: >
            The name of the owner of the card


            > ℹ️ Information

            >

            > Hellgate® only soft-deletes data. So in case of deletion this
            value will be anonymized.
        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

            >

            > Hellgate® 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
    HellgateTokenAuthenticationData:
      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
    HellgateToken:
      type: object
      properties:
        id:
          type: string
          description: The ID of the Hellgate® 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 Hellgate 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 Hellgate 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 Hellgate
            token..
          enum:
            - none
            - checked
            - skipped
        authentication_data:
          $ref: '#/components/schemas/HellgateTokenAuthenticationData'
        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 Hellgate®.


            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://api.hellgate.io/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
    Enrollment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique ID of the enrollment on Hellgate
        action_requirement:
          type: object
          description: An instruction to follow in order to complete an enrollment
          properties:
            type:
              type: string
              description: The type of the action that is requested
              enum:
                - otp
                - redirect_url
            otp:
              type: object
              properties:
                expires_at:
                  type: string
                  format: date-time
                  description: The time stamp when the possibility to submit OTP ends
                remaining_retries:
                  type: integer
                  description: The number of retries left to submit the OTP
              required:
                - expires_at
                - number_of_retries
            redirect_url:
              type: string
              format: uri
              description: The target URL to redirect to
          required:
            - type
        failure_details:
          type: array
          description: In case the enrollment fails, this array holds related reasons
          items:
            type: object
            properties:
              classifier:
                type: string
                description: Unique classifier of the error
              message:
                type: string
                description: Human readable information about the failure
              source:
                type: string
                enum:
                  - protocol
                  - scheme
        status:
          type: string
          description: >
            The status of the enrollment.


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

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

            | `pending`  | The enrollment is in progress (for instance an action
            requirement is present).                                |

            | `active`   | The enrollment is active and can be
            used.                                                                    
            |

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

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

            | `failed`   | The enrollment process
            failed.                                                                               
            |
          enum:
            - pending
            - active
            - inactive
            - deleted
            - failed
        device_information:
          type: object
          properties:
            id:
              type: string
              description: The ID of the device in the wallet
            os:
              type: string
              description: The operating system of the device
            type:
              type: string
              description: the type of the device
        token:
          $ref: '#/components/schemas/HellgateToken'
      required:
        - id
        - status
    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
            Hellgate® 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
    Session:
      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
    HellgateTokenList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/HellgateToken'
        pagination:
          $ref: '#/components/schemas/Pagination'
    SecurityCode:
      type: object
      properties:
        security_code_available:
          type: boolean
          description: Security Data available in the system
    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'
    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'
        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 Hellgate
      required:
        - id
        - amount
        - currency_code
        - merchant_id
        - reference
        - success
        - token_id
    CardArtBinary:
      type: string
      format: binary
    TokensImportCreate:
      type: object
      properties:
        provider:
          type: string
          description: |
            The source from where cardholder data shall be imported.
            Hellgate® supports currently stripe.com as input source.
          enum:
            - stripe
        stripe:
          type: object
          description: >
            This property holds the configuration data for the import from
            stripe.

            It must be present if the selected provider is `stripe`.
          properties:
            api_key:
              type: string
              example: sk_test_****
          required:
            - api_key
      required:
        - provider
    TokensImport:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the import.
        created_at:
          type: string
          description: The timestamp when the import was requested.
          format: date-time
        finished_at:
          type: string
          description: >
            The timestamp when the import was finished. 


            It is only available if the import was successfully finished or was
            aborted.
          format: date-time
        provider:
          type: string
          enum:
            - stripe
        status:
          type: string
          enum:
            - preparing
            - running
            - finished
            - aborted
          example: preparing
        stripe:
          type: object
          properties:
            api_key:
              type: string
              description: The redacted key which was sent when requesting the import.
              example: '[REDACTED]'
        attemts:
          type: integer
          description: The amount of attempts to import a token.
        successes:
          type: integer
          description: The amount of successful imports.
        failures:
          type: integer
          description: The amount of failures while importing a token.
    TokensImportFailure:
      type: object
      properties:
        reason:
          type: string
          description: The reason why the import failed
          example: destination_error
        context:
          type: object
          description: >-
            An object that describes the context of the failure to support
            failure analysis
    TokensImportFailureList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TokensImportFailure'
        pagination:
          $ref: '#/components/schemas/Pagination'
    CountryCode_3166_2:
      type: string
      description: The ISO 3166 two letter country code
    MerchantScheme:
      type: object
      properties:
        name:
          type: string
          description: The network scheme name
          enum:
            - visa
            - mastercard
        acquirer_bin:
          type: string
          description: The acquiring institution identification code
        requestor_id:
          type: string
          description: |
            The 3DS requestor identifier
            requestor_id and requestor_name should be sent in pairs.
        requestor_name:
          type: string
          description: |
            The 3DS requestor name
            requestor_id and requestor_name should be sent in pairs.
        category_code:
          type: string
          description: The DS-specific code describing the Merchant type of business
          format: '0000'
        merchant_id:
          type: string
          description: >
            Allow override the acquiring merchant id that can be used to specify
            per card scheme during

            the authentication.

            merchant_id and merchant_name should be sent in pairs.
        merchant_name:
          type: string
          description: >
            Allow override the merchant name that can be used to specify per
            card scheme during the

            authentication.

            merchant_id and merchant_name should be sent in pairs.
      required:
        - name
        - acquirer_bin
        - category_code
    Merchant:
      type: object
      properties:
        id:
          type: string
          description: The ID of the merchant
          format: uuid
        created_at:
          type: string
          description: The date-time the merchant was created (following ISO 8601)
          format: date-time
        company_city:
          type: string
          description: The city in the merchant's primary address.
        country_code:
          $ref: '#/components/schemas/ISO3166-2-CountryCode'
        encryption_key:
          type: string
          description: >
            The masked version of the key used to encrypt authentication data
            (for instance network token and cryptogram).

            A full copy of this information is returned only once, when the
            merchant was initially created.
        legal_name:
          type: string
          description: The name of the merchant
        website_url:
          type: string
          description: The URL of the merchant's website
          format: uri
        type:
          type: string
          description: The merchant type
          enum:
            - primary
            - submerchant
        identity_and_verification_enabled:
          type: boolean
          description: >
            The flag indicates if the 3DS identity and verification is required
            or not (only allowed for primary)
        3ds_enabled:
          type: boolean
          description: |
            Indicates if 3DS is available or not for the Merchant
        default_currency:
          $ref: '#/components/schemas/CurrencyCode'
        default_merchant_id:
          type: string
          description: The id for the Merchant
        schemes:
          type: array
          description: >-
            The schemes supported by the merchant (required if merchant has a
            merchant_id)
          items:
            $ref: '#/components/schemas/MerchantScheme'
      example:
        id: 00000000-0000-0000-0000-000000000000
        created_at: '2023-10-10T00:00:00Z'
        company_city: Berlin
        country_code: DE
        encryption_key: eyJhbGciO[redacted]
        legal_name: Example Merchant
        website_url: https://example.com
        type: submerchant
        identity_and_verification_enabled: false
        3ds_enabled: true
        default_currency: EUR
        default_merchant_id: 1234567890
        schemes:
          name: visa
          acquirer_bin: 40001
          requestor_id: 123456789.visa
          requestor_name: 3dsclient.local.visa
          category_code: 3200
          merchant_id: ''
          merchant_name: ''
      required:
        - id
        - created_at
        - company_city
        - country_code
        - encryption_key
        - legal_name
        - website_url
        - type
    MerchantList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Merchant'
        pagination:
          $ref: '#/components/schemas/Pagination'
    MerchantOnboarding:
      type: object
      properties:
        company_city:
          type: string
          description: The city in the merchant's primary address.
        country_code:
          $ref: '#/components/schemas/ISO3166-2-CountryCode'
        legal_name:
          type: string
          description: The name of the merchant
        website_url:
          type: string
          description: The URL of the merchant's website
          format: uri
        identity_and_verification_enabled:
          type: boolean
          description: >
            The flag indicates if the 3DS identity and verification is required
            or not (only allowed for primary)
        3ds_enabled:
          type: boolean
          description: |
            Indicates if 3DS is available or not for the Merchant
        default_currency:
          $ref: '#/components/schemas/CurrencyCode'
        default_merchant_id:
          type: string
          description: The id for the Merchant
        schemes:
          type: array
          description: >-
            The schemes supported by the merchant (required if merchant has a
            merchant_id)
          items:
            $ref: '#/components/schemas/MerchantScheme'
      example:
        company_city: Berlin
        country_code: DE
        legal_name: Example Merchant
        website_url: https://example.com
        identity_and_verification_enabled: false
        3ds_enabled: true
        default_currency: EUR
        default_merchant_id: 1234567890
        schemes:
          name: visa
          acquirer_bin: 40001
          requestor_id: 123456789.visa
          requestor_name: 3dsclient.local.visa
          category_code: 3200
          merchant_id: ''
          merchant_name: ''
      required:
        - company_city
        - country_code
        - legal_name
        - website_url
    MerchantFirstTime:
      type: object
      properties:
        id:
          type: string
          description: The ID of the merchant
          format: uuid
        created_at:
          type: string
          description: The date-time the merchant was created (following ISO 8601)
          format: date-time
        company_city:
          type: string
          description: The city in the merchant's primary address.
        country_code:
          $ref: '#/components/schemas/ISO3166-2-CountryCode'
        encryption_key:
          type: string
          description: >
            The key used to encrypt authentication data (for instance network
            token and cryptogram).

            This information is returned only once, when the merchant was
            initially created. Subsequent calls will return a masked value.
        legal_name:
          type: string
          description: The name of the merchant
        website_url:
          type: string
          description: The URL of the merchant's website
          format: uri
      example:
        id: 00000000-0000-0000-0000-000000000000
        created_at: '2023-10-10T00:00:00Z'
        company_city: Berlin
        country_code: DE
        encryption_key: eyJhbGciOiJSUzI1NiIsImVudGl0bGVtZW50IjoiYWF4NXdq...
        legal_name: Example Merchant
        website_url: https://example.com
      required:
        - id
        - created_at
        - company_city
        - country_code
        - encryption_key
        - legal_name
        - website_url
    MerchantUpdate:
      type: object
      properties:
        company_city:
          type: string
          description: The city in the merchant's primary address.
        country_code:
          $ref: '#/components/schemas/ISO3166-2-CountryCode'
        legal_name:
          type: string
          description: The name of the merchant
        website_url:
          type: string
          description: The URL of the merchant's website
          format: uri
        identity_and_verification_enabled:
          type: boolean
          description: >
            The flag indicates if the 3DS identity and verification is required
            or not (only allowed for primary)
        3ds_enabled:
          type: boolean
          description: |
            Indicates if 3DS is available or not for the Merchant
        default_currency:
          $ref: '#/components/schemas/CurrencyCode'
        default_merchant_id:
          type: string
          description: The id for the Merchant
        schemes:
          type: array
          description: >-
            The schemes supported by the merchant (required if merchant has a
            merchant_id)
          items:
            $ref: '#/components/schemas/MerchantScheme'
      required:
        - company_city
        - country_code
        - encryption_key
        - legal_name
        - website_url
        - type
        - legal_name
  responses:
    400_BadRequestError:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 400
            message: The request could not be handle due to invalid data
            classifier: BAD_REQUEST
    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 enrollment or 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:
                        - enrollment.created
                        - enrollment.updated
                        - enrollment.deleted
                        - token.created
                        - token.updated
                        - token.deleted
                    token:
                      $ref: '#/components/schemas/HellgateToken'
                    enrollment:
                      $ref: '#/components/schemas/Enrollment'
                  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://api.hellgate.io/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, Hellgate® will
                try to redeliver.
  examples:
    import_preparing:
      value:
        id: 63820065-af1a-42fa-b96f-8d928fc6c2ec
        created_at: '2023-10-10T00:00:00Z'
        provider: stripe
        status: preparing
        stripe:
          api_key: '[REDACTED]'
        attemts: 0
        successes: 0
        failures: 0
    import_running:
      value:
        id: 63820065-af1a-42fa-b96f-8d928fc6c2ec
        created_at: '2023-10-10T00:00:00Z'
        provider: stripe
        status: running
        stripe:
          api_key: '[REDACTED]'
        attemts: 100
        successes: 99
        failures: 1
    import_finished:
      value:
        id: 63820065-af1a-42fa-b96f-8d928fc6c2ec
        created_at: '2023-10-10T00:00:00Z'
        finished_at: '2023-10-10T01:00:00Z'
        provider: stripe
        status: finished
        stripe:
          api_key: '[REDACTED]'
        attemts: 200
        successes: 199
        failures: 1
