> ## 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. # Request cryptogram > Request a cryptogram (TAVV) for a network token. Supports `ecom` (e-commerce) and `dauth` (delegated authentication). Set `mode` to control how the cryptogram is returned. `inline` returns the full cryptogram payload (SAQ-D / RoC only). `reference` returns a short-lived, single-use `cryptogram_reference` that you forward with [Forward cryptogram](/products/guardian/api-reference/network/forward-cryptogram). When omitted, `mode` defaults to `inline` on SAQ-D / RoC and is forced to `reference` on SAQ-A / SAQ-A EP. See [Network Tokens overview](/products/guardian/tokens/network-tokens). ## OpenAPI ````yaml /products/guardian/openapi.yaml post /api/network/tokens/{id}/cryptograms 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}/cryptograms: post: tags: - network summary: Request cryptogram description: > Request a cryptogram (TAVV) for a network token. Supports `ecom` (e-commerce) and `dauth` (delegated authentication). Set `mode` to control how the cryptogram is returned. `inline` returns the full cryptogram payload (SAQ-D / RoC only). `reference` returns a short-lived, single-use `cryptogram_reference` that you forward with [Forward cryptogram](/products/guardian/api-reference/network/forward-cryptogram). When omitted, `mode` defaults to `inline` on SAQ-D / RoC and is forced to `reference` on SAQ-A / SAQ-A EP. See [Network Tokens overview](/products/guardian/tokens/network-tokens). operationId: network_token_cryptogram parameters: - name: id in: path description: The ID of the token for which to request a cryptogram. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/cryptogram_request' examples: ecom: summary: E-commerce request value: type: ecom amount: 1000 currency_code: EUR reference: order_1234567890 dauth: summary: Delegated authentication request value: type: dauth amount: 1000 currency_code: EUR data: 0sxO1Q4+VME7xw7nwWJbagvHhu85JlJzQuMx+RuWL90= dynamic_data: delegated_authentication: true authentication_factor_a: X authentication_factor_b: 'Y' merchant_name: Example Merchant reference: order-1234567890 responses: '200': description: Success response with the requested cryptogram. content: application/json: schema: $ref: '#/components/schemas/cryptogram_response' '400': $ref: '#/components/responses/400_BadRequestError' '401': $ref: '#/components/responses/401_UnauthorizedError' '403': $ref: '#/components/responses/403_ForbiddenError' '404': $ref: '#/components/responses/404_NotFoundError' security: - bearerAuth: [] - APIKey: [] components: schemas: cryptogram_request: oneOf: - $ref: '#/components/schemas/cryptogram_request_ecom' - $ref: '#/components/schemas/cryptogram_request_dauth' cryptogram_response: oneOf: - $ref: '#/components/schemas/cryptogram_response_tavv' - $ref: '#/components/schemas/cryptogram_response_dynamic_cvv' - $ref: '#/components/schemas/cryptogram_response_reference' cryptogram_request_ecom: title: ECOM Request type: object properties: type: example: ecom type: string mode: type: string enum: - inline - reference description: > Controls whether the cryptogram is returned in the response or kept inside Guardian. - `inline` returns the full cryptogram payload. Only allowed when the instance compliance level is SAQ-D or RoC. - `reference` returns a short-lived, single-use `cryptogram_reference` instead. Forward it with [Forward cryptogram](/products/guardian/api-reference/network/forward-cryptogram). When omitted, the mode defaults to `inline` on SAQ-D / RoC and is forced to `reference` on SAQ-A / SAQ-A EP. amount: example: 700 type: integer 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. currency_code: example: EUR type: string description: | The three letter ISO-4217 currency code. reference: example: order-1234567890 type: string metadata: $ref: '#/components/schemas/Metadata' required: - amount - currency_code - reference cryptogram_request_dauth: title: DAuth Request type: object properties: type: example: dauth type: string mode: type: string enum: - inline - reference description: > Controls whether the cryptogram is returned in the response or kept inside Guardian. - `inline` returns the full cryptogram payload. Only allowed when the instance compliance level is SAQ-D or RoC. - `reference` returns a short-lived, single-use `cryptogram_reference` instead. Forward it with [Forward cryptogram](/products/guardian/api-reference/network/forward-cryptogram). When omitted, the mode defaults to `inline` on SAQ-D / RoC and is forced to `reference` on SAQ-A / SAQ-A EP. amount: example: 700 type: integer 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. currency_code: example: EUR type: string description: | The three letter ISO-4217 currency code. data: example: ZGV2aWNlLXNpZ25hdHVyZS1kYXRh type: string description: Signature data from the device. dynamic_data: type: object properties: delegated_authentication: example: true type: boolean authentication_factor_a: example: X type: string authentication_factor_b: example: 'Y' type: string required: - delegated_authentication - authentication_factor_a - authentication_factor_b merchant_name: example: Example Merchant type: string description: >- The name of the merchant associated with the delegated authentication. reference: example: order-1234567890 type: string description: > A reference for the cryptogram request, e.g. an order number. On VISA this field must only contain letters, numbers, and hyphens. metadata: $ref: '#/components/schemas/Metadata' required: - amount - currency_code - data - dynamic_data - reference cryptogram_response_tavv: type: object title: TAVV properties: type: type: string cryptogram: type: string description: > The token authentication verification value (TAVV) for the network token. eci: type: string description: | The Electronic Commerce Indicator (ECI) from the issuer. expiry_month: type: integer expiry_year: type: integer number: type: string metadata: $ref: '#/components/schemas/Metadata' example: order_ref: order-1234567890 required: - cryptogram - eci - expiry_month - expiry_year - number example: type: tavv cryptogram: Af9KZ3vVQkFxM3BZkJYFZkYBAgAEAAAB eci: '05' expiry_month: 10 expiry_year: 2030 number: '4122234533471157' cryptogram_response_dynamic_cvv: type: object title: Dynamic CVV properties: type: type: string dynamic_cvv: type: string description: | The dynamic CVV for the network token. expiry_month: type: integer expiry_year: type: integer number: type: string metadata: $ref: '#/components/schemas/Metadata' example: order_ref: order-1234567890 required: - dynamic_cvv - expiry_month - expiry_year - number example: type: dynamic_cvv dynamic_cvv: '471' expiry_month: 10 expiry_year: 2030 number: '37502542932225' cryptogram_response_reference: type: object title: Reference description: > Returned when the cryptogram is requested in `reference` mode. The full cryptogram stays inside Guardian; forward it with [Forward cryptogram](/products/guardian/api-reference/network/forward-cryptogram). properties: cryptogram_reference: type: string format: uuid description: > A short-lived, single-use handle pointing at the cryptogram stored inside Guardian. It is bound to the issuing tenant, the network token, and the calling credential, and is rejected on any binding mismatch. expires_at: type: string format: date-time description: > When the reference expires. A reference is invalidated after the first successful forward or after this time, whichever comes first. Defaults to 15 minutes after creation. required: - cryptogram_reference - expires_at example: cryptogram_reference: 58d6d56a-b3b8-4e6b-9df1-f6582e37a8b0 expires_at: '2026-06-02T12:15:00.000Z' ErrorGeneric: type: object properties: code: $ref: '#/components/schemas/ErrorStatusCode' classifier: $ref: '#/components/schemas/ErrorClassifier' message: $ref: '#/components/schemas/ErrorMessage' Metadata: type: object description: | Metadata consisting of key-value entries. * Maximum 20 key-value pairs. * Maximum 20 characters per key. * Maximum 80 characters per value. example: my_key_one: my_value_one my_key_two: my_value_two 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 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 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. ````