---
title: Apple Pay™ for Web
slug: apple-paytm-for-web
docTags: 
createdAt: 2024-08-19T12:45:36.639Z
---

:::hint{type="info"}
It is assumed you already have a Judopay account. If you do not, sign up for a sandbox account [here](https://www.judopay.com/contact/apply-sandbox-account).
:::

### Prerequisites

**From the Web SDK integration guide:**

- [Create a paymentSession](docId:40dWE6LBub7vdKza1QYDC)
- [Add the Payment Form to your Website](docId:40dWE6LBub7vdKza1QYDC)
  - To hide the payment form iFrame, use:
    `<div id="payment-iframe" style="position:absolute;width:0;height:0;border:0;"></div>`

:::hint{type="info"}
The payment form iFrame must be loaded onto the page in order for payments to work.&#x20;
However displaying the form to the consumer is not required for this transaction type.
:::

**Direct from Judopay**:

- Judopay JudoID
- A valid `apple-developer-merchantid-domain-association`
  - Get it [here](docId\:oelqjygAmbce2048QcJP1).

**From the Merchant**:&#x20;

- Domain(s) being used for Apple Pay™
- These are the domain(s) where the Apple Pay™ button will be displayed, for example the checkout page.&#x20;

:::hint{type="warning"}
These must be SSL enabled domains, Apple will not allow non-encrypted domains to be used.
:::

- Account(s) being used for Apple Pay™

***

## Integrating Apple Pay™

### Step One: Place the Apple Pay™ Button

Using Judopay's **Web SDK**:

1. Within your checkout page code, add the following for placement of the Apple Pay™ button:
   `<div id="apple-pay-button-container" width="100%" align="left"></div>`&#x20;

:::hint{type="info"}
This \<div> tag will be exchanged to display the Apple Pay™ button.
(On a browser or device that can use Apple Pay™, for example an iPhone, or Safari Browser on a Mac).
:::

***

### Step Two: Update the Apple Pay™ Button

1. Include the following script to create the Apple Pay™ button:
   This sample will call the **handleApplePayButtonClick&#x20;**&#x66;unction, when the button is clicked.

:::CodeblockTabs
Create Apple Pay Button

```javascript
<script>
var button = judo.digitalWallets.getApplePayButton({
height: 38, 
width: 240, 
language: 'EN', 
style: 'black', 
type: 'buy'});

button.onclick = handleApplePayButtonClick

document.getElementById('apple-pay-button-container').appendChild(button)

</script>   
```
:::

**Style**:

- black
- white

**Type&#x20;**<font color="#42cbd4">(</font><font color="#42cbd4">Optional</font><font color="#42cbd4">)</font>:

- If set to buy:
  - **Buy now with Apple**, will be displayed.
- If omitted:
  - The Apple **Logo&#x20;**&#x77;ill be displayed.

***

### Step Three: Handle the Apple Pay™ Button Click

1. Include the following script to handle the Apple Pay™ Payment:

:::hint{type="info"}
Replace the items in \{\{**brackets**}} with your values.
:::

:::CodeblockTabs
Handle Apple Pay Payment

```javascript
<script>
function handleApplePayButtonClick() {

 let applePayConfiguration = {  
      amount: '{{amount}}',  
      currency: '{{currency}}',  
      yourConsumerReference: '{{yourConsumerReference}}',  
      yourPaymentReference: '{{yourPaymentReference}}',  
      judoId: '{{judoId}}', 
      initiativeContext: '{{yourDomainName}}'
 }

 judo.digitalWallets.invokePaymentWithApplePay({{paymentSession}}, configuration)
      .then(handleSuccess)
      .catch(handleError)
} 
</script>
```
:::

### Configuration Object Parameter Descriptions

See below for more details on the parameters that create the **applePayConfiguration&#x20;**&#x6F;bject:

**Apple Pay™ Configuration Object Parameter Descriptions:**

| **Parameter**                                                                             | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `judoId`<br />String<br /><font color="#ef5b2e">Required</font><br /><br />               | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                                                                                                                                                            |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font><br /><br />              | The amount to process.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.                                                                                                                                                                                                                                                                                                      |
| `currency`<br />String<br /><font color="#ef5b2e">Required</font><br /><br />             | The currency of the transaction. <br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR                                                                                                                                                                                                                                                                                                                                                   |
| `yourConsumerReference`<br />String<br /><font color="#ef5b2e">Required</font>            | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                                                                                                                                                                 |
| `yourPaymentReference`<br />String<br /><font color="#ef5b2e">Required</font><br /><br /> | Your unique reference for this payment.<br />Format:<br />* Maximum length 50 characters.<br />This value should be unique in order to protect your customers against duplicate transactions. <br />With a server side integration, if a payment reference is not supplied, the transaction will not be processed.                                                                                                                                     |
| `initiativeContext`<br />String<br /><font color="#42cbd4">Optional</font>                | Your fully qualified domain name associated with your **Apple Pay Merchant Identity Certificate**.<br />* The default is: `window.location.hostname`
* For example: `initiativeContext ="web.judopay.com"`                                                                                                                                                                                                                                             |
| `methodConfiguration`<br />Object<br /><font color="#42cbd4">Optional</font>              | This parameter contains the following fields:<br />* version
  - number
* supportedNetworks
  - array containing any of the following strings:
    - “amex”
    - “chinaUnionPay”
    - “discover”
    - “masterCard”
    - “visa”
    - “maestro”
    - “jcb”
* merchantCapabilities
  - array containing any of the following strings:
    - "supports3DS"
    - "supportsCredit"
    - "supportsDebit"
    - "supportsEMV"
* countryCode
  - string |
| `details`<br />Object<br /><font color="#42cbd4">Optional</font><br />                    | Provides information about the specific transaction. Use this object to supply the information for recurring payments.<br />For more information, see [Apple Pay™ Recurring Payments .](docId\:oelqjygAmbce2048QcJP1) <br />See [here](https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/PaymentRequest) for more details on the parameter fields.                                                                                       |
| `options`<br />Object<br /><font color="#42cbd4">Optional</font>                          | Enables you to set options to control the behaviour of the user agent.<br />See [here](https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/PaymentRequest) for more details on the parameter fields.                                                                                                                                                                                                                                       |
| `onShippingAddressChange`<br />Method<br /><font color="#42cbd4">Optional</font>          | Dispatched when the user changes their shipping address.<br />See [here](https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/shippingaddresschange_event) for more details on this parameter.                                                                                                                                                                                                                                              |
| `onShippingOptionChange`<br />Method<br /><font color="#42cbd4">Optional</font>           | Dispatched when the user changes a shipping option.<br />See [here](https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/shippingoptionchange_event) for more details on this parameter.                                                                                                                                                                                                                                                    |
| `delayedAuthorisation`<br />Boolean<br /><font color="#42cbd4">Optional</font>****        | **For preAuths only**.<br />Set to true to authenticate a card holder with 3D secure, without performing payment authorisation.<br />When set to true, the 3D Secure authentication status is returned in the response.<br />The payment authorisation is carried out at the stage when you are ready to **collect the amount from the customer**.<br />* The default value = **false**                                                                |
| `initialRecurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>         | Indicates if this initial payment is part of a recurring payment.<br />For more information, see [Apple Pay™ Recurring Payments .](docId\:oelqjygAmbce2048QcJP1)                                                                                                                                                                                                                                                                                       |

2\. Ensure the configuration options for:

- amount
- currency
- yourConsumerReference
- yourPaymentReference

  match those used when obtaining the valid paymentSession.


This is used to cross reference the validity of the transaction.

***

### Step Four: Handle the Response

All the Judopay Web SDK transaction methods return a promise.
Once the authorisation is complete, the promise will be either fulfilled or rejected.

**Fulfilled**

- You will receive a JSON object response (a Judopay receipt object).
  - For more information and schema on the JSON object, see [API Transaction Response](docId\:bcXNM5keOk-nlNrZTafUT).
- Depending on the result the consumer should be redirected to the appropriate outcome page.
  - For example, if the result = SUCCESS redirect the consumer to the Success Page.
- This page should display the necessary transaction information (found in the Judopay receipt object).

**Rejected**

- You will receive an error object
  - For more information on error responses returned, see [Web SDK Error Responses](docId\:qfxaWPAQl_-2EVfP8y94d).
- The consumer should be redirected to an Error Page.

:::CodeblockTabs
Response Example

```json
const onFulfillment = (receiptObject) => {
  const { result } = receiptObject
  //redirect to appropriate page depending on the result (success/failure/declined page)
}

const onRejection = (error) => {
  //redirect to error page and handle error
}
```
:::

For more information on the response codes, see [Codes](docId:_zrsihomUEW-XnRQ4PBtJ).

***

## Apple Pay™ Recurring Payments

Make sure you are using:

- Web SDK **Version** **0.1.0&#x20;**(or higher)

:::hint{type="warning"}
Integration via Web Payments is not currently supported.
:::

Judopay supports Merchant Initiated Transactions (MIT)s for Wallet Customer Initiated Transactions (CIT)s.&#x20;

Apple Pay™ recurring payments enables you to process a standard Apple Pay™ transaction, however by setting the `initialRecurringPayment` flag in the initial transaction, will result in an Apple Pay™ recurring / deferred payment token (also known as a Merchant Primary Account Number, or MPAN) being generated and sent to Judopay.

The Apple Pay™ MPAN is stored by Judopay, and an associated Judopay card token is returned in the Apple Pay™ transaction response.&#x20;

This associated Judopay card token can then be used by you for future Merchant Initiated Transactions.

### Recurring Payments&#x20;

Apple Pay™ accepts the MIT descriptor only through a `PaymentDetailsModifier`.&#x20;
The Web SDK handles that for you.

To trigger an initial transaction that allows you to set up an Apple Pay™ recurring payment token for future Merchant Initiated Transactions (MIT):

1. Set `recurringPaymentRequest` on the `ApplePayPaymentConfiguration` passed to `invokePaymentWithApplePay` / `invokePreAuthWithApplePay`
2. Shapes follow Apple Pay™s `ApplePayRecurringPaymentRequest`
   The SDK injects the `tokenNotificationURL`:

:::CodeblockTabs
Recurring Payments Example

```json
import JudoPay, { ApplePayPaymentConfiguration } from "web-sdk";

const judopay = new JudoPay("<API_TOKEN>", /* sandbox */ true);

const configuration: ApplePayPaymentConfiguration = {
  judoId: "<JUDO_ID>",
  amount: "25.00",
  currency: "GBP",
  yourPaymentReference: "<PAYMENT_REF>",
  yourConsumerReference: "<CONSUMER_REF>",
  // First charge is taken now, together with the mandate setup:
  initialRecurringPayment: true,
  recurringPaymentRequest: {
    paymentDescription: "Premium Plan subscription",
    managementURL: "https://merchant.example.com/subscriptions",
    billingAgreement: "Subscription auto-renews until cancelled.",
    regularBilling: {
      label: "Premium Plan — monthly",
      amount: "25.00",
      type: "final",
      paymentTiming: "recurring",
      recurringPaymentStartDate: new Date("2026-10-01T00:00:00Z"),
      recurringPaymentIntervalUnit: "month",
      recurringPaymentIntervalCount: 1,
      // recurringPaymentEndDate omitted -> open-ended
    },
    // Optional discounted / trial first period
    trialBilling: {
      label: "7 day free trial",
      amount: "0.00",
      type: "final",
      paymentTiming: "recurring",
      recurringPaymentIntervalUnit: "day",
      recurringPaymentIntervalCount: 7,
    },
  },
};

const button = judopay.digitalWallets.getApplePayButton({ type: "subscribe" });
button.onclick = () => {
  judopay.digitalWallets
    .invokePaymentWithApplePay("<PAYMENT_SESSION>", configuration)
    .then((response) => console.log("Recurring mandate set up", response))
    .catch((error) => console.error(error));
};
document.getElementById("apple-pay-container").append(button);
```
:::

Judopay acts as &#x61;**&#x20;pass-through service**, whereby we supply the data needed by Apple Pay™ for them to return a device / merchant specific token that can be used for MIT transactions.&#x20;

For a full description on all the object properties in the Apple Pay™ recurring payments flow, see the [Apple Pay™ Documentation](https://developer.apple.com/documentation/applepayontheweb/applepayrecurringpaymentrequest).

***

### Deferred Payments

Apple Pay™ accepts the MIT descriptor only through a `PaymentDetailsModifier`.
The Web SDK handles that for you.

To trigger an initial transaction that allows you to set up an Apple Pay™ deferred payment token for future Merchant Initiated Transactions (MIT):

1. Set `deferredPaymentRequest` on the `ApplePayPaymentConfiguration` passed to `invokePaymentWithApplePay` / `invokePreAuthWithApplePay`&#x20;
2. Shapes follow Apple Pay™s `ApplePayDeferredPaymentRequest`&#x20;
   The SDK injects the `tokenNotificationURL`:

:::CodeblockTabs
Deferred Payment Example

```json
import JudoPay, { ApplePayPaymentConfiguration } from "web-sdk";

const judopay = new JudoPay("<API_TOKEN>", /* sandbox */ true);

const configuration: ApplePayPaymentConfiguration = {
  judoId: "<JUDO_ID>",
  amount: "200.00",
  currency: "GBP",
  yourPaymentReference: "<PAYMENT_REF>",
  yourConsumerReference: "<CONSUMER_REF>",
  deferredPaymentRequest: {
    paymentDescription: "Hotel room reservation",
    managementURL: "https://merchant.example.com/bookings",
    billingAgreement: "Your card will be charged on the billing date shown.",
    deferredBilling: {
      label: "Hotel room reservation",
      amount: "200.00",
      type: "final",
      paymentTiming: "deferred",
      deferredPaymentDate: new Date("2027-01-01T08:00:00Z"),
    },
    // Optional: date until which the shopper can cancel for free
    freeCancellationDate: new Date("2026-12-25T08:00:00Z"),
    freeCancellationDateTimeZone: "Europe/London",
  },
};

const button = judopay.digitalWallets.getApplePayButton({ type: "book" });
button.onclick = () => {
  judopay.digitalWallets
    .invokePaymentWithApplePay("<PAYMENT_SESSION>", configuration)
    .then((response) => console.log("Deferred payment authorised", response))
    .catch((error) => console.error(error));
};
document.getElementById("apple-pay-container").append(button);
```
:::

Judopay acts as &#x61;**&#x20;pass-through service**, whereby we supply the data needed by Apple Pay™ for them to return a device / merchant specific token that can be used for MIT transactions.&#x20;

For a full description on all the object properties in the Apple Pay™ recurring payments flow, see the [Apple Pay™ Documentation](https://developer.apple.com/documentation/applepayontheweb/applepaydeferredpaymentrequest).

***

## Domain Registration

To get your valid Apple™ domain registration:

1. Create the following (well-known) folder on your web server's **root** domain directory:
   `./well-known`
2. In the folder, create a web server identity file:
   **apple-developer-merchantid-domain-association**
3. Download the following contents to the web server identity file:

::File{src="https://api.archbee.com/api/presign/QGXTyW3MgdNcMjdEa0v8r/A2iUILa8_uflH-N9WDfzD_apple-developer-merchantid-domain-association.txt" label="apple-developer-merchantid-domain-association.txt" indent="2"}

:::hint{type="warning"}
Make sure you remove the **.txt file extension**.
:::

&#x20;  4\. Complete a web server test:

- Make sure the web server identity file is accessible externally from your website.
- In a browser go to:
  `https://www.yourdomain.com/.well-known/apple-developer-merchantid-domain-association`
- Change the location to your website domain.
- Ensure that the `apple-developer-merchantid-domain-association` file is downloadable.

:::hint{type="info"}
Apple will use this location to check the validity of your domain. It is important this is externally accessible.
:::

&#x20;   5\. Notify [Judopay](mailto\:developersupport@judopay.com) of the following details:

- **JudoID(s)&#x20;**
  - List your JudoIDs you wish enabled for Apple Pay™
- **Domain(s)**
  - List your domain URLs you wish enabled for Apple Pay™&#x20;

:::hint{type="info"}
Judopay developer support will enable your account(s) with the Apple Pay™ configuration that will allow you to perform Apple Pay™ transactions from those domains.
Once complete, we will reply to your original request notifying you that this has been actioned.
:::

***

## Testing your Wallet Payment Integration

Wallet Payment Scenarios (via Web SDK Integration):

- [Apple Pay™](docId\:t13itu-7QX7Ylrxgvj5jt)

For more information see, [Testing your Wallet Payment Integration](docId\:IyacWLIdSCQIKMCfrrkhp).