> ## 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. # Tokenize Apple Pay > Turn an Apple Pay payment into a stored wallet token. Pass the `PKPaymentToken` `paymentData` envelope exactly as the Apple Pay JS API returns it, as the `payment_data` field. Guardian verifies the `EC_v1` signature against Apple's trusted certificates and decrypts the payload server-side with your active payment processing certificate, so the decrypted card data never touches your systems. An Apple Pay payment always yields a device-bound token: a device PAN (DPAN) with a single-use cryptogram and ECI. The underlying funding PAN is never extracted, stored, or returned, so an Apple Pay token cannot be promoted to a network token. Tokenization is idempotent on the encrypted payload: resubmitting the same envelope returns the existing wallet token. If that payload's token was already deleted, the request returns `409` with the classifier `APPLE_PAY_TOKEN_DELETED`. Rejected envelopes return `422` with a classifier naming the cause: `APPLE_PAY_SIGNATURE_INVALID`, `APPLE_PAY_UNKNOWN_CERTIFICATE`, `APPLE_PAY_TOKEN_EXPIRED`, or `APPLE_PAY_MALFORMED_TOKEN` (Guardian's generic missing-field classifier, shared by the other Apple Pay endpoints). If no active payment processing certificate exists, the request returns `500` with the classifier `APPLE_PAY_NO_ACTIVE_CERTIFICATE`. See [Apple Pay](/products/guardian/tokens/wallet-tokens/apple-pay) for prerequisites and the full flow. ## OpenAPI ````yaml /products/guardian/openapi.yaml post /api/wallet/apple-pay/tokenize 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/apple-pay/tokenize: post: tags: - wallet summary: Tokenize Apple Pay description: > Turn an Apple Pay payment into a stored wallet token. Pass the `PKPaymentToken` `paymentData` envelope exactly as the Apple Pay JS API returns it, as the `payment_data` field. Guardian verifies the `EC_v1` signature against Apple's trusted certificates and decrypts the payload server-side with your active payment processing certificate, so the decrypted card data never touches your systems. An Apple Pay payment always yields a device-bound token: a device PAN (DPAN) with a single-use cryptogram and ECI. The underlying funding PAN is never extracted, stored, or returned, so an Apple Pay token cannot be promoted to a network token. Tokenization is idempotent on the encrypted payload: resubmitting the same envelope returns the existing wallet token. If that payload's token was already deleted, the request returns `409` with the classifier `APPLE_PAY_TOKEN_DELETED`. Rejected envelopes return `422` with a classifier naming the cause: `APPLE_PAY_SIGNATURE_INVALID`, `APPLE_PAY_UNKNOWN_CERTIFICATE`, `APPLE_PAY_TOKEN_EXPIRED`, or `APPLE_PAY_MALFORMED_TOKEN` (Guardian's generic missing-field classifier, shared by the other Apple Pay endpoints). If no active payment processing certificate exists, the request returns `500` with the classifier `APPLE_PAY_NO_ACTIVE_CERTIFICATE`. See [Apple Pay](/products/guardian/tokens/wallet-tokens/apple-pay) for prerequisites and the full flow. operationId: wallet_apple_pay_tokenize requestBody: content: application/json: schema: $ref: '#/components/schemas/apple_pay_tokenize_request' responses: '200': description: Success response content: application/json: schema: $ref: '#/components/schemas/apple_pay_tokenize_response' '401': $ref: '#/components/responses/401_UnauthorizedError' '403': $ref: '#/components/responses/403_ForbiddenError' '409': $ref: '#/components/responses/409_ConflictError' '422': $ref: '#/components/responses/422_ValidationError' '500': description: >- No active Apple Pay payment processing certificate exists on this instance. content: application/json: schema: $ref: '#/components/schemas/ErrorGeneric' example: code: 500 message: >- The Apple Pay token could not be processed due to a server-side configuration issue. classifier: APPLE_PAY_NO_ACTIVE_CERTIFICATE security: - bearerAuth: [] - APIKey: [] components: schemas: apple_pay_tokenize_request: type: object properties: payment_data: type: object description: > The Apple Pay `EC_v1` `paymentData` envelope, passed through verbatim as returned by the Apple Pay JS API. properties: version: type: string example: EC_v1 data: type: string description: Base64-encoded encrypted payment data. signature: type: string description: Base64-encoded CMS signature. header: type: object properties: ephemeralPublicKey: type: string publicKeyHash: type: string transactionId: type: string required: - ephemeralPublicKey - publicKeyHash - transactionId required: - version - data - signature - header required: - payment_data example: payment_data: version: EC_v1 data: 3+f5jVXhLf8T... signature: MEUCIQD... header: ephemeralPublicKey: MFkwEwYHKoZ... publicKeyHash: OrWgjRGkqEWlx... transactionId: c1caf5ae5f... apple_pay_tokenize_response: title: Apple Pay Tokenize Response type: object properties: id: type: string format: uuid description: The ID of the stored wallet token. card: type: object properties: brand: type: string example: visa last4: type: string example: '4242' expiry_month: type: integer example: 12 expiry_year: type: integer example: 2028 required: - brand - last4 - expiry_month - expiry_year required: - id - card example: id: 0d5c1774-5f3f-4a2f-9c86-1f30a0ea9be2 card: brand: visa last4: '4242' expiry_month: 12 expiry_year: 2028 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 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 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. ````