> ## 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 wallet token > Forward a request to a certified third-party provider with the wallet token's card data injected server-side, so it never touches your systems. This mirrors [Forward card data](/products/guardian/api-reference/pci/forward-card-data) and [Forward cryptogram](/products/guardian/api-reference/network/forward-cryptogram). The available placeholders depend on the token's `auth_method`: - `CRYPTOGRAM_3DS`: `{{ dpan }}`, `{{ cryptogram }}`, `{{ eci }}`, `{{ expiry_month }}`, `{{ expiry_year }}`. The cryptogram is single-use — the token is consumed by the first successful forward. - `PAN_ONLY`: `{{ fpan }}`, `{{ expiry_month }}`, `{{ expiry_year }}`. Forwardable repeatedly. Using a placeholder the token's `auth_method` does not carry returns `422` with the classifier `DESTINATION_POLICY_VIOLATION`; a declared placeholder without a value on this specific token returns `422` with `PLACEHOLDER_VALUE_MISSING`. Forwarding an already-consumed `CRYPTOGRAM_3DS` token returns `400` with `CRYPTOGRAM_CONSUMED`. See [Wallet Tokens](/products/guardian/tokens/wallet-tokens/overview#forwarding-wallet-tokens) for details. ## OpenAPI ````yaml /products/guardian/openapi.yaml post /api/wallet/{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/wallet/{id}/forward: post: tags: - wallet summary: Forward wallet token description: > Forward a request to a certified third-party provider with the wallet token's card data injected server-side, so it never touches your systems. This mirrors [Forward card data](/products/guardian/api-reference/pci/forward-card-data) and [Forward cryptogram](/products/guardian/api-reference/network/forward-cryptogram). The available placeholders depend on the token's `auth_method`: - `CRYPTOGRAM_3DS`: `{{ dpan }}`, `{{ cryptogram }}`, `{{ eci }}`, `{{ expiry_month }}`, `{{ expiry_year }}`. The cryptogram is single-use — the token is consumed by the first successful forward. - `PAN_ONLY`: `{{ fpan }}`, `{{ expiry_month }}`, `{{ expiry_year }}`. Forwardable repeatedly. Using a placeholder the token's `auth_method` does not carry returns `422` with the classifier `DESTINATION_POLICY_VIOLATION`; a declared placeholder without a value on this specific token returns `422` with `PLACEHOLDER_VALUE_MISSING`. Forwarding an already-consumed `CRYPTOGRAM_3DS` token returns `400` with `CRYPTOGRAM_CONSUMED`. See [Wallet Tokens](/products/guardian/tokens/wallet-tokens/overview#forwarding-wallet-tokens) for details. operationId: wallet_token_forward parameters: - in: path name: id description: The ID of the wallet token to forward. 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 the wallet token's card data on the fly. Append `| unwrap` to emit a value as its native type instead of a string, e.g. `{{ expiry_month | unwrap }}`. examples: cryptogram_3ds: summary: Device token (CRYPTOGRAM_3DS) description: Forward a device-bound Google Pay token to a processor value: paymentMethod: type: networkToken number: '{{ dpan }}' expiryMonth: '{{ expiry_month | unwrap }}' expiryYear: '{{ expiry_year | unwrap }}' mpiData: authenticationResponse: 'Y' cavv: '{{ cryptogram }}' eci: '{{ eci }}' pan_only: summary: Card on file (PAN_ONLY) description: Forward a card-on-file Google Pay token to a processor value: paymentMethod: type: scheme number: '{{ fpan }}' expiryMonth: '{{ expiry_month | unwrap }}' expiryYear: '{{ expiry_year | unwrap }}' 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' '422': $ref: '#/components/responses/422_ValidationError' '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 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 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' 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: example: $.source.account_number type: string description: Json-path in the request which points to the validation error message: example: is required type: string description: Human readable validation message 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. ````