> ## 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: hello@starfish.team url: https://hellgate.io/cpa/guardian license: name: Hellgate API Terms url: https://hellgate.io/terms-and-conditions servers: - url: https://{cluster_id}.on-hellgate.cloud description: Guardian service instance variables: cluster_id: default: my-cluster-id description: | Guardian is a service of the Hellgate Cloud Platform. The unique cluster-id is used to connect to your instance. 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: - APIKey: [] - AdminToken: [] 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: type: string description: Json-path in the request which points to the validation error message: 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: APIKey: type: apiKey name: x-api-key in: header AdminToken: type: apiKey name: x-admin-token in: header ````