openapi: 3.0.3
info:
  title: Commerce 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{% admonition type=\"warning\" name=\"Gated Features\" %}\n  Some of the features offered by Hellgate are gated and require explicit activation. These features are clearly labeled with a `Gated` badge.\n\n  In order to get access you need to contact your account manager.\n{% /admonition %}\n\n{% admonition type=\"info\" name=\"Beta Features\" %}\n  Hellgate offers various features as part of our beta release track. These features are clearly labeled with a Beta badge in the documentation and interface.\n\n  By default, accounts do not have access to beta features unless explicitly subscribed to beta releases. If you would like to enable beta features, please \n  contact your account manager for subscription options.\n\n\t**⚠️ Beta features are experimental and subject to change or removal at any time. They may also have limited support and stability.**\n{% /admonition %}\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\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## 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### Request Errors\n\nHellgate uses the standard errors to indicate the client errors on the gateway level.\n\n{% tabs %}\n  {% tab label=\"Invalid Requests - HTTP 4xx\" %}\n    The 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    }\n    ```\n  {% /tab %}\n  {% tab label=\"Unprocessable Content - HTTP 422\" %}\n    The response payload for processing errors follows a standard \n    format which includes the validation errros.\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          \"path\": \"a JSON path pointing to the wrong data\",\n          \"message\": \"something interesting for humans...\"\n        }\n      ]\n    }\n    ```\n  {% /tab %}\n{% /tabs %}\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
x-tagGroups:
  - name: Payments
    tags:
      - payments_ci
      - payments_mi
      - payments_modifications
      - payments_data
      - refunds_data
  - name: Authentications
    tags:
      - authentications_ci
      - authentications_mi
      - authentications_data
  - name: Customer Data
    tags:
      - credentials_management
  - name: Tokens
    tags:
      - tokens_create
      - tokens_management
      - compliance_service
      - network_tokens
  - name: Configuration
    tags:
      - merchants
  - name: Automation
    tags:
      - processor_backup
      - reconciliation
tags:
  - name: payments_ci
    x-displayName: Customer Initiated
  - name: payments_mi
    x-displayName: Merchant Initiated
  - name: payments_modifications
    x-displayName: Payment Modifications
  - name: payments_data
    x-displayName: Payment Data
  - name: refunds_data
    x-displayName: Refund Data
  - name: authentications_ci
    x-displayName: Customer Initiated
    description: >
      Hellgate allows to process EMVCo 3-D Secure authentication requests as
      standalone request.


      For example, these endpoints can be used to process payment authentication
      centrally and 

      process the subsequent authorization requests conditionally on different
      payment processors.


      The secion of customer initiated authentications consists of three
      use-cases:


      {% table %}


      - Use-Case {% width="30%" %}

      - Description


      ---


      - One Off

      - A standard situation in which a single payment amount shall undergo 3-D
      Secure authentication.


      ---


      - Initial Recurring

      - An authentication of the first payment in the sequence of recurring
      payments.


      ---


      - Initial Installment

      - An authentication of the first payment in the sequence of installment
      payments.


      {% /table %}
  - name: authentications_mi
    x-displayName: Merchant Initiated (3RI)
    description: >
      Hellgate supports requestor-initiated EMVCo 3-D Secure authentication
      requests as standalone transactions.


      All requests in this section must be linked to a prior customer-initiated
      authentication.
  - name: authentications_data
    x-displayName: Authentication Data
    description: |
      Access the results of prior authentications for reference.
  - name: credentials_management
    x-displayName: Credentials on File
  - name: tokens_create
    x-displayName: Create Hellgate Tokens
    description: >
      Hellgate Tokens are powerful instrument to manage card holder data in a
      PCI/DSS compliant way.


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


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


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

      is automatically provisioned and maintained through its life-cycle.


      {% admonition type="info" %}
        The use of Network Tokens requires prior activation by your account manager.
      {% /admonition %}
  - name: merchants
    x-displayName: Merchants
    description: |
      Hellgate accounts support two operating models.

      {% tabs %}
        {% tab label="Single Merchant Model" %}
          This is the default model for accounts.

          - It is not possible to add sub-merchants (via `POST /merchants`)
          - It is not possible to delete the primary merchant (via `DELETE /merchants/{id}`)
        {% /tab %}
        {% tab label="Eco-System Model" %}
          This model enables ecosystem providers to manage sub-merchants, allowing them to execute specific 
          use cases within the ecosystem's framework.

          A common example is mobility ecosystems, where the main actor permits third parties to conduct transactions as needed.

          {% admonition type="info" name="Important information" %}
            The eco-system model requires activation by your account manager. Validate your specific scenario is required to grant access to the feature-set.
          {% /admonition %}
        {% /tab %}
      {% /tabs %}
  - name: reconciliation
    x-displayName: Reconciliation
  - name: processor_backup
    x-displayName: Processor Backup
    description: >
      In case your precious payment-method data is currently locked into an
      acquirer processor, Hellgate allows you to migrate the tokens
      automatically.

      Currently we support stripe.com, but more processors are on our list.
      Please ask you account manager for more information.


      Detailed documentation on how to migrate your stripe payment methods can
      be found on the [Hellgate Developer
      Documentation](https://developer.hellgate.dev/resources/imports/backup_stripe).
paths:
  /payments/one-off:
    post:
      summary: One-off
      description: >
        Request a one-off payment.


        This API endpoint is used to initiate a one-time payment that requires
        the customer to be actively on-session. 

        These payments involve real-time customer interactions and are the
        primary method for customer-initiated payments.


        Hellgate utilizes an action_requirement mechanism to prompt any
        necessary customer interactions during the payment process.

        The interactions are supported with SDKs. See the [Hellgate Developer
        Documentation](https://developer.hellgate.io) for more information.
      operationId: request_one_off_payment
      tags:
        - payments_ci
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequestOneTime'
            examples:
              guest:
                summary: Guest payment
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: checkout
              guest_storing_credentials:
                summary: Guest payment (Store Credentials)
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: checkout
                    store_credentials: true
              token:
                summary: Hellgate Token
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: token
                    token_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
              credential:
                summary: Stored Credentials
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: credential
                    credential_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
              platform:
                summary: Platform payment
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: credential
                    credential_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                  splits:
                    - type: seller
                      amount: 800
                      merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      reference: 'Order #12345 - Seller 1'
                    - type: commission
                      amount: 200
                      reference: 'Order #12345 - Commission'
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                require_action:
                  summary: Action required (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    action_requirement:
                      type: use_sdk
                      session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    reference: 'Order #12345'
                    status: processing
                    use_case: ONE_OFF
                platform:
                  summary: Platform payment (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    reference: 'Order #12345'
                    status: processing
                    use_case: ONE_OFF
                    splits:
                      - type: seller
                        amount: 800
                        merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        reference: 'Order #12345 - Seller 1'
                      - type: commission
                        amount: 200
                        reference: 'Order #12345 - Commission'
                missing_rules:
                  summary: Missing rules (Failed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    failure_details:
                      - classifier: PROCESSING_RULE_ERROR
                        message: 'Payment failed: No processing rule found.'
                        source: protocol
                    reference: 'Order #12345'
                    status: failed
                    use_case: ONE_OFF
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
              example:
                code: 400
                message: The request is invalid
                classifier: BAD_REQUEST
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Payment_Notification'
  /payments/unscheduled:
    post:
      summary: Initial unscheduled
      description: >
        Request the initial payment for unscheduled subsequent payments.


        This API endpoint is used to initiate an initial payment that requires
        the customer to be actively on-session. 

        With the payment successfully authorized, subsequent unscheduled
        payments can be made while the customer is off-session.


        Hellgate utilizes an action_requirement mechanism to prompt any
        necessary customer interactions during the payment process.

        The interactions are supported with SDKs. See the [Hellgate Developer
        Documentation](https://developer.hellgate.io) for more information.
      operationId: request_initial_unscheduled_payment
      tags:
        - payments_ci
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequestUnscheduled'
            examples:
              guest:
                summary: Initial guest payment
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: checkout
              token:
                summary: Initial with Hellgate Token
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: token
                    token_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
              credential:
                summary: Initial from stored Credentials
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  source:
                    type: credential
                    credential_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                require_action:
                  summary: Action required (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    action_requirement:
                      type: use_sdk
                      session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    reference: 'Order #12345'
                    status: processing
                    use_case: UNSCHEDULED
                missing_rules:
                  summary: Missing rules (Failed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    failure_details:
                      - classifier: PROCESSING_RULE_ERROR
                        message: 'Payment failed: No processing rule found.'
                        source: protocol
                    reference: 'Order #12345'
                    status: failed
                    use_case: UNSCHEDULED
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
              example:
                code: 400
                message: The request is invalid
                classifier: BAD_REQUEST
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Payment_Notification'
  /payments/recurring:
    post:
      summary: Initial recurring
      description: >
        Request the initial payment for recurring subsequent payments.


        This API endpoint is used to initiate an initial payment that requires
        the customer to be actively on-session. 

        With the payment successfully authorized, subsequent recurring payments
        can be made while the customer is off-session.


        Recurring payments must adhere to a predefined schedule to be
        successfully processed. 


        The following conditions must be met:
          - Expiration Limit: The `recurring_expiry` date must not be exceeded.
          - Frequency Compliance: The `recurring_frequency` must not be lower than the defined minimum. 
          - Amount Restriction: The `amount` must not exceed the initially authorized amount.

        Hellgate utilizes an action_requirement mechanism to prompt any
        necessary customer interactions during the payment process.

        The interactions are supported with SDKs. See the [Hellgate Developer
        Documentation](https://developer.hellgate.io) for more information.
      operationId: request_initial_recurring_payment
      tags:
        - payments_ci
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequestRecurring'
            examples:
              guest:
                summary: Initial guest payment
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  recurring_expiry: '20231010'
                  recurring_frequency: 28
                  source:
                    type: checkout
              token:
                summary: Initial with Hellgate Token
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  recurring_expiry: '20231010'
                  recurring_frequency: 28
                  source:
                    type: token
                    token_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
              credential:
                summary: Initial from stored Credentials
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Order #12345'
                  recurring_expiry: '20231010'
                  recurring_frequency: 28
                  source:
                    type: credential
                    credential_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                require_action:
                  summary: Action required (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    action_requirement:
                      type: use_sdk
                      session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    reference: 'Order #12345'
                    recurring_expiry: '20231010'
                    recurring_frequency: 28
                    status: processing
                    use_case: RECURRING
                missing_rules:
                  summary: Missing rules (Failed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    failure_details:
                      - classifier: PROCESSING_RULE_ERROR
                        message: 'Payment failed: No processing rule found.'
                        source: protocol
                    reference: 'Order #12345'
                    recurring_expiry: '20231010'
                    recurring_frequency: 28
                    status: failed
                    use_case: RECURRING
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
              example:
                code: 400
                message: The request is invalid
                classifier: BAD_REQUEST
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Payment_Notification'
  /payments/unscheduled/{id}/subsequent:
    post:
      summary: Unscheduled
      description: >
        Request a subsequent unscheduled payment.


        - The customer does not need to be on-session for this payment. 

        - If 3RI is enabled on the account, the payment request can include an
        off-session authentication initiated by the requestor.
      operationId: request_subsequent_unscheduled_payment
      tags:
        - payments_mi
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the initial payment
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequestSubsequent'
            example:
              amount: 1000
              currency_code: EUR
              authentication_preference: NO_3RI
              reference: 'Order #12345'
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                processing:
                  summary: Authorization in Progress (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    authentication_preference: NO_3RI
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    credential_id: 7d542f79-5f16-44e1-8fff-e8cbaf2597f9
                    initial_payment_id: 2c973d90-751e-4e66-a6bf-c53a9a56f93e
                    reference: 'Order #12345'
                    source:
                      type: card
                      cardholder_name: Bob Holder
                      expiry_month: 12
                      expiry_year: 2030
                      masked_account_number: 424242XXXXXX4242
                      pan_type: FPAN
                    status: processing
                    use_case: SUBSEQUENT_UNSCHEDULED
                missing_rules:
                  summary: Missing rules (Failed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    authentication_preference: NO_3RI
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    credential_id: 7d542f79-5f16-44e1-8fff-e8cbaf2597f9
                    initial_payment_id: 2c973d90-751e-4e66-a6bf-c53a9a56f93e
                    failure_details:
                      - classifier: PROCESSING_RULE_ERROR
                        message: 'Payment failed: No processing rule found.'
                        source: protocol
                    reference: 'Order #12345'
                    source:
                      type: card
                      cardholder_name: Bob Holder
                      expiry_month: 12
                      expiry_year: 2030
                      masked_account_number: 424242XXXXXX4242
                      pan_type: FPAN
                    status: failed
                    use_case: SUBSEQUENT_UNSCHEDULED
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
              example:
                code: 400
                message: The request is invalid
                classifier: BAD_REQUEST
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Payment_Notification'
  /payments/recurring/{id}/subsequent:
    post:
      summary: Recurring
      description: >
        Request a subsequent recurring payment.


        - The customer does not need to be on-session for this payment. 

        - If 3RI is enabled on the account, the payment request can include an
        off-session authentication initiated by the requestor.


        The request must to follow the schedule defined by the initial recurring
        payment.
      operationId: request_subsequent_recurring_payment
      tags:
        - payments_mi
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the initial payment
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequestSubsequent'
            example:
              amount: 1000
              currency_code: EUR
              authentication_preference: NO_3RI
              reference: 'Order #12345'
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                processing:
                  summary: Authorization in Progress (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    authentication_preference: NO_3RI
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    credential_id: 7d542f79-5f16-44e1-8fff-e8cbaf2597f9
                    initial_payment_id: 2c973d90-751e-4e66-a6bf-c53a9a56f93e
                    reference: 'Order #12345'
                    source:
                      type: card
                      cardholder_name: Bob Holder
                      expiry_month: 12
                      expiry_year: 2030
                      masked_account_number: 424242XXXXXX4242
                      pan_type: FPAN
                    status: processing
                    use_case: SUBSEQUENT_RECURRING
                missing_rules:
                  summary: Missing rules (Failed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    authentication_preference: NO_3RI
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    credential_id: 7d542f79-5f16-44e1-8fff-e8cbaf2597f9
                    initial_payment_id: 2c973d90-751e-4e66-a6bf-c53a9a56f93e
                    failure_details:
                      - classifier: PROCESSING_RULE_ERROR
                        message: 'Payment failed: No processing rule found.'
                        source: protocol
                    reference: 'Order #12345'
                    source:
                      type: card
                      cardholder_name: Bob Holder
                      expiry_month: 12
                      expiry_year: 2030
                      masked_account_number: 424242XXXXXX4242
                      pan_type: FPAN
                    status: failed
                    use_case: SUBSEQUENT_RECURRING
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
              example:
                code: 400
                message: The request is invalid
                classifier: BAD_REQUEST
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Payment_Notification'
  /payments/{id}/capture:
    post:
      summary: Capture
      description: >
        Attempts to capture a payment that is currently in authorized. 


        The attributes `amount` and `currency_code` are optional. 

        If not provided, the full authorized amount will be captured.


        If a partial amount is provided, it must be less than or equal 

        to the authorized amount and the currency must match the authorized
        amount.


        The operation is asynchronous such that the result will be communicated
        via a notifcation.
      operationId: capture_payment
      tags:
        - payments_modifications
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the payment on Hellgate.
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaptureCreate'
            examples:
              full_capture:
                summary: Full capture
                value:
                  reference: 'Full capture order #12345'
              partial_capture:
                summary: Partial capture
                value:
                  amount: 800
                  currency_code: EUR
                  reference: 'Partial capture order #12345'
              partial_capture_on_platform:
                summary: Partial capture on platform
                value:
                  amount: 800
                  currency_code: EUR
                  reference: 'Partial capture order #12345'
                  splits:
                    - type: seller
                      amount: 750
                      merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      reference: 'Order #12345 - Seller 1'
                    - type: commission
                      amount: 50
                      reference: 'Order #12345 - Commission'
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Capture accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                full_capture:
                  summary: Full capture (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                      authorized: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    flow_matrix_rule: e-commerce flow
                    reference: 'Order #12345'
                    status: capturing
                    source:
                      type: card
                      cardholder_name: Bob Holder
                      expiry_month: 12
                      expiry_year: 2030
                      masked_account_number: 424242XXXXXX4242
                      pan_type: FPAN
                    use_case: ONE_OFF
                partial_capture_on_platform:
                  summary: Partial capture on platform (Success)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                      authorized: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    flow_matrix_rule: e-commerce flow
                    reference: 'Order #12345'
                    splits:
                      - type: seller
                        amount: 750
                        merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        reference: 'Order #12345 - Seller 1'
                      - type: commission
                        amount: 50
                        reference: 'Order #12345 - Commission'
                    status: capturing
                    source:
                      type: card
                      cardholder_name: Bob Holder
                      expiry_month: 12
                      expiry_year: 2030
                      masked_account_number: 424242XXXXXX4242
                      pan_type: FPAN
                    use_case: ONE_OFF
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
              example:
                code: 400
                message: The request is invalid
                classifier: BAD_REQUEST
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Payment_Notification'
  /payments/{id}/void:
    post:
      summary: Void
      description: >
        Attempts to void a payment.


        Hellgate will attempt to interrupt the payment processing and reverse
        the transaction. 

        However, this operation may not always succeed due to limitations
        imposed by specific payment 

        methods or providers. If the void operation is not possible, the payment
        will continue 

        processing until it reaches its terminal state (e.g., successful
        completion or failure).


        The operation is asynchronous such that the result will be communicated
        via a notifcation.
      operationId: cancel_payment
      tags:
        - payments_modifications
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the payment on Hellgate.
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Cancel accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              example:
                id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                amount:
                  requested: 1000
                  authorized: 1000
                created_at: '2023-10-10T00:00:00Z'
                currency_code: EUR
                flow_matrix_rule: e-commerce flow
                reference: 'Order #12345'
                status: voiding
                source:
                  type: card
                  cardholder_name: Bob Holder
                  expiry_month: 12
                  expiry_year: 2030
                  masked_account_number: 424242XXXXXX4242
                  pan_type: FPAN
                use_case: ONE_OFF
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
              example:
                code: 400
                message: The request is invalid
                classifier: BAD_REQUEST
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
      callbacks:
        notification:
          $ref: '#/components/callbacks/Payment_Notification'
  /payments:
    get:
      summary: Get payments
      description: >
        Retrieves a paginated list of payments associated with the account. 


        Payments are sorted in reverse chronological order (most recent first). 

        The caller can specify the number of payments per page using a query
        parameter, 

        with a maximum limit of 500 payments per page. If no value is provided,
        a default 

        number of payments per page will be used.
      operationId: list_payments
      tags:
        - payments_data
      security:
        - APIKeyAuth: []
      parameters:
        - in: query
          name: limit
          description: The desired amount of records per page.
          schema:
            type: integer
            minimum: 1
            default: 50
            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 payments created from this date.
          schema:
            type: string
            format: YYYY-MM-DD
          required: false
        - in: query
          name: to
          description: Return only payments created up to this date.
          schema:
            type: string
            format: YYYY-MM-DD
          required: false
        - in: query
          name: currency_code
          description: |
            Return only payments with the specified currencies.

            Currencies are in ISO 4217 and use a list formats, e.g.:
              - `currency_code=EUR`
              - `currency_code=EUR,USD`
          schema:
            type: string
          required: false
        - in: query
          name: status
          description: |
            Return only payments with the specified status.

            Status are given as a list, e.g.: 
              - `status=authorized`
              - `status=authorized,captured`.
          schema:
            type: string
          required: false
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponseList'
              example:
                data:
                  - id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                      authorized: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    flow_matrix_rule: e-commerce flow
                    reference: 'Order #12345'
                    status: authorized
                    source:
                      type: card
                      cardholder_name: Bob Holder
                      expiry_month: 12
                      expiry_year: 2030
                      masked_account_number: 424242XXXXXX4242
                      pan_type: FPAN
                    use_case: ONE_OFF
                pagination:
                  current_page: 1
                  page_size: 50
                  total_items: 1
                  total_pages: 1
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /payments/{id}:
    get:
      summary: Get payment details
      description: Returns the details of the payment with the specified identifier.
      operationId: get_payment
      tags:
        - payments_data
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the payment on Hellgate.
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                require_action:
                  summary: Requires Action
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    action_requirement:
                      type: use_sdk
                      session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    reference: 'Order #12345'
                    status: processing
                    use_case: ONE_OFF
                authorized:
                  summary: Authorized (with Credential ID)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                      authorized: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    credential_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    currency_code: EUR
                    reference: 'Order #12345'
                    status: authorized
                    use_case: ONE_OFF
                missing_rules:
                  summary: Missing rules (Failed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount:
                      requested: 1000
                    created_at: '2023-10-10T00:00:00Z'
                    currency_code: EUR
                    failure_details:
                      - classifier: PROCESSING_RULE_ERROR
                        message: 'Payment failed: No processing rule found.'
                        source: protocol
                    reference: 'Order #12345'
                    status: failed
                    use_case: ONE_OFF
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /payments/{id}/transactions:
    get:
      summary: List transactions
      description: >
        Retrieves a paginated list of all transactions associated with a
        payment. 


        The results are grouped into pages, and the caller can specify the
        number of transactions 

        per page via a query parameter, with a maximum limit of 500 transactions
        per page. If no 

        value is specified, a default page size will be used.
      operationId: list_payment_transactions
      tags:
        - payments_data
      security:
        - APIKeyAuth: []
      parameters:
        - in: query
          name: limit
          description: The desired amount of records per page.
          schema:
            type: integer
            minimum: 0
            default: 50
            maximum: 500
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 0
          required: false
        - in: path
          name: id
          description: The ID of the payment on Hellgate.
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
              example:
                data:
                  - id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    type: authorize
                    status: succeeded
                    started_at: '2021-01-01T00:00:00Z'
                    finished_at: '2021-01-01T00:00:00Z'
                    processor:
                      name: Starfish Bank
                      transaction_id: ch_1H9zvz2eZvKYlo2C5J1J9zvz
                      merchant_id: acct_1H9zvz2eZvKYlo2C
                      network_transaction_reference: '1234567890'
                pagination:
                  current_page: 1
                  page_size: 50
                  total_items: 1
                  total_pages: 1
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /payments/{id}/refunds:
    post:
      summary: Refund
      description: >
        Request a refund for a payment.


        This API endpoint is used to initiate a refund for a payment that has
        been successfully captured.

        Refunds can be in full or partial. Depending on the payment method, the
        refund may take a few days to be processed.
      operationId: create_refund
      tags:
        - payments_modifications
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the payment.
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundCreate'
            examples:
              full_refund:
                summary: Full refund
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Refund order #12345'
              full_refund_on_platform:
                summary: Full refund on platform
                value:
                  amount: 1000
                  currency_code: EUR
                  reference: 'Refund order #12345'
                  splits:
                    - type: seller
                      amount: 900
                      merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      reference: 'Refund order #12345 - Seller 1'
                    - type: commission
                      amount: 100
                      reference: 'Refund order #12345 - Commission'
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Refund accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
              examples:
                full_refund:
                  summary: Full refund (Processing)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount: 1000
                    currency_code: EUR
                    created_at: '2023-10-10T00:00:00Z'
                    payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                    reference: 'Refund order #12345'
                    status: processing
                full_refund_on_platform:
                  summary: Full refund on platform (Processing)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount: 1000
                    currency_code: EUR
                    created_at: '2023-10-10T00:00:00Z'
                    payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                    reference: 'Refund order #12345'
                    splits:
                      - type: seller
                        amount: 900
                        merchant_id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        reference: 'Refund order #12345 - Seller 1'
                      - type: commission
                        amount: 100
                        reference: 'Refund order #12345 - Commission'
                    status: processing
                completed:
                  summary: Refund (completed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount: 1000
                    currency_code: EUR
                    created_at: '2023-10-10T00:00:00Z'
                    payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                    reference: 'Refund order #12345'
                    status: completed
                failed:
                  summary: Refund (Failed)
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount: 1000
                    currency_code: EUR
                    created_at: '2023-10-10T00:00:00Z'
                    failure_details:
                      - classifier: TRANSACTION_ERROR
                        message: 'Transaction failed: No refund possible.'
                        source: processor
                      - classifier: PAYMENT_FAILURE
                        message: 'Refund failed: Transaction not successful.'
                        source: protocol
                    payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                    reference: 'Refund order #12345'
                    status: failed
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGeneric'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
        '409':
          $ref: '#/components/responses/409_ConflictError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
      callbacks:
        refund_notification:
          $ref: '#/components/callbacks/Refund_Notification'
        payment_notification:
          $ref: '#/components/callbacks/Payment_Notification'
    get:
      summary: Get refunds
      description: |
        Get a list of all refunds that belong to a payment.
      operationId: list_refunds_of_payment
      tags:
        - payments_data
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the payment on Hellgate.
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /refunds/{id}:
    get:
      summary: Get refund details
      description: |
        Get the details of a refund.
      operationId: get_a_refund
      tags:
        - refunds_data
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the refund on Hellgate.
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
              examples:
                processing:
                  summary: refund.processing
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount: 1000
                    currency_code: EUR
                    created_at: '2023-10-10T00:00:00Z'
                    payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                    reference: 'Refund order #12345'
                    status: processing
                completed:
                  summary: refund.completed
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount: 1000
                    currency_code: EUR
                    created_at: '2023-10-10T00:00:00Z'
                    payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                    reference: 'Refund order #12345'
                    status: completed
                failed:
                  summary: refund.failed
                  value:
                    id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    amount: 1000
                    currency_code: EUR
                    created_at: '2023-10-10T00:00:00Z'
                    failure_details:
                      - classifier: TRANSACTION_ERROR
                        message: 'Transaction failed: No refund possible.'
                        source: processor
                      - classifier: PAYMENT_FAILURE
                        message: 'Refund failed: Transaction not successful.'
                        source: protocol
                    payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                    reference: 'Refund order #12345'
                    status: failed
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /refunds/{id}/transactions:
    get:
      summary: List transactions
      description: >
        Retrieves a paginated list of all transactions associated with a
        refund. 


        The results are grouped into pages, and the caller can specify the
        number of transactions 

        per page via a query parameter, with a maximum limit of 500 transactions
        per page. If no 

        value is specified, a default page size will be used.
      operationId: list_refund_transactions
      tags:
        - refunds_data
      security:
        - APIKeyAuth: []
      parameters:
        - in: query
          name: limit
          description: The desired amount of records per page.
          schema:
            type: integer
            minimum: 0
            default: 50
            maximum: 500
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 0
          required: false
        - in: path
          name: id
          description: The ID of the refund on Hellgate.
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
              example:
                data:
                  - id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                    type: refund
                    status: succeeded
                    started_at: '2021-01-01T00:00:00Z'
                    finished_at: '2021-01-01T00:00:00Z'
                    processor:
                      name: Starfish Bank
                      transaction_id: ch_1H9zvz2eZvKYlo2C5J1J9zvz
                      merchant_id: acct_1H9zvz2eZvKYlo2C
                      network_transaction_reference: '1234567890'
                pagination:
                  current_page: 1
                  page_size: 50
                  total_items: 1
                  total_pages: 1
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /authentications/one-off:
    post:
      summary: One-off
      description: >
        Request an authentication for a one-off payment.


        This API endpoint triggers a 3-D Secure (3DS) authentication without
        processing a payment. 

        It is used to verify a customer's identity before completing a
        transaction or for regulatory 

        compliance (e.g., Strong Customer Authentication - SCA).


        The customer must be on-session to complete the authentication. Hellgate
        utilizes the action_requirement mechanism to 

        request any necessary interaction with the customer. The interactions
        are supported with SDKs. See the 

        [Hellgate Developer Documentation](https://developer.hellgate.io) for
        more information.
      operationId: create_authentication_cof
      tags:
        - authentications_ci
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OneOffRequest'
            examples:
              minimal:
                summary: Minimal
                value:
                  amount: 1000
                  currency_code: EUR
                  source:
                    type: token
                    token_id: 71820e49-6822-4df1-8db5-d245456172b6
              no_challenge:
                summary: No Challenge for specific Merchant
                value:
                  amount: 1000
                  currency_code: EUR
                  challenge_preference: NO_CHALLENGE
                  merchant_id: 5bcf18e8-cd66-420e-9eb7-ed503c503653
                  source:
                    type: token
                    token_id: 71820e49-6822-4df1-8db5-d245456172b6
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
              example:
                id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                amount: 1000
                currency_code: EUR
                action_requirement:
                  type: use_sdk
                  session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                created_at: '2023-10-10T00:00:00Z'
                challenge_preference: CHALLENGE
                purchase_date: '20241010000000'
                use_case: ONE_OFF
                source:
                  type: token
                  token_id: 71820e49-6822-4df1-8db5-d245456172b6
                status: PROCESSING
        '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: >
        Request an authentication for an initial recurring payment.


        This API endpoint triggers a 3-D Secure (3DS) authentication without
        processing a payment. 

        It is used to verify a customer's identity before completing a
        transaction or for regulatory 

        compliance (e.g., Strong Customer Authentication - SCA).


        The customer must be on-session to complete the authentication. Hellgate
        utilizes the action_requirement mechanism to 

        request any necessary interaction with the customer. The interactions
        are supported with SDKs. See the 

        [Hellgate Developer Documentation](https://developer.hellgate.io) for
        more information.
      operationId: create_recurring_authentication
      tags:
        - authentications_ci
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringRequest'
            example:
              amount: 1000
              currency_code: EUR
              recurring_expiry: '20231231'
              recurring_frequency: 28
              source:
                type: token
                token_id: 71820e49-6822-4df1-8db5-d245456172b6
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
              example:
                id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                amount: 1000
                currency_code: EUR
                action_requirement:
                  type: use_sdk
                  session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                created_at: '2023-10-10T00:00:00Z'
                purchase_date: '20241010000000'
                recurring_expiry: '20231231'
                recurring_frequency: 28
                use_case: INITIAL_RECURRING
                source:
                  type: token
                  token_id: 71820e49-6822-4df1-8db5-d245456172b6
                status: PROCESSING
        '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.

        This authentication is initiated by the requestor (3RI) and will not 
        require interactions with customers; it can be run off-session.
      operationId: create_subsequent_recurring_authentication
      tags:
        - authentications_mi
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the original recurring authentication
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubsequentRequest'
            example:
              amount: 1000
              currency_code: EUR
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
              example:
                id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                amount: 1000
                currency_code: EUR
                created_at: '2023-10-10T00:00:00Z'
                challenge_preference: CHALLENGE
                original_authentication: 75de8951-0066-4702-9eb5-dd298974e95a
                purchase_date: '20241010000000'
                recurring_expiry: '20231231'
                recurring_frequency: 28
                use_case: SUBSEQUENT_RECURRING
                source:
                  type: token
                  token_id: 71820e49-6822-4df1-8db5-d245456172b6
                status: PROCESSING
        '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: >
        Request an authentication for an initial installment payment.


        This API endpoint triggers a 3-D Secure (3DS) authentication without
        processing a payment. 

        It is used to verify a customer's identity before completing a
        transaction or for regulatory 

        compliance (e.g., Strong Customer Authentication - SCA).


        The customer must be on-session to complete the authentication. Hellgate
        utilizes the action_requirement mechanism to 

        request any necessary interaction with the customer. The interactions
        are supported with SDKs. See the 

        [Hellgate Developer Documentation](https://developer.hellgate.io) for
        more information.
      operationId: create_installment_authentication
      tags:
        - authentications_ci
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallmentRequest'
            example:
              amount: 1000
              currency_code: EUR
              recurring_expiry: '20231231'
              recurring_frequency: 28
              number_of_installments: 12
              source:
                type: token
                token_id: 71820e49-6822-4df1-8db5-d245456172b6
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
              example:
                id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                amount: 1000
                currency_code: EUR
                action_requirement:
                  type: use_sdk
                  session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                created_at: '2023-10-10T00:00:00Z'
                challenge_preference: CHALLENGE
                purchase_date: '20241010000000'
                recurring_expiry: '20231231'
                recurring_frequency: 28
                number_of_installments: 12
                use_case: INITIAL_INSTALLMENT
                source:
                  type: token
                  token_id: 71820e49-6822-4df1-8db5-d245456172b6
                status: PROCESSING
        '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 subsequent installment payment.

        This authentication is initiated by the requestor (3RI) and will not 
        require interactions with customers; it can be run off-session.
      operationId: create_installment_recurring_authentication
      tags:
        - authentications_mi
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the original installment authentication
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubsequentRequest'
            example:
              amount: 1000
              currency_code: EUR
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Authentication created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
              example:
                id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                amount: 1000
                currency_code: EUR
                created_at: '2023-10-10T00:00:00Z'
                challenge_preference: CHALLENGE
                original_authentication: 75de8951-0066-4702-9eb5-dd298974e95a
                purchase_date: '20241010000000'
                recurring_expiry: '20231231'
                recurring_frequency: 28
                number_of_installments: 12
                use_case: SUBSEQUENT_INSTALLMENT
                source:
                  type: token
                  token_id: 71820e49-6822-4df1-8db5-d245456172b6
                status: PROCESSING
        '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:
        - authentications_data
      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
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationList'
              example:
                data:
                  - id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                    amount: 1000
                    currency_code: EUR
                    action_requirement:
                      type: use_sdk
                      session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                    created_at: '2023-10-10T00:00:00Z'
                    challenge_preference: CHALLENGE
                    purchase_date: '20241010000000'
                    use_case: ONE_OFF
                    source:
                      type: token
                      token_id: 71820e49-6822-4df1-8db5-d245456172b6
                    status: PROCESSING
                pagination:
                  current_page: 1
                  page_size: 1
                  total_items: 1
                  total_pages: 1
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
  /authentications/{id}:
    get:
      summary: Get an authentication
      description: |
        Return the details of an authentication referenced by its id
      operationId: get_authentications_detail
      tags:
        - authentications_data
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the authentication.
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authentication'
              example:
                id: 7dcb4365-a948-4b41-a2d2-a7bffa2d3994
                amount: 1000
                currency_code: EUR
                action_requirement:
                  type: use_sdk
                  session_id: d5b8e449-13da-4594-bf00-643146fb35d1
                created_at: '2023-10-10T00:00:00Z'
                challenge_preference: CHALLENGE
                purchase_date: '20241010000000'
                use_case: ONE_OFF
                source:
                  type: token
                  token_id: 71820e49-6822-4df1-8db5-d245456172b6
                status: PROCESSING
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /credentials:
    get:
      summary: Get credentials
      description: |
        Get a list of credentials on file which 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_credentials
      tags:
        - credentials_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: query
          name: limit
          description: The desired amount of records per page.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 1
          required: false
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /credentials/{id}:
    get:
      summary: Get credential details
      description: Get the detail information about stored credentials.
      operationId: get_credential
      tags:
        - credentials_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the credential
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
    delete:
      summary: Delete credentials
      description: |
        Remove a credentials from Hellgate.

        {% admonition type="info" name="Information" %}
          Hellgate only soft-deletes data. So in case of deletion this value will be anonymized.
        {% /admonition %}
      operationId: remove_credentials
      tags:
        - credentials_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the credential
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Beta
          position: after
      responses:
        '204':
          description: Success response (No Content)
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /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_create
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenSessionCreate'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenSession'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
  /cde-import:
    post:
      summary: Create token from FPAN
      description: |
        Import cardholder-data in exchange for a Hellgate token.

        {% admonition type="warning" name="Compliance Check Required" %}
          In order to use this endpoint you need to prove a certain level of compliance with PCI/DSS with us.
          Reach out to your account manager for more information.
        {% /admonition %}
      operationId: import_cardholder_data
      tags:
        - tokens_create
      security:
        - APIKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardholderData'
      x-badges:
        - name: Gated
          position: after
          color: orange
      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:
    get:
      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_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: query
          name: limit
          description: >-
            The desired amount of records per page. The parameter defaults to 50
            if it is omitted and has a maximum of 500.
          schema:
            type: integer
            minimum: 1
            maximum: 500
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 1
          required: false
        - in: query
          name: from
          description: Return only network tokens created from this date (YYYY-MM-DD).
          schema:
            type: string
            format: date-time
          required: false
        - in: query
          name: to
          description: Return only network tokens created up to this date (YYYY-MM-DD).
          schema:
            type: string
            format: date-time
          required: false
        - in: query
          name: sort
          description: >
            It allows sorting the result by created_at. e.g
            `sort=created_at+asc` or `sort=created_at+desc`
          schema:
            type: string
          required: false
        - in: query
          name: network_token_status
          description: >-
            Requested status in list format e.g `network_token_status=active` or
            `network_token_status=active,inactive`
          schema:
            $ref: '#/components/schemas/NetworkTokenStatus'
          required: false
        - in: query
          name: scheme
          description: >-
            Requested card schemes in list format e.g `scheme=VISA` or
            `scheme=VISA,MASTERCARD`
          schema:
            $ref: '#/components/schemas/CardScheme'
          required: false
        - in: query
          name: business_key
          description: >-
            Request tokens which the exact match of this value.


            The business key is a reference of the original ID under which the
            cardholder data was stored on the system from which it was imported
            to 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_management
      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'
    delete:
      summary: Delete a token
      description: >
        Remove a Hellgate token and all associated information (e.g. network
        tokens).


        {% admonition type="warning" name="Warning" %}
          This operation cannot be undone.
        {% /admonition %}
      operationId: remove_tokenized_card
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the 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
      description: >
        Get an indicator if security information for a stored Hellgate token is
        still available.
      operationId: get_tokenized_card_security_information
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the 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}/refresh-session:
    post:
      summary: Refresh CVC2
      description: >
        Create a session to update the Security Code from a Hellgate Token using
        our SDK.
      operationId: refresh_secutiry_token_session
      tags:
        - tokens_management
      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/TokenSession'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /tokens/{id}/consume:
    post:
      summary: Consume a token
      description: >-
        Tell Hellgate after successful use of the token for an payment
        authorization, that the CVC2 can be removed from cache.
      operationId: consume_security_code
      tags:
        - tokens_management
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the 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'
  /forward:
    post:
      summary: Forward card 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.


                To securely handle and inject sensitive cardholder data,
                predefined templates can be 

                used. These templates help structure and standardize the data
                injection process while 

                ensuring compliance with security and regulatory requirements. 


                | Placeholder              |
                Description                                          |

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

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

                | `{{ cardholder_name }}`  | The name of the
                cardholder.                          |

                | `{{ 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. |


                All injected data will be represented as a string in the
                payload. If a specific data 

                type is required, such as a numeric representation of the
                expiration month, the data 

                can be unwrapped and converted back to its original type as
                needed: `{{ expiration_month | unwrap }}`.
            examples:
              adyen:
                description: Forward a payment request to Adyen
                value:
                  paymentMethod:
                    type: scheme
                    number: '{{ account_number }}'
                    expiryMonth: '{{ expiration_month}}'
                    expiryYear: '{{ expiration_year}}'
                    cvc: '{{ security_code }}'
              worldpay:
                description: Forward a payment request to Worldpay
                value:
                  transactionReference: My reference
                  instruction:
                    method: card
                    paymentInstrument:
                      type: plain
                      cardNumber: '{{ account_number }}'
                      expiryDate:
                        month: '{{ expiration_month | unwrap }}'
                        year: '{{ expiration_year | unwrap }}'
                  value:
                    currency: EUR
                    amount: 1000
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: >
                The content-type can also be `x-www-form-urlencoded`.


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


                | Placeholder              |
                Description                                          |

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

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

                | `{{ cardholder_name }}`  | The name of the
                cardholder.                          |

                | `{{ 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. |
            examples:
              stripe:
                description: Forward a payment request to Stripe
                value:
                  paymentMethod:
                    type: card
                    card:
                      number: '{{ account_number }}'
                      exp_month: '{{ expiration_month}}'
                      exp_year: '{{ expiration_year}}'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                description: The response from the third party provider.
            application/x-www-form-urlencoded:
              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'
  /tokens/{id}/provisions:
    post:
      summary: Update a network token
      description: >
        If the provisioning of a network token status is `failed` or
        `not_available`

        for any reason, this endpoint can be used to provision a network token.
      operationId: network_token_provision
      tags:
        - network_tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate token
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Gated
          position: after
          color: orange
      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/{id}/payment-data:
    post:
      summary: Request payment-data
      description: >
        Request a payment-data bundle for a Hellgate token.


        The bundle can contain various elements including the TAVV cryptogram
        for a network token.


        {% admonition type="info" %}

        This call supports the all operating models of Hellgate (**single
        merchant** and **eco-systems**).


        For eco-systems you need to specify which merchant you want to request
        the crypotgram for.

        {% /admonition %}
      operationId: request_payment_data
      tags:
        - network_tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate token
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Gated
          position: after
          color: orange
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentDataRequest'
            examples:
              single:
                summary: Single Merchant
                value:
                  amount: 10000
                  currency_code: EUR
                  reference: '1234567890'
              platform:
                summary: Managed Eco-System
                value:
                  amount: 10000
                  currency_code: EUR
                  merchant_id: 00000000-0000-0000-0000-000000000000
                  reference: '1234567890'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentData'
              examples:
                single:
                  summary: Success Case (Single-Merchant & Eco-System)
                  value:
                    id: 00000000-0000-0000-0000-000000000000
                    amount: 10000
                    currency_code: EUR
                    created_at: '2023-10-01T00:00:00Z'
                    encrypted_authentication_data: eyJhbGc...
                    merchant_id: 00000000-0000-0000-0000-000000000000
                    reference: '1234567890'
                    success: true
                    token_id: 00000000-0000-0000-0000-000000000000
                platform:
                  summary: Success Case (Managed Eco-System)
                  value:
                    id: 00000000-0000-0000-0000-000000000000
                    amount: 10000
                    currency_code: EUR
                    created_at: '2023-10-01T00:00:00Z'
                    merchant_id: 00000000-0000-0000-0000-000000000000
                    reference: '1234567890'
                    success: true
                    token_id: 00000000-0000-0000-0000-000000000000
                failure:
                  summary: Failure Case
                  value:
                    id: 00000000-0000-0000-0000-000000000000
                    amount: 10000
                    currency_code: EUR
                    created_at: '2023-10-01T00:00:00Z'
                    failure_details:
                      - classifier: SOME_ERROR
                        scheme_code: Do not honor
                        message: Scheme rejected the request
                        source: scheme
                    merchant_id: 00000000-0000-0000-0000-000000000000
                    reference: '1234567890'
                    success: false
                    token_id: 00000000-0000-0000-0000-000000000000
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
        '422':
          $ref: '#/components/responses/422_ValidationError'
    get:
      summary: Get payment-data
      description: |
        List all payment-data bundles created for this Hellgate Token.
      operationId: list_payment_data
      tags:
        - network_tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the Hellgate token
          schema:
            type: string
            format: uuid
          required: true
        - in: query
          name: limit
          description: >-
            The desired amount of records per page. The parameter defaults to 50
            if it is omitted and has a maximum of 500.
          schema:
            type: integer
            minimum: 1
            maximum: 500
          required: false
        - in: query
          name: page
          description: The desired number of the page to return.
          schema:
            type: integer
            minimum: 1
          required: false
        - in: query
          name: sort
          description: >
            It allows sorting the result by created_at. e.g
            `sort=created_at+asc` or `sort=created_at+desc`
          schema:
            type: string
          required: false
      x-badges:
        - name: Gated
          position: after
          color: orange
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentDataList'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
  /payment-data/{id}/forward:
    post:
      summary: Forward payment-data
      description: >
        This endpoint enables platform merchants to leverage payment-data
        bundles in their acquirer integration.

        The request is forwarded to the configured destination URL of your
        merchant settings.


        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

        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/payment-data/d76074b3-53a8-4288-abcc-27c1281596d9/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_payment_data
      tags:
        - network_tokens
      security:
        - APIKeyAuth: []
      parameters:
        - in: path
          name: id
          description: The ID of the payment-data bundle
          schema:
            type: string
            format: uuid
          required: true
      x-badges:
        - name: Gated
          position: after
          color: orange
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: >
                The payload the caller wants to forward to the third party
                provider.


                To securely handle and inject sensitive token data, predefined
                templates can be 

                used. These templates help structure and standardize the data
                injection process while 

                ensuring compliance with security and regulatory requirements. 


                | Placeholder              |
                Description                                          |

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

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

                | `{{ cardholder_name }}`  | The name of the
                cardholder.                          |

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

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

                | `{{ cryptogram }}`       | The token authentication
                verification value TAVV.    |

                | `{{ eci }}`              | The ECI associated with the
                payment-data bundle.     |

                | `{{ amount }}`           | The authenticated amount given in
                minor units        |

                | `{{ currency_code }}`    | The currency code of the
                authenticated amount.       |


                All injected data will be represented as a string in the
                payload. If a specific data 

                type is required, such as a numeric representation of the
                expiration month, the data 

                can be unwrapped and converted back to its original type as
                needed: `{{ expiration_month | unwrap }}`.
            examples:
              adyen:
                summary: Forward payment-data to Adyen
                value:
                  reference: MAGIC DUST XYZ
                  amount:
                    value: '{{ amount }}'
                    currency: '{{ currency_code }}'
                  paymentMethod:
                    type: networkToken
                    expiryMonth: '{{ expiration_month }}'
                    expiryYear: '{{ expiration_year }}'
                    holderName: '{{ cardholder_name }}'
                    number: '{{ network_token }}'
                  mpiData:
                    tokenAuthenticationVerificatioNValue: '{{ cryptogram }}'
                    eci: '{{ eci }}'
                  recurringProcessingModel: CardOnFile
                  shopperInteraction: Ecommerce
          application/x-www-form-urlencoded:
            schema:
              type: object
              description: >
                The content-type can also be `x-www-form-urlencoded`.


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


                | Placeholder              |
                Description                                          |

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

                | `{{ network_token }}`    | The network token of this
                payment-data bundle.       |

                | `{{ cardholder_name }}`  | The name of the
                cardholder.                          |

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

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

                | `{{ cryptogram }}`       | The token authentication
                verification value TAVV.    |

                | `{{ eci }}`              | The ECI associated with the
                payment-data bundle.     |

                | `{{ amount }}`           | The authenticated amount given in
                minor units        |

                | `{{ currency_code }}`    | The currency code of the
                authenticated amount.       |
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                description: The response from the third party provider.
            application/x-www-form-urlencoded:
              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:
        - APIKeyAuth: []
      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:
        - 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:
        - 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
      description: Update the information of a merchant.
      operationId: update_merchant
      tags:
        - merchants
      security:
        - 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.

        {% admonition type="warning" name="Warning" %}
          This operation cannot be undone.
        {% /admonition %}
      operationId: remove_merchant
      tags:
        - merchants
      security:
        - 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'
  /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:
        - processor_backup
      security:
        - 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:
        - processor_backup
      security:
        - 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:
        - processor_backup
      security:
        - 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'
        '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:
        - processor_backup
      security:
        - 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'
  /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:
        - 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'
components:
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
  schemas:
    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: An EMVCo compatible address record
      properties:
        city:
          type: string
          minLength: 1
          maxLength: 50
        country:
          $ref: '#/components/schemas/ISO3166-3-CountryCode'
        line_1:
          type: string
          minLength: 1
          maxLength: 50
        line_2:
          type: string
          minLength: 1
          maxLength: 50
        line_3:
          type: string
          minLength: 1
          maxLength: 50
        postal_code:
          type: string
          minLength: 1
          maxLength: 16
        state:
          type: string
          minLength: 1
          maxLength: 3
    PhoneRecord:
      type: object
      properties:
        country_code:
          type: string
          minLength: 1
          maxLength: 3
        number:
          type: string
          minLength: 1
          maxLength: 15
    CardholderInformation:
      type: object
      properties:
        separate_shipping_address:
          type: boolean
          description: |
            If true the request also accepts the `shipping_address` object.
            If false it'll use the `billing_address` as `shipping_address`.
        billing_address:
          $ref: '#/components/schemas/EMVCoAddressRecord'
        email:
          type: string
          minLength: 1
          maxLength: 254
        home_phone:
          $ref: '#/components/schemas/PhoneRecord'
        mobile_phone:
          $ref: '#/components/schemas/PhoneRecord'
        shipping_address:
          $ref: '#/components/schemas/EMVCoAddressRecord'
        work_phone:
          $ref: '#/components/schemas/PhoneRecord'
    AdditionalInformation:
      type: object
      properties:
        account_information:
          type: object
          description: Information about the account provided by the merchant.
          properties:
            authentication:
              type: object
              properties:
                timestamp:
                  type: string
                  format: date-time
                  description: The date and time the consumer logged in
                auth_method:
                  type: string
                  enum:
                    - guest
                    - merchant_credentials
                    - sso
                    - issuer_credentials
                    - third_party
                    - fido
                reference:
                  type: string
            change_date:
              type: string
              description: The date the account was last changed
              format: date-time
            creation_date:
              type: string
              description: The date the account was opened by the consumer
              format: date-time
            number_of_purchases:
              type: integer
              description: Number of purchases in the last 6 months
            password_change_date:
              type: string
              description: >-
                The date the consumer's password on the merchant's side was last
                changed
              format: date-time
            payments:
              type: object
              properties:
                day_count:
                  type: integer
                  description: >-
                    Number of payments in the last 24 hours (including abandoned
                    transactions)
                year_count:
                  type: integer
                  description: >-
                    Number of payments in the previous year (including abandoned
                    transactions)
            suspicious_activity:
              type: boolean
              description: >-
                Indication that the merchant has expirienced suspicious activity
                on the customer account
        card_information:
          type: object
          properties:
            registration_date:
              type: string
              description: The date when the card was enrolled with the merchant
              format: date-time
            provision_attempts_last_twenty_four_hours:
              description: The number of the attempts to enroll a card in the last 24 hours
              type: integer
        cardholder_information:
          $ref: '#/components/schemas/CardholderInformation'
        purchase_information:
          type: object
          properties:
            delivery:
              type: object
              properties:
                e_mail:
                  type: string
                timeframe:
                  type: string
                  enum:
                    - electronic
                    - sameday
                    - nextday
                    - standard
            gift_card:
              type: object
              properties:
                amount:
                  type: number
                  description: Total purchase price of prepaid card or gift card
                count:
                  type: integer
                  description: Total number of prepaid or gift cards purchased
                currency:
                  type: string
                  description: The ISO-4217 currency code
            pre_order:
              type: object
              properties:
                pre_order_date:
                  type: string
                  description: Expected product release date
                  format: date-time
                reorder:
                  type: boolean
                delivery_method:
                  type: string
                  enum:
                    - billing_address
                    - confirmed_address
                    - other_address
                    - store_or_pickup
                    - digital
                    - none
                    - other
    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)
    PaymentReference:
      type: string
      maxLength: 80
      description: A description of the payment for later reference
    RequestSourceCheckout:
      type: object
      properties:
        type:
          type: string
        store_credentials:
          type: boolean
          default: false
      required:
        - type
    RequestSourceToken:
      type: object
      properties:
        type:
          type: string
        store_credentials:
          type: boolean
          default: false
        token_id:
          type: string
          format: uuid
      required:
        - type
        - token_id
    RequestSourceCredential:
      type: object
      properties:
        type:
          type: string
        credential_id:
          type: string
          format: uuid
      required:
        - type
        - credential_id
    PaymentRequestSource:
      description: >
        The source for this payment request.


        {% table %}


        - Type

        - Description


        ---


        - checkout

        - During the checkout an action requirement will be available, to
        determine the actual payment credentials from the shopper.
          The SDKs can be used to handle the session and safely process the payment data.

        ---


        - token

        - An already existing Hellgate token can be used as source for the
        payment.


        ---


        - credential

        - Already stored credentials are used as source for the payment.


        {% /table %}
      discriminator:
        propertyName: type
        mapping:
          checkout: '#/components/schemas/RequestSourceCheckout'
          token: '#/components/schemas/RequestSourceToken'
          credential: '#/components/schemas/RequestSourceCredential'
      default: checkout
      oneOf:
        - $ref: '#/components/schemas/RequestSourceToken'
        - $ref: '#/components/schemas/RequestSourceCheckout'
        - $ref: '#/components/schemas/RequestSourceCredential'
    PaymentSplitSeller:
      type: object
      properties:
        type:
          type: string
        merchant_id:
          type: string
          format: uuid
        amount:
          type: integer
          description: |
            The amount to be sent to the respective merchant account.
            It considers the payment's currency selection.
        reference:
          type: string
          description: A reference for the seller split.
      required:
        - type
        - merchant_id
        - amount
        - reference
    PaymentSplitCommission:
      type: object
      properties:
        type:
          type: string
        amount:
          type: integer
          description: >
            The amount to be sent to the platform account in terms of a
            commission.

            It considers the payment's currency selection.
        reference:
          type: string
          description: A reference for the commission split.
      required:
        - type
        - amount
        - reference
    PaymentSplitsRequest:
      description: >
        An optional array of split instructions.


        Data in this array is only processed on a Hellgate account 

        in the platform operating model. If you are in doubt, please reach out
        to your account representative.


        In order to have a valid split instruction, the total amount of the
        payment needs to be the sum of all splits.


        {% table %}


        - Type

        - Description


        ---


        - seller

        - Sending the given amount to the seller referenced by the `merchant_id`
        in the payload.
          The seller needs to be onboarded to the account and linked to the processor in order to
          receive funds from a payment split.

        ---


        - commission

        - An already existing Hellgate token can be used as source for the
        payment.


        {% /table %}
      type: array
      minItems: 1
      items:
        type: object
        discriminator:
          propertyName: type
          mapping:
            seller: '#/components/schemas/PaymentSplitSeller'
            commission: '#/components/schemas/PaymentSplitCommission'
        oneOf:
          - $ref: '#/components/schemas/PaymentSplitSeller'
          - $ref: '#/components/schemas/PaymentSplitCommission'
    PaymentRequestOneTime:
      type: object
      properties:
        additional_information:
          $ref: '#/components/schemas/AdditionalInformation'
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        reference:
          $ref: '#/components/schemas/PaymentReference'
        source:
          $ref: '#/components/schemas/PaymentRequestSource'
        splits:
          $ref: '#/components/schemas/PaymentSplitsRequest'
      required:
        - amount
        - currency_code
        - reference
    ActionRequirement:
      type: object
      properties:
        type:
          type: string
          enum:
            - use_sdk
        session_id:
          type: string
          format: uuid
          description: The id of the session to use for the SDK
      required:
        - type
        - session_id
    AuthenticationPreference:
      type: string
      description: >
        The preference for the authentication method to be used for the payment.


        {% table %}


        - Preference {% width="30%" %}

        - Description


        ---


        - NO_3RI

        - Don't perform 3RI authentication for this payment (Default).


        ---


        - TRY_3RI

        - Try to perform 3RI authentication for this payment. If it fails the
        payment will still be sent for authorization.


        ---


        - REQUIRE_3RI

        - Require 3RI authentication for this payment. If it fails the payment
        will not be sent for authorization.


        {% /table %}
      default: NO_3RI
      enum:
        - NO_3RI
        - TRY_3RI
        - REQUIRE_3RI
    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.
    AuthenticationResult:
      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'
    CountryCode_3166_2:
      type: string
      description: The ISO 3166 two letter country code
    PaymentSourceCard:
      type: object
      properties:
        type:
          type: string
          description: The type of payment-method that was used as source
        cardholder_name:
          type: string
        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)
        issuer:
          type: object
          properties:
            account:
              type: object
              properties:
                funding:
                  type: string
                  enum:
                    - credit
                    - debit
                    - prepaid
                    - charge
                    - deferred debit
                country_code:
                  $ref: '#/components/schemas/CountryCode_3166_2'
                currency:
                  $ref: '#/components/schemas/CurrencyCode'
            identification_number:
              type: string
              description: The issuer idenfication number (IIN) - also know as BIN
            name:
              type: string
              description: The name of the bank
            scheme:
              type: string
              description: The scheme in which the card was issued
            segment:
              type: string
              enum:
                - consumer
                - business
                - commercial
                - other
        masked_account_number:
          type: string
          description: >-
            The full lenght of the card number, but masked to conform to PCI/DSS
            requirments
        pan_type:
          type: string
          description: >
            The type of primary account number (PAN) which used for this the
            payment. 


            `DPAN` indicates a network token was used and `FPAN` indicates the
            full card was used.
          enum:
            - FPAN
            - DPAN
      required:
        - type
        - cardholder_name
        - expiry_month
        - expiry_year
        - masked_account_number
        - pan_type
    PaymentSource:
      description: |-
        The source that was used for the payment.

        | Type       | Description                                  |
        |------------|----------------------------------------------|
        | `card`     | The payment method `card` was used as source |
      discriminator:
        propertyName: type
        mapping:
          card: '#/components/schemas/PaymentSourceCard'
      oneOf:
        - $ref: '#/components/schemas/PaymentSourceCard'
    PaymentSplitsResponse:
      description: >
        An array of split instructions.


        Data in this array is only processed on a Hellgate account 

        in the platform operating model. If you are in doubt, please reach out
        to your account representative.


        {% table %}


        - Type

        - Description


        ---


        - seller

        - Sending the given amount to the seller referenced by the `merchant_id`
        in the payload.
          The seller needs to be onboarded to the account and linked to the processor in order to
          receive funds from a payment split.

        ---


        - commission

        - An already existing Hellgate token can be used as source for the
        payment.


        {% /table %}
      type: array
      minItems: 1
      items:
        type: object
        discriminator:
          propertyName: type
          mapping:
            seller: '#/components/schemas/PaymentSplitSeller'
            commission: '#/components/schemas/PaymentSplitCommission'
        oneOf:
          - $ref: '#/components/schemas/PaymentSplitSeller'
          - $ref: '#/components/schemas/PaymentSplitCommission'
    PaymentStatus:
      type: string
      enum:
        - open
        - processing
        - failed
        - authorized
        - capturing
        - captured
        - settling
        - settled
        - voiding
        - voided
    UseCase:
      type: string
      description: Definition of the payment use-case for processing
      enum:
        - ONE_OFF
        - UNSCHEDULED
        - SUBSEQUENT_UNSCHEDULED
        - RECURRING
        - SUBSEQUENT_RECURRING
    PaymentResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the payment on Hellgate
        action_requirement:
          $ref: '#/components/schemas/ActionRequirement'
        additional_information:
          $ref: '#/components/schemas/AdditionalInformation'
        authentication_preference:
          $ref: '#/components/schemas/AuthenticationPreference'
        authentication_result:
          $ref: '#/components/schemas/AuthenticationResult'
        amount:
          type: object
          properties:
            requested:
              $ref: '#/components/schemas/Amount'
            authorized:
              $ref: '#/components/schemas/Amount'
            captured:
              $ref: '#/components/schemas/Amount'
            voided:
              $ref: '#/components/schemas/Amount'
            refunded:
              $ref: '#/components/schemas/Amount'
        created_at:
          type: string
          description: The date-time the payment was created (following ISO 8601)
          format: date-time
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        credential_id:
          type: string
          format: uuid
          description: The ID of the credential associated with the payment.
        failure_details:
          type: array
          description: >
            The reasons why a payment failed during processing in Hellgate. 


            This can be due to processing errors on the side of the processor, 

            as well as errors in the processing of the underlying flow.


            In case the failure is due to a processing problem, the transaction

            history of the payment can give more information on the exact
            failure details.
          items:
            type: object
            properties:
              classifier:
                type: string
              message:
                type: string
              source:
                type: string
                enum:
                  - processor
                  - integration
                  - protocol
        flow_matrix_rule:
          type: string
          description: >
            The rule in the flow matrix, which was chosen to process the
            payment.
        initial_payment_id:
          type: string
          format: uuid
          description: |
            The ID of the initial payment.

            Only present for subsequent merchant-initiated payments.
        processing_annotations:
          type: object
          description: >
            This is an optional attribute holding results from eventual
            pre-processing of the request.
        reference:
          $ref: '#/components/schemas/PaymentReference'
        recurring_expiry:
          type: string
          format: yyyyMMdd
          description: |
            The date when the recurring should expiry.

            Only present for recurring payments.
        recurring_frequency:
          type: integer
          description: |
            Indicates the minimum number of days between authorisations.

            Only present for recurring payments.
        source:
          $ref: '#/components/schemas/PaymentSource'
        splits:
          $ref: '#/components/schemas/PaymentSplitsResponse'
        status:
          $ref: '#/components/schemas/PaymentStatus'
        use_case:
          $ref: '#/components/schemas/UseCase'
      required:
        - id
        - amount
        - created_at
        - currency_code
        - reference
        - status
        - use_case
    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'
    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
    InitialRequestSourceCheckout:
      type: object
      properties:
        type:
          type: string
      required:
        - type
    InitialRequestSourceToken:
      type: object
      properties:
        type:
          type: string
        token_id:
          type: string
          format: uuid
      required:
        - type
        - token_id
    InitialPaymentRequestSource:
      description: >
        The source for this initial payment.


        {% table %}


        - Type

        - Description


        ---


        - checkout

        - During the checkout an action requirement will be available, to
        determine the actual payment credentials from the shopper.
          The SDKs can be used to handle the session and safely process the payment data.

        ---


        - token

        - An already existing Hellgate token can be used as source for the
        payment.


        ---


        - credential

        - Already stored credentials are used as source for the payment.


        {% /table %}
      discriminator:
        propertyName: type
        mapping:
          checkout: '#/components/schemas/InitialRequestSourceCheckout'
          token: '#/components/schemas/InitialRequestSourceToken'
          credential: '#/components/schemas/RequestSourceCredential'
      default: checkout
      oneOf:
        - $ref: '#/components/schemas/InitialRequestSourceToken'
        - $ref: '#/components/schemas/InitialRequestSourceCheckout'
        - $ref: '#/components/schemas/RequestSourceCredential'
    PaymentRequestUnscheduled:
      type: object
      properties:
        additional_information:
          $ref: '#/components/schemas/AdditionalInformation'
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        reference:
          $ref: '#/components/schemas/PaymentReference'
        source:
          $ref: '#/components/schemas/InitialPaymentRequestSource'
        splits:
          $ref: '#/components/schemas/PaymentSplitsRequest'
      required:
        - amount
        - currency_code
        - reference
    PaymentRequestRecurring:
      type: object
      properties:
        additional_information:
          $ref: '#/components/schemas/AdditionalInformation'
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        reference:
          $ref: '#/components/schemas/PaymentReference'
        recurring_expiry:
          type: string
          format: yyyyMMdd
          description: |
            The date when the recurring should expiry.
        recurring_frequency:
          type: integer
          description: Indicates the minimum number of days between authorisations.
        source:
          $ref: '#/components/schemas/InitialPaymentRequestSource'
        splits:
          $ref: '#/components/schemas/PaymentSplitsRequest'
      required:
        - amount
        - currency_code
        - reference
        - recurring_expiry
        - recurring_frequency
    PaymentRequestSubsequent:
      type: object
      properties:
        additional_information:
          $ref: '#/components/schemas/AdditionalInformation'
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        authentication_preference:
          $ref: '#/components/schemas/AuthenticationPreference'
        reference:
          $ref: '#/components/schemas/PaymentReference'
      required:
        - amount
        - currency_code
        - reference
    CaptureCreate:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        reference:
          type: string
          maxLength: 80
          description: A description of the capture for later reference
        splits:
          $ref: '#/components/schemas/PaymentSplitsRequest'
      required:
        - reference
    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
    PaymentResponseList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
    TransactionStatus:
      type: string
      enum:
        - pending
        - succeeded
        - failed
    Transaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the Transaction on Hellgate
        failure_details:
          type: array
          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:
                  - processor
                  - integration
            required:
              - classifier
              - source
        finished_at:
          type: string
          format: date-time
          description: The date-time the transaction was finished (following ISO 8601)
        processor:
          type: object
          properties:
            name:
              type: string
              description: Name of the processor of payment transaction
            transaction_id:
              type: string
              description: The transaction ID on the processor side
            merchant_id:
              type: string
              description: The identification of the merchant being used with the processor
            network_transaction_reference:
              type: string
              description: The network transaction reference
        started_at:
          type: string
          format: date-time
          description: The date-time the transaction was started (following ISO 8601)
        status:
          $ref: '#/components/schemas/TransactionStatus'
        type:
          type: string
          enum:
            - authorize
            - capture
            - cancel
            - refund
    TransactionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        pagination:
          $ref: '#/components/schemas/Pagination'
    RefundResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        created_at:
          type: string
          description: The date-time the refund was created (following ISO 8601)
          format: date-time
        failure_details:
          type: array
          description: >
            The reasons why a refund failed during processing in Hellgate. 


            This can be due to processing errors on the side of the processor, 

            as well as errors in the processing of the underlying flow.


            In case the failure is due to a processing problem, the transaction

            history of the payment can give more information on the exact
            failure details.
          items:
            type: object
            properties:
              classifier:
                type: string
              message:
                type: string
              source:
                type: string
                enum:
                  - processor
                  - integration
                  - protocol
        payment_id:
          type: string
          format: uuid
        reference:
          type: string
          maxLength: 80
          description: A description of the refund for later reference
        splits:
          $ref: '#/components/schemas/PaymentSplitsResponse'
        status:
          type: string
          enum:
            - processing
            - completed
            - failed
      required:
        - id
        - amount
        - currency_code
        - reference
        - payment_id
        - status
    RefundList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RefundResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
    RefundCreate:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        reference:
          type: string
          maxLength: 80
          description: A description of the refund for later reference
        splits:
          $ref: '#/components/schemas/PaymentSplitsRequest'
      required:
        - reference
    RequestSourceToken-2:
      type: object
      properties:
        type:
          type: string
        token_id:
          type: string
          format: uuid
      required:
        - type
        - token_id
    AuthenticationRequestSource:
      description: >
        The payment credentials for this authentication request.


        {% table %}


        - Type

        - Description


        ---


        - token

        - An already existing Hellgate token can be used as source for the
        authentication.


        {% /table %}
      discriminator:
        propertyName: type
        mapping:
          token: '#/components/schemas/RequestSourceToken-2'
      default: token
      oneOf:
        - $ref: '#/components/schemas/RequestSourceToken-2'
    OneOffRequest:
      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.
        source:
          $ref: '#/components/schemas/AuthenticationRequestSource'
        merchant_id:
          type: string
          description: The ID of the merchant for whom the authentication is requested
          format: uuid
      required:
        - amount
        - currency_code
        - source
    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:
          $ref: '#/components/schemas/AuthenticationResult'
        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
        source:
          $ref: '#/components/schemas/AuthenticationRequestSource'
        use_case:
          type: string
          enum:
            - ONE_OFF
            - INITIAL_RECURRING
            - INITIAL_INSTALLMENT
            - SUBSEQUENT_RECURRING
            - SUBSEQUENT_INSTALLMENT
      required:
        - amount
        - created_at
        - currency_code
        - id
        - status
        - source
        - use_case
    RecurringRequest:
      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
          format: yyyyMMdd
          description: |
            The date when the recurring should expiry.
        recurring_frequency:
          type: integer
          description: Indicates the minimum number of days between authorisations.
        source:
          $ref: '#/components/schemas/AuthenticationRequestSource'
        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
        - source
        - recurring_expiry
        - recurring_frequency
    SubsequentRequest:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
      required:
        - amount
        - currency_code
    InstallmentRequest:
      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.
        source:
          $ref: '#/components/schemas/AuthenticationRequestSource'
        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
        - source
        - recurring_expiry
        - recurring_frequency
    AuthenticationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Authentication'
        pagination:
          $ref: '#/components/schemas/Pagination'
    CredentialCard:
      type: object
      properties:
        type:
          type: string
          description: The type of the credential
        id:
          type: string
          description: The ID of the credential on file
          format: uuid
        created_at:
          type: string
          description: The date-time the credential was created (following ISO 8601)
          format: date-time
        cardholder_name:
          type: string
          description: The name of the owner of the card
        expiry_month:
          type: integer
          description: The number of month in a year (e.g. April is 4)
        expiry_year:
          type: integer
          description: The year given as four digit number (e.g. 2023)
        issuer:
          type: object
          properties:
            account:
              type: object
              properties:
                funding:
                  type: string
                  enum:
                    - credit
                    - debit
                    - prepaid
                    - charge
                    - deferred debit
                country_code:
                  $ref: '#/components/schemas/CountryCode_3166_2'
                currency:
                  $ref: '#/components/schemas/CurrencyCode'
            identification_number:
              type: string
              description: The issuer idenfication number (IIN) - also know as BIN
            name:
              type: string
              description: The name of the bank
            scheme:
              type: string
              description: The scheme in which the card was issued
            segment:
              type: string
              enum:
                - consumer
                - business
                - commercial
                - other
        masked_account_number:
          type: string
          description: >-
            The full lenght of the card number, but masked to conform to PCI/DSS
            requirments
      required:
        - id
        - type
        - created_at
        - cardholder_name
        - expiry_month
        - expiry_year
        - masked_account_number
    Credential:
      description: The underlying payment-method type of this stored credential.
      discriminator:
        propertyName: type
        mapping:
          card: '#/components/schemas/CredentialCard'
      oneOf:
        - $ref: '#/components/schemas/CredentialCard'
    CredentialList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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
    TokenSession:
      type: object
      properties:
        session_id:
          description: |
            The ID of the session which needs to be used to initialize the SDK.
          type: string
          format: uuid
      required:
        - session_id
    CardholderData:
      type: object
      properties:
        cardholder_name:
          type: string
          description: |
            The name of the owner of the card

            {% admonition type="info" name="Information" %}
              Hellgate only soft-deletes data. So in case of deletion this value will be anonymized.
            {% /admonition %}
        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
    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
    PaymentData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The id of the requested payment data
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        created_at:
          type: string
          format: date-time
          description: The date-time the payment-data was created (following ISO 8601)
        encrypted_authentication_data:
          $ref: '#/components/schemas/EncryptedAuthenticationData'
        failure_details:
          type: array
          description: >
            The reasons why the processing failed. 

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

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

            If true, the processing was successfully completed. In case it is
            false,  the processing failed and the `failure_details` field
            contains more information about the failure.
        token_id:
          type: string
          format: uuid
          description: The ID of the token on Hellgate
      required:
        - id
        - amount
        - currency_code
        - merchant_id
        - reference
        - success
        - token_id
    PaymentDataList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PaymentData'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PaymentDataRequest:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Amount'
        currency_code:
          $ref: '#/components/schemas/CurrencyCode'
        merchant_id:
          type: string
          description: >
            The ID of the merchant for whom the authentication is requested.


            Only required when the account operates an ecoystem or platform. 

            The value will default to the primary merchant of an account in
            other cases.
          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'
    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: 9071cd4e-9627-421b-96cc-d48ffda5e894
        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
    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'
  responses:
    401_UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 401
            message: No valid means of authentication was provided
            classifier: UNAUTHORIZED
    403_ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 403
            message: Not allowed to access this resource or feature
            classifier: FORBIDDEN
    409_ConflictError:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 409
            message: Conflict
            classifier: CONFLICT
    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
    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
    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:
    Payment_Notification:
      '{notification_endpoint}':
        post:
          summary: Payment Notification callback
          description: >
            The notification callback is used to inform a listener about changes
            to a payment. 


            The listener must respond with an HTTP status code 200 to
            acknowledge and accept the callback. 

            If a different status code is returned, Hellgate will attempt to
            resend the notification, 

            following a retry policy until the notification is successfully
            acknowledged or the maximum 

            retry limit is reached.
          security: []
          parameters:
            - in: path
              name: notification_endpoint
              schema:
                type: string
              description: The endpoint of the callback listner.
              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: The ID of the payment which triggered the notification.
                    created_at:
                      type: string
                      format: date-time
                      description: >-
                        The date-time the event was occurred (following ISO
                        8601)
                    event_type:
                      type: string
                      enum:
                        - payment.processing
                        - payment.authorized
                        - payment.captured
                        - payment.settled
                        - payment.failed
                        - payment.voided
                        - payment.refunded
                    payment:
                      oneOf:
                        - $ref: '#/components/schemas/PaymentResponse'
                examples:
                  processing:
                    summary: payment.processing
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: payment.processing
                      payment:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount:
                          requested: 1000
                        created_at: '2023-10-10T00:00:00Z'
                        currency_code: EUR
                        flow_matrix_rule: e-commerce flow
                        reference: 'Order #12345'
                        status: processing
                        source:
                          type: card
                          cardholder_name: Bob Holder
                          expiry_month: 12
                          expiry_year: 2030
                          masked_account_number: 424242XXXXXX4242
                          pan_type: FPAN
                        use_case: ONE_OFF
                  authorized:
                    summary: payment.authorized
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: payment.authorized
                      payment:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount:
                          requested: 1000
                          authorized: 1000
                        created_at: '2023-10-10T00:00:00Z'
                        currency_code: EUR
                        flow_matrix_rule: e-commerce flow
                        reference: 'Order #12345'
                        status: authorized
                        source:
                          type: card
                          cardholder_name: Bob Holder
                          expiry_month: 12
                          expiry_year: 2030
                          masked_account_number: 424242XXXXXX4242
                          pan_type: FPAN
                        use_case: ONE_OFF
                  captured:
                    summary: payment.captured
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: payment.captured
                      payment:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount:
                          requested: 1000
                          authorized: 1000
                          captured: 1000
                        created_at: '2023-10-10T00:00:00Z'
                        currency_code: EUR
                        flow_matrix_rule: e-commerce flow
                        reference: 'Order #12345'
                        status: captured
                        source:
                          type: card
                          cardholder_name: Bob Holder
                          expiry_month: 12
                          expiry_year: 2030
                          masked_account_number: 424242XXXXXX4242
                          pan_type: FPAN
                        use_case: ONE_OFF
                  settled:
                    summary: payment.settled
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: payment.settled
                      payment:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount:
                          requested: 1000
                          authorized: 1000
                          captured: 1000
                        created_at: '2023-10-10T00:00:00Z'
                        currency_code: EUR
                        flow_matrix_rule: e-commerce flow
                        reference: 'Order #12345'
                        status: settled
                        source:
                          type: card
                          cardholder_name: Bob Holder
                          expiry_month: 12
                          expiry_year: 2030
                          masked_account_number: 424242XXXXXX4242
                          pan_type: FPAN
                        use_case: ONE_OFF
                  voided:
                    summary: payment.voided
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: payment.voided
                      payment:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount:
                          requested: 1000
                          authorized: 1000
                          voided: 1000
                        created_at: '2023-10-10T00:00:00Z'
                        currency_code: EUR
                        flow_matrix_rule: e-commerce flow
                        reference: 'Order #12345'
                        status: voided
                        source:
                          type: card
                          cardholder_name: Bob Holder
                          expiry_month: 12
                          expiry_year: 2030
                          masked_account_number: 424242XXXXXX4242
                          pan_type: FPAN
                        use_case: ONE_OFF
                  failed:
                    summary: payment.failed
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: payment.failed
                      payment:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount:
                          requested: 1000
                        created_at: '2023-10-10T00:00:00Z'
                        currency_code: EUR
                        failure_details:
                          - classifier: TRANSACTION_ERROR
                            message: 'Transaction failed: Do not honor.'
                            source: processor
                          - classifier: PAYMENT_FAILURE
                            message: 'Payment failed: Transaction not successful.'
                            source: protocol
                        flow_matrix_rule: e-commerce flow
                        reference: 'Order #12345'
                        status: failed
                        source:
                          type: card
                          cardholder_name: Bob Holder
                          expiry_month: 12
                          expiry_year: 2030
                          masked_account_number: 424242XXXXXX4242
                          pan_type: FPAN
                        use_case: ONE_OFF
                  refunded:
                    summary: payment.refunded
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: payment.refunded
                      payment:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount:
                          requested: 1000
                          authorized: 1000
                          captured: 1000
                          refunded: 500
                        created_at: '2023-10-10T00:00:00Z'
                        currency_code: EUR
                        flow_matrix_rule: e-commerce flow
                        reference: 'Order #12345'
                        status: captured
                        source:
                          type: card
                          cardholder_name: Bob Holder
                          expiry_month: 12
                          expiry_year: 2030
                          masked_account_number: 424242XXXXXX4242
                          pan_type: FPAN
                        use_case: ONE_OFF
          responses:
            '200':
              description: >
                Confirmation of receipt. For other status codes, Hellgate will
                try to redeliver.
            '400':
              description: Bad request
    Refund_Notification:
      '{notification_endpoint}':
        post:
          summary: Refund Notification callback
          description: >
            The notification callback is used to inform a listener about changes
            to a refund. 


            The listener must respond with an HTTP status code 200 to
            acknowledge and accept the callback. 

            If a different status code is returned, Hellgate will attempt to
            resend the notification, 

            following a retry policy until the notification is successfully
            acknowledged or the maximum 

            retry limit is reached.
          security: []
          parameters:
            - in: path
              name: notification_endpoint
              schema:
                type: string
              description: The endpoint of the callback listner.
              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: The ID of the payment which triggered the notification.
                    created_at:
                      type: string
                      format: date-time
                      description: >-
                        The date-time the event was occurred (following ISO
                        8601)
                    event_type:
                      type: string
                      enum:
                        - refund.processing
                        - refund.completed
                        - refund.failed
                    refund:
                      oneOf:
                        - $ref: '#/components/schemas/RefundResponse'
                examples:
                  processing:
                    summary: refund.processing
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: refund.processing
                      refund:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount: 1000
                        currency_code: EUR
                        created_at: '2023-10-10T00:00:00Z'
                        payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                        reference: 'Refund order #12345'
                        status: processing
                  completed:
                    summary: refund.completed
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: refund.completed
                      refund:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount: 1000
                        currency_code: EUR
                        created_at: '2023-10-10T00:00:00Z'
                        payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                        reference: 'Refund order #12345'
                        status: completed
                  failed:
                    summary: refund.failed
                    value:
                      id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                      created_at: '2023-10-10T00:00:00Z'
                      event_type: refund.failed
                      refund:
                        id: 54ba1fdb-7e4e-402b-aebb-66f9d5345cf8
                        amount: 1000
                        currency_code: EUR
                        created_at: '2023-10-10T00:00:00Z'
                        failure_details:
                          - classifier: TRANSACTION_ERROR
                            message: 'Transaction failed: No refund possible.'
                            source: processor
                          - classifier: PAYMENT_FAILURE
                            message: 'Refund failed: Transaction not successful.'
                            source: protocol
                        payment_id: cdc60e91-1d1a-4641-8ada-84bdbbe189f5
                        reference: 'Refund order #12345'
                        status: failed
          responses:
            '200':
              description: >
                Confirmation of receipt. For other status codes, Hellgate will
                try to redeliver.
            '400':
              description: Bad request
    Token_Notification:
      '{notification_endpoint}':
        post:
          summary: Token Master Notification
          description: >-
            This endpoint is used to notify the integration server about changes
            in the token state.
          security: []
          parameters:
            - in: path
              name: notification_endpoint
              schema:
                type: string
              description: >-
                The endpoint of the notification callback. The endpoint is
                provided by the integration server during the account creation.
              required: true
            - in: header
              name: x-hmac-signature
              schema:
                type: string
              description: >-
                The signature of request body calculated based on the secret
                HMAC key of the account
          requestBody:
            content:
              application/json:
                schema:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: >-
                        A unique ID of the event which caused the notifcation
                        callback
                    created_at:
                      type: string
                      format: date-time
                      description: >-
                        The date-time the event was occurred (following ISO
                        8601)
                    event_type:
                      type: string
                      enum:
                        - token.created
                        - token.updated
                        - token.deleted
                    token:
                      $ref: '#/components/schemas/HellgateToken'
                  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.
            '400':
              description: Bad request
  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
