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

# Forward payment-data

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

Commerce requires certain HTTP headers for this feature. These headers
are reserved and cannot be used by the caller:

| Header | Required? | Description |
| ------ | --------- | ----------- |
| `x-api-key` | Yes | Authentication of the request. |
| `x-hellgate-version` | No | Define the API version to use for the request. |

Refer to the general documentation about [forwarding senstive data](/products/commerce/v2/guides/forwarding) 
for more information.


<Badge stroke icon="house-lock" color="orange">Gated Feature</Badge>


## OpenAPI

````yaml /products/commerce/v2/openapi.yaml post /payment-data/{id}/forward
openapi: 3.1.0
info:
  title: Commerce API
  version: '2.0'
  description: >
    The Commerce V2 API provides a comprehensive payment orchestration platform
    designed to streamline and optimize payment processing for modern
    businesses. 

    Built with flexibility and security at its core, our API enables you to
    process payments, manage authentications, and handle cardholder data across
    multiple payment processors without vendor lock-in.
  contact:
    name: Starfish GmbH & Co. KG
    email: hello@starfish.team
    url: https://hellgate.io/cpa/commerce
  license:
    name: Commerce API Terms
    url: https://hellgate.io/terms-and-conditions
servers:
  - url: https://sandbox.hellgate.io
    description: Commerce SaaS Sandbox
  - url: https://api.hellgate.io
    description: Commerce SaaS Production
security: []
tags:
  - name: payments_ci
    description: >-
      Handle payment processing where the customer is actively present and
      authorizing the transaction.
  - name: payments_mi
    description: >-
      Process transactions without direct customer interaction at the time of
      payment.
  - name: payments_modifications
    description: >-
      Modify existing payment transactions after initial authorization (capture,
      void, refund).
  - name: payments_data
    description: >-
      Access comprehensive payment transaction data for reporting,
      reconciliation, and analysis.
  - name: refunds_data
    description: Access detailed refund transaction data for tracking and reconciliation.
  - name: authentications_ci
    description: >-
      Process EMVCo 3-D Secure authentication requests as standalone
      transactions (one-off, recurring, installment).
  - name: authentications_mi
    description: >-
      Process requestor-initiated EMVCo 3-D Secure authentication requests (3RI)
      as standalone transactions.
  - name: authentications_data
    description: Access the results of prior authentications for reference.
  - name: credentials_management
    description: >-
      Manage stored payment credentials for repeat customers across all
      operating models.
  - name: tokens_create
    description: >-
      Create and import Commerce tokens to securely store cardholder data while
      maintaining PCI DSS compliance.
  - name: tokens_management
    description: Manage stored Commerce tokens including CVC2 security code management.
  - name: compliance_service
    description: >-
      Safely handle sensitive cardholder data while maintaining PCI DSS
      compliance via a secure proxy service.
  - name: network_tokens
    description: >-
      Manage network tokens with major card schemes with automatic lifecycle
      management.
  - name: merchants
    description: >-
      Configure and manage merchant accounts based on your chosen operating
      model.
  - name: reconciliation
    description: Reconcile imported token data.
  - name: processor_backup
    description: >-
      Migrate payment tokens from third-party processors (currently supports
      stripe.com).
paths:
  /payment-data/{id}/forward:
    post:
      tags:
        - network_tokens
      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.


        Commerce requires certain HTTP headers for this feature. These headers

        are reserved and cannot be used by the caller:


        | Header | Required? | Description |

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

        | `x-api-key` | Yes | Authentication of the request. |

        | `x-hellgate-version` | No | Define the API version to use for the
        request. |


        Refer to the general documentation about [forwarding senstive
        data](/products/commerce/v2/guides/forwarding) 

        for more information.
      operationId: forward_payment_data
      parameters:
        - in: path
          name: id
          description: The ID of the payment-data bundle
          schema:
            type: string
            format: uuid
          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 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              | Type     |
                Description                                          |

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

                | `{{ network_token }}`    | `string` | The Token-Pan (TPAN) of
                the network token.           |

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

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

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

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

                | `{{ dynamic_cvv }}`      | `string` | The dynamic CVV, when
                present instead of a TAVV.     |

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

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

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


                Placeholder of type `number` can be unwrapped from the standard
                string representation.
            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              | Type     |
                Description                                          |

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

                | `{{ network_token }}`    | `string` | The Token-Pan (TPAN) of
                the network token.           |

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

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

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

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

                | `{{ dynamic_cvv }}`      | `string` | The dynamic CVV, when
                present instead of a TAVV.     |

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

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

                | `{{ currency_code }}`    | `string` | 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'
      security:
        - APIKeyAuth: []
components:
  responses:
    400_BadRequestError:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 400
            message: The request could not be handle due to invalid data
            classifier: BAD_REQUEST
    401_UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 401
            message: No valid means of authentication was provided
            classifier: UNAUTHORIZED
    403_ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorGeneric'
          example:
            code: 403
            message: Not allowed to access this resource or feature
            classifier: FORBIDDEN
    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
  schemas:
    ErrorGeneric:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorStatusCode'
        classifier:
          $ref: '#/components/schemas/ErrorClassifier'
        message:
          $ref: '#/components/schemas/ErrorMessage'
    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
  securitySchemes:
    APIKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header

````