> ## 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 cryptogram

> Forward a request to a certified third-party provider with cryptogram data injected server-side, so it never touches your systems. This lets SAQ-A merchants use network tokens without ever handling a raw cryptogram, and mirrors [Forward card data](/products/guardian/api-reference/pci/forward-card-data).

- Resolves the single-use `x-cryptogram-reference` returned by [Request cryptogram](/products/guardian/api-reference/network/request-cryptogram) in `reference` mode.
- Injects the cryptogram and other PCI-scoped fields (token PAN, expiry, ECI, and more) into your request body via placeholders.
- Forwards the result to the `x-destination-url`.

See [Network Tokens](/products/guardian/tokens/network-tokens#forwarding-cryptograms) for the full placeholder list.




## OpenAPI

````yaml /products/guardian/openapi.yaml post /api/network/tokens/{id}/forward
openapi: 3.1.0
info:
  title: Guardian API
  version: '1.0'
  contact:
    name: Starfish GmbH & Co. KG
    email: support@hellgate.io
    url: https://hellgate.io/cpa/guardian
  license:
    name: Hellgate API Terms
    url: https://hellgate.io/terms-and-conditions
servers:
  - url: https://{instance}.{env}.on-hellgate.cloud
    description: Managed instance of Guardian
    variables:
      instance:
        default: my-instance
        description: Your unique instance slug, provided during onboarding.
      env:
        default: eu1
        description: Deployment environment (currently eu1).
security: []
tags:
  - name: pci
    description: Management of card payment credentials under the ruling of PCI DSS.
  - name: network
    description: Management of network tokens and cryptograms for secure transactions.
  - name: generic
    description: Management of generic tokens and their schemas for various use cases.
  - name: metadata
    description: Inquiries for card metadata based on PAN, PCI tokens, or network tokens.
  - name: wallet
    description: >-
      Management of wallet tokens ingested from device wallets such as Google
      Pay.
  - name: apikey
    description: Management of API keys for service access.
  - name: webhook
    description: Management of webhooks for event notifications.
  - name: types
    description: Management of types for generic token schemas.
paths:
  /api/network/tokens/{id}/forward:
    post:
      tags:
        - network
      summary: Forward cryptogram
      description: >
        Forward a request to a certified third-party provider with cryptogram
        data injected server-side, so it never touches your systems. This lets
        SAQ-A merchants use network tokens without ever handling a raw
        cryptogram, and mirrors [Forward card
        data](/products/guardian/api-reference/pci/forward-card-data).


        - Resolves the single-use `x-cryptogram-reference` returned by [Request
        cryptogram](/products/guardian/api-reference/network/request-cryptogram)
        in `reference` mode.

        - Injects the cryptogram and other PCI-scoped fields (token PAN, expiry,
        ECI, and more) into your request body via placeholders.

        - Forwards the result to the `x-destination-url`.


        See [Network
        Tokens](/products/guardian/tokens/network-tokens#forwarding-cryptograms)
        for the full placeholder list.
      operationId: network_token_forward
      parameters:
        - in: path
          name: id
          description: The ID of the network token.
          schema:
            type: string
            format: uuid
          required: true
        - in: header
          name: x-cryptogram-reference
          description: >
            The `cryptogram_reference` UUID returned by [Request
            cryptogram](/products/guardian/api-reference/network/request-cryptogram)
            in `reference` mode. Single-use and short-lived.
          schema:
            type: string
            format: uuid
          required: true
        - in: header
          name: x-destination-url
          description: >
            The target URL to which the request shall be forwarded. Guardian
            forwards calls only to whitelisted destination URLs (major payment
            providers are included by default). Contact support to whitelist a
            custom URL.
          schema:
            type: string
            format: uri
            example: https://api.psp.example.com/payments
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: >
                The payload to forward to the third-party provider.


                Use placeholders to inject sensitive, cryptogram-derived data on
                the fly. Available placeholders include

                `{{ cryptogram }}`, `{{ dynamic_cvv }}`, `{{ eci }}`, `{{
                expiry_month }}`, `{{ expiry_year }}`, `{{ number }}`

                (the network token number / TPAN), `{{ type }}`, `{{
                scheme_reference }}`, `{{ network_token_id }}`, and `{{
                network_token_type }}`.

                Append `| unwrap` to emit a value as its native type instead of
                a string, e.g. `{{ expiry_month | unwrap }}`.

                See [Network Tokens](/products/guardian/tokens/network-tokens)
                for the full placeholder list.
            examples:
              adyen:
                description: Forward a payment request to Adyen
                value:
                  paymentMethod:
                    type: networkToken
                    number: '{{ number }}'
                    expiryMonth: '{{ expiry_month | unwrap }}'
                    expiryYear: '{{ expiry_year | unwrap }}'
                  mpiData:
                    authenticationResponse: 'Y'
                    cavv: '{{ cryptogram }}'
                    eci: '{{ eci }}'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: object
                description: The response from the third-party provider.
        '400':
          $ref: '#/components/responses/400_BadRequestError'
        '401':
          $ref: '#/components/responses/401_UnauthorizedError'
        '403':
          $ref: '#/components/responses/403_ForbiddenError'
        '404':
          $ref: '#/components/responses/404_NotFoundError'
        '502':
          $ref: '#/components/responses/502_BadGatewayError'
        '503':
          $ref: '#/components/responses/503_ServiceUnavailableError'
        '504':
          $ref: '#/components/responses/504_GatewayTimeoutError'
      security:
        - bearerAuth: []
        - APIKey: []
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
    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
    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:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT bearer token obtained via the OAuth2 client-credentials grant from
        the platform Authentication API. The token's scopes gate the endpoints
        it may call, and its audience names the Guardian instance. This is the
        standard way to authenticate to Guardian.
    APIKey:
      type: apiKey
      name: x-api-key
      in: header
      description: >-
        Deprecated. Long-lived instance API key, sent as `x-api-key`. Existing
        integrations continue to work, but new ones should use the OAuth2 bearer
        token instead.

````