> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # Apple Pay via Proxy > Learn your options to tokenize Apple Pay instruments and how to use them in proxy flow. Payrails allows the use of tokenized Apple Pay instruments via the Instant Proxy integration. This allows merchants to forward sensitive Apple Pay data to supported payment providers without decrypting or storing the Apple Pay network token on their end. ## Tokenize Apple Pay instruments Before an Apple Pay token can be used in Instant proxy, we need to tokenize it and create an Instrument for it. Check our Apple Pay guide for detailed information on how to set up a new integration by storing the keys and certificates of your Apple Pay account to be able to decrypt Apple Pay tokens on your behalf. Payrails offers multiple ways to tokenize the card information, depending on the PCI DSS scope you are willing to own, the requirements about the level of control you need on your checkout page, and ease of implementation. Here's a table comparing your options from a high-level perspective: | Tokenization Type | Integration Effort | PCI Scope | | :- | :- | :- | | [Apple Button Element SDK with Payrails decryption](#1-apple-pay-button-element-sdk-with-payrails-decrypted-tokens) | Low | Low (SAQ and AOC) | | [Server-to-Server with Payrails decryption](#2-server-to-server-with-payrails-decrypted-tokens) | Medium | Low (SAQ and AOC) | | [Server-to-Server with Merchant decryption](#3-server-to-server-with-merchant-decrypted-tokens) | High | High (Level 1 ROC and AOC) | ### 1. Apple Pay Button Element SDK with Payrails-decrypted tokens Payrails Elements are payment UI components you can assemble together to build a payment form, giving better flexibility than Drop-in with the ability to manage each element separately. Check our Elements guide for more detailed information. Elements provides merchants with easy integration to Apple Pay tokenization without having the need to set up any integration with the Apple Pay SDK directly. Payrails manages all the keys needed for completing the Apple Pay session and detokenization, reducing all merchant overhead. Check out the [Apple Pay Button Element](/docs/orchestration/checkout-sdks/web-v5-legacy/elements#apple-pay-element) for a detailed guide. For details of how to integrate this option, move to this [section](#set-up-the-apple-pay-button-element-for-tokenization) . ### 2. Server-to-Server with Payrails-decrypted tokens In this integration method, the merchant maintains control over their Apple Pay integration, but they do not maintain the keys needed to decrypt the Apple Pay tokens. This provides merchants flexibility to keep their own Apple Pay SDK integration while not touching sensitive data in their servers. For this flow, once you obtain the encrypted Apple Pay token object from your direct integration with Apple, use [Create Instrument](/reference/createinstrument#/) API endpoint to pass it to Payrails. You will use `encyrptedData` object to pass the Apple Pay token, alongside `encryptedDataType` passed as 'networkToken', since Apple Pay digital wallet uses network tokens technology. Once you create the instrument, you are returned an instrumentId in the API response, and you can start passing this instrumentId in the Proxy API requests. For details of how to integrate this option, move to this [section](#2-server-to-server-with-payrails-decrypted-tokens-2). ### 3. Server-to-Server with merchant-decrypted tokens This integration method allows merchant to maintain control over their Apple Pay integration. Merchants implement the Apple Pay SDK integration and decryption of the Apple Pay token, and directly provide the decrypted network token to Payrails. This requires the necessary level of PCI compliance to be able to store and process PCI-sensitive data on your servers. For details of how to integrate this option, move to this [section](#3-server-to-server-with-merchant-decrypted-tokens-2). You can jump to [this section](#use-apple-pay-instrument-in-instant-proxy) to learn how to pass an Apple Pay instrument in a proxy API. *** ### 1. Apple Pay Button Element SDK with Payrails-decrypted tokens #### Set up the Apple Pay button element for tokenization ##### Perform Client init with Intent "tokenization" * Perform a [Client init](/reference/clientinit) with intent "tokenization\` ```json theme={null} { "type": "tokenization", "meta": { "order": { "softDescription": "Subscription" }, "clientContext": { "host": "example.merchant.com/store" } }, "amount": { "value": "0.00", "currency": "EUR" } } ``` * Provide the display name for the Apple Pay payment sheet in `meta.order.softDescription` * Provide the merchant store page initiative context in `meta.clientContext.host` * Provide the amount in `amount` ##### Render the Apple Pay button ```javascript theme={null} import { Payrails } from '@payrails/web-sdk'; // Call the backend to get the init response const initResponse = giveMeInitResponseFromBackend(); // Initialize client const Payrails = Payrails.init(initResponse); const element = payrails.applePayButton({ events: { onSuccess: (type: 'TOKENIZE', instrument?: any) => { console.log('yay!'); }, onFailed: (type: 'TOKENIZE', error?: any) => { console.log('nah :('); }, onButtonClicked: async () => { console.log('button clicked'); // If resolved to false, process will STOP before applePay session creation return Promise.resolve(true); }, onRequestStart: async () => { console.log('Requesting...'); // If resolved to false, process will STOP before instrument creation }, onApplePayAvailable() => { console.log('Apple Pay ready'); // event will fire when Apple Pay Button is initialized }, styles: { type: 'plain', style: 'black' } }, translations: { labels: { paymentScreenLabel: "Checkout with applePay" } } }); element.mount('#apple-pay-button-container'); ``` * Listen to the `onSuccess` callback for the event of type `TOKENIZE` to get the details for the newly created Apple Pay Instrument Once the instrument has been created, it can be used in the instant proxy in your backend service. Jump to this [section](#use-apple-pay-instrument-in-instant-proxy) to read more. ### 2. Server-to-Server with Payrails-decrypted tokens If you prefer to use your own client-side implementation for Apple Pay button, where you receive the encrypted Apple Pay token, you can use Payrails APIs with a server-to-server integration to process payments with Apple Pay. Note that, with this approach, you will follow the Apple documentation here to build Apple Pay into your applications. In this flow, although you receive the Apple Pay token from Apple, you can pass it to Payrails to decrypt it on your behalf, so that you don't have to manage PCI-sensitive data on your servers. In order for Payrails to decrypt the Apple Pay tokens, follow our [guide](/docs/orchestration/payment-methods/apple-pay#request-certificate-signing-requests-csrs) to share your certificate and key with Payrails. Once you are ready with the Apple integration and get an Apple Pay token object, you will create payment instruments to use them in Payrails proxy APIs. #### Create the Apple Pay instrument in Payrails Once you have completed the above steps, Apple Pay SDK will provide you with payment tokens encrypted by Apple. Use POST/ Create Instrument API endpoint, send paymentMethod=applePay, and pass the decrypted Apple Pay token under data.encryptedData object, with encryptedDataType=networkToken, and by providing fields like billing address and eci details. See below an example and API reference for all details of the object. ```Text JSON theme={null} { "paymentMethod": "applePay", "displayName": "Visa 4443" "data": { "encryptedData": ".......encryptedApplePayNetworkToken.......", "encryptedDataType": "networkToken", "network": "visa", "eci": "07", "billingAddress": { "street": "Berlin street", "doornumber": "345", "postalCode": "30103", "city": "Berlin", "country": "DE", }, } } ``` Once the instrument has been created, it can be used in the instant proxy in your backend service. Jump to this [section](#use-apple-pay-instrument-in-instant-proxy) to read more. ### 3. Server-to-Server with merchant-decrypted tokens Once you are ready with your own client-side implementation and decryption of Apple Pay tokens, you can use Payrails APIs with a server-to-server integration to process payments with Apple Pay. Note that, with this approach, you will follow the Apple documentation here to build Apple Pay into your applications. Once you are ready with the Apple integration and can have the decrypted Apple Pay tokens, you will create payment instruments to use them in Payrails proxy APIs. #### Prepare the Apple Pay token 1. Apple Pay SDK will provide you with a payment token encrypted by Apple. 2. Decrypt the Apple Pay token with your integration (using your Apple Pay private keys). 3. Populate the token into the Payrails network token format as below: ```Text JSON theme={null} { "cardNumber": "4111111111111111", "expiryMonth": "03", "expiryYear": "30", "securityCode": "ApplePayCryptogram==", "holderName": "John Doe", "holderReference": "customer123" } ``` 4. Encrypt the network token with the vault public key. **Note** that when you decrypt an Apple Pay token, the data you have is PCI-sensitive data. Therefore, our API requires this value to be passed as encrypted by a public key by Payrails Vault. The sensitive details should be encrypted with the RSA public key provided by Payrails SDK or public encryption key API, using JWE with encryption algorithm RSA-OAEP-256 and content encryption A256CBC-HS512. #### Create the Apple Pay instrument Once you have completed the above steps, the next step will be creating an Apple Pay instrument. Use POST/ Create Instrument API endpoint, send paymentMethod=applePay, and pass the decrypted Apple Pay token under data.encryptedData object, with encryptedDataType=networkToken, and by providing fields like billing address and eci details. See below an example and API reference for all details of the object. ```Text JSON theme={null} { "paymentMethod": "applePay", "displayName": "Visa 4443" "data": { "encryptedData": ".......encryptedApplePayNetworkToken.......", "encryptedDataType": "networkToken", "network": "visa", "eci": "07", "billingAddress": { "street": "Berlin street", "doornumber": "345", "postalCode": "30103", "city": "Berlin", "country": "DE", }, } } ``` Once the instrument has been created, it can be used in the instant proxy in your backend service. Move to the next [section](#use-apple-pay-instrument-in-instant-proxy) to read more. ## Use Apple Pay instrument in Instant Proxy With the instrument created, you can now forward it to your payment providers via Instant Proxy. Check out the [Instant Proxy](/docs/token-vault/vault-proxy/proxy-payment-instruments/cards-via-proxy) for a detailed guide. ### Prepare the request body you want to pass to the payment provider based on the provider's API contract. This request will include fields that are non-sensitive (i.e. amount), as well as the card information that is PCI sensitive. You will put `{{key}}` in the place of the sensitive fields, while forwarding the rest of the payload as it is. Read in the next section what the key variables you will use are in more detail. This is the `body` object you will see under [Vault Proxy API.](/reference/vaultproxy) ### Prepare the request headers that are needed to be passed to the payment provider The payment providers typically require certain headers to securely receive a request from the senders, such as authentication or authorization keys. In order for us to send a request to the payment provider, we need to provide those headers when forwarding your request to the provider. You will provide all required header information defined by the provider's API contract. This is the `headers` object in [Vault Proxy API](/reference/vaultproxy). ### Prepare the URL of the provider that you want Payrails to forward the request. You have to define a destination URL path for every proxy request that you want to send. This is the URL of the API endpoint of the payment provider. You will pass it to Payrails, so that we can send your request body and headers you prepared in the previous steps to the designated URL. This is `url` object in [Vault Proxy API](/reference/vaultproxy). Below you can find some examples of some well-known providers and how you should map the card data using our instruments. ```json Checkout theme={null} { "paymentInstrumentId": "eeaac45c-f032-49bc-a8c5-ec99d79b74e2", "url": "https://api.sandbox.checkout.com/payments", "headers": { "x-API-key": "YOUR_API_KEY", "Content-Type": "application/json" }, "body": { "amount": 1000, "currency": "USD", "reference": "some_reference", "source": { "type": "network_token", "token_type": "applepay", "token": "{{networkTokenNumber}}", "expiry_month": "{{networkTokenExpiryMonth}}", "expiry_year": "{{networkTokenExpiryYear}}", "cryptogram": "{{networkTokenCryptogram}}", "name": "{{cardHolderName}}" }, "payment_type": "Regular", "authorization_type": "Final", "capture": true, "processing_channel_id": "pc_xxxxxxxxxxx", "risk": { "enabled": false }, "merchant_initiated": true } } ``` ```json Stripe theme={null} { "paymentInstrumentId": "eeaac45c-f032-49bc-a8c5-ec99d79b74e2", "url": "https://api.stripe.com/v1/payment_intents", "headers": { "Authorization": "***", "Content-Type": "application/x-www-form-urlencoded", "Idempotency-Key": "{{your-unique-key}}" }, "body": "amount=1000¤cy=usd&confirm=true&payment_method_types[]=card&payment_method_data[type]=card&payment_method_data[card][last4]=9999&payment_method_data[card][network_token][number]={{networkTokenNumber}}&payment_method_data[card][network_token][exp_month]={{networkTokenExpiryMonth}}&payment_method_data[card][network_token][exp_year]={{networkTokenExpiryYear}}&payment_method_options[card][network_token][cryptogram]={{networkTokenCryptogram}}&payment_method_options[card][network_token][electronic_commerce_indicator]=07" } ``` 1. For network token number, use `{{networkTokenNumber}}` 2. For cryptogram, use `{{networkTokenCryptogram}}` 3. For the expiry month of the network token, use `{{networkTokenExpiryMonth}}` 4. For the expiry year of the network token, if: 1. 4-digit expiry year of the network token, use `{{networkTokenExpiryYear}}` 2. 2-digit expiry year of the network token, use `{{networkTokenExpiryYear2Digits}}` Apple Pay tokens will always contain a network token in them, always use the network token place holders when making a proxy request for an apple pay instrument. ## Related topics - [Google Pay via Proxy](/docs/token-vault/vault-proxy/proxy-payment-instruments/google-pay-via-proxy.md) - [Cards via Proxy](/docs/token-vault/vault-proxy/proxy-payment-instruments/cards-via-proxy.md) - [Apple Pay](/docs/orchestration/payment-methods/apple-pay.md)