Apple Pay™ for Web

It is assumed you already have a Judopay account. If you do not, sign up for a sandbox account here.

Prerequisites

From the Web SDK integration guide:

Create a paymentSession

Add the Payment Form to your Website

To hide the payment form iFrame, use: <div id="payment-iframe" style="position:absolute;width:0;height:0;border:0;"></div>

The payment form iFrame must be loaded onto the page in order for payments to work. 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.

From the Merchant:

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.

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:

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>

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

Include the following script to create the Apple Pay™ button: This sample will call the handleApplePayButtonClick function, when the button is clicked.

<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 (Optional):

If set to buy:

Buy now with Apple, will be displayed.

If omitted:

The Apple Logo will be displayed.

Step Three: Handle the Apple Pay™ Button Click

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

Replace the items in {{brackets}} with your values.

<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 object:

Apple Pay™ Configuration Object Parameter Descriptions:

Parameter	Description
judoId String Required	Unique ID supplied by Judopay. Specific to a merchant and/or location. Format: 100100100 Maximum length 9 characters. Do not include spaces or dashes.
amount Decimal Required	The amount to process. Format: Two decimal places For currencies using a different structure please contact Judopay for support.
currency String Required	The currency of the transaction. Any ISO 4217 alphabetic currency code: GBP USD EUR
yourConsumerReference String Required	Unique reference to anonymously identify your customer. Advisable to use GUIDs. Must be below 40 characters.
yourPaymentReference String Required	Your unique reference for this payment. Format: Maximum length 50 characters. This value should be unique in order to protect your customers against duplicate transactions. With a server side integration, if a payment reference is not supplied, the transaction will not be processed.
initiativeContext String Optional	Your fully qualified domain name associated with your Apple Pay Merchant Identity Certificate. The default is: window.location.hostname For example: initiativeContext ="web.judopay.com"
methodConfiguration Object Optional	This parameter contains the following fields: 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 Object Optional	Provides information about the specific transaction. Use this object to supply the information for recurring payments. For more information, see Apple Pay™ Recurring Payments . See here for more details on the parameter fields.
options Object Optional	Enables you to set options to control the behaviour of the user agent. See here for more details on the parameter fields.
onShippingAddressChange Method Optional	Dispatched when the user changes their shipping address. See here for more details on this parameter.
onShippingOptionChange Method Optional	Dispatched when the user changes a shipping option. See here for more details on this parameter.
delayedAuthorisation Boolean Optional	For preAuths only. Set to true to authenticate a card holder with 3D secure, without performing payment authorisation. When set to true, the 3D Secure authentication status is returned in the response. The payment authorisation is carried out at the stage when you are ready to collect the amount from the customer. The default value = false
initialRecurringPayment Boolean Optional	Indicates if this initial payment is part of a recurring payment. For more information, see Apple Pay™ Recurring Payments .

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.
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.
The consumer should be redirected to an Error Page.

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.

Apple Pay™ Recurring Payments

Make sure you are using:

Web SDK Version 0.1.0 (or higher)

Integration via Web Payments is not currently supported.

Judopay supports Merchant Initiated Transactions (MIT)s for Wallet Customer Initiated Transactions (CIT)s.

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.

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

Recurring 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™ recurring payment token for future Merchant Initiated Transactions (MIT):

Set recurringPaymentRequest on the ApplePayPaymentConfiguration passed to invokePaymentWithApplePay / invokePreAuthWithApplePay

Shapes follow Apple Pay™s ApplePayRecurringPaymentRequest The SDK injects the tokenNotificationURL:

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 a 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.

For a full description on all the object properties in the Apple Pay™ recurring payments flow, see the Apple Pay™ Documentation.

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):

Set deferredPaymentRequest on the ApplePayPaymentConfiguration passed to invokePaymentWithApplePay / invokePreAuthWithApplePay

Shapes follow Apple Pay™s ApplePayDeferredPaymentRequest The SDK injects the tokenNotificationURL:

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 a 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.

For a full description on all the object properties in the Apple Pay™ recurring payments flow, see the Apple Pay™ Documentation.

Domain Registration

To get your valid Apple™ domain registration:

Create the following (well-known) folder on your web server's root domain directory: ./well-known

In the folder, create a web server identity file: apple-developer-merchantid-domain-association

Download the following contents to the web server identity file:

apple-developer-merchantid-domain-association.txt

Make sure you remove the .txt file extension.

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.

Apple will use this location to check the validity of your domain. It is important this is externally accessible.

5. Notify Judopay of the following details:

JudoID(s)

List your JudoIDs you wish enabled for Apple Pay™

Domain(s)

List your domain URLs you wish enabled for Apple Pay™

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™

For more information see, Testing your Wallet Payment Integration.