Apple Pay

From Barion Documentation
Jump to navigation Jump to search

Apple Pay integration

Apple Pay is a wallet solution created by Apple for Apple customers. It is only accessible in the Apple ecosystem. You can use it with your iPhone, iWatch or with your desktop/laptop Macintosh computer. When it comes to Barion there are two different ways to use this payment option:

  • on the Barion Smart Gateway (called hosted mode)
  • in their webshop if they integrate the so-called integrated mode

The customer who wants to pay with Apple Pay Wallet must have an Apple device that supports authentication. This could be

  • an iPhone,
  • a modern MacBook with fingerprint authentication or
  • an older MacBook with a paired iPhone

Browser support

Apple Pay behaves differently depending on the customer's browser:

  • In Safari, and in any browser built on Apple's WebKit engine (Chrome, Firefox, or Edge on iOS), the button works natively, and the customer confirms the payment with Touch ID or Face ID.
  • In other desktop browsers that can't run Apple Pay directly (for example Chrome, Firefox, or Edge on Windows), Apple's SDK automatically shows a QR code that the customer scans with their iPhone's Camera app (requires iOS 18 or later) to complete the payment there.

Furthermore, the customer must fill out their home address and their contact information in their Apple Pay wallet as well. Without this, they won't be able to use their card in their Apple Wallet. This can be done even during the payment process.

This feature is listed as an available payment method on the shop's admin site

In case it is switched off the shop won't be able to display it as a funding source. This won't produce any error message, the Apple Pay option just won't be visible.

Hosted mode

This is the "out of the box" mode that is available on the Barion Smart Gateway. It works in every browser described in the Browser support section above — natively in Safari and other WebKit-based browsers, and via the QR code hand-off in other desktop browsers.

If the customer selects the Apple Pay accordion, the Apple Pay button will be visible.

Once the customer clicks the Pay button the Apple Pay screen is displayed. This screen is actually controlled by the device, we don't have any control over it.

On this screen, the customer may change the used credit card, the home address, or the e-mail address. These are all required to pay via Apple Pay. Once the customer approves the transaction everything continues as with a normal card would.

Integrated mode

In integrated mode (called processor mode in Apple documentation) the webshop owner puts the Apple Pay button in their webshop and does not need to redirect the customer to the Barion Smart Gateway. This feature requires custom development from the webshop owner. The shop has to implement the Apple Pay button (instead of just relying on our gateway). To do this, they have to read through this documentation.

The Apple Pay button can be displayed anywhere on the webshop. For example, on our demomerchant site is next to the Google Pay button.

This integration requires a developer and is beneficial for shops that want to provide their customer a faster payment experience (since there is no need to redirect them to our gateway).

To enable the button on the merchant's website the website has to be registered at Apple services. To help with this task we created a setting screen in our system. This setting page is available from the shop's setting page. (The one accessible by the owner)

On this page, the owner has to input all the domains that the shop is using for the Apple Pay button. In addition to this the owner also has to upload a domain verification file to its domain.

After payment

After the successful payment, the customer receives the usual confirmation letter, however, the bank card is clearly flagged, so the customer is aware that the payment was funded with a card from their Apple Wallet.

Warning: The card number displayed here is not the real card number. Apple creates a fake card number to protect the real card, so we are only aware of the fake number.

Troubleshooting domain association errors

Some common pitfalls with domain association files can be found below.

  • domain association file cannot be reached without authentication
  • response doesn’t contain “Content-Type” header with value “application/json”
  • merchant’s server only supports TLS 1.3 (Barion uses 1.2 for checking this file)
  • merchant has some form of bot/scraping protection enabled, which filters out requests that has a non-browser shaped or missing User-Agent header

Contact

George Maroufidis <[email protected]>

George Maroufidis |  Pay eCommerce EMEIA | OneBattersea Power Station, London, SW11 8BZ, United Kingdom | iPhone: +44 7591 916 527

Design

  • Apple Pay Marketing Guidelines
  • Human Interface Guidelines

Reference

  • Configuring the environment
  • Apple Pay on the web
  • PaymentToken
  • Sandbox

This article is about directly integrating the Apple Pay button in your webshop.

If you simply want to display Apple Pay as a payment option in the Barion Smart Gateway, no further configuration is necessary; pass "ApplePay" in the FundingSources array when preparing a payment.

The appeal of Apple Pay is that it requires only two actions from the customer: selecting the ‘Pay with Apple Pay’ button, and confirming the payment with Touch ID or Face ID.

Another advantage to your Barion shop’s payment workflow is that customers aren’t navigated away from your checkout page when using Apple Pay.

Prerequisites

IMPORTANT
You do not need to register an Apple Developer Account! Should you need an Apple Merchant Id, use the PublicId (guid) of your shop!
  • access to and being able to modify both your webshop’s front-end and back-end code
  • your webshop using HTTPS (having a TLS 1.2 or higher certificate installed) for all its pages that include the Apple Pay button
  • Barion Wallet with an approved Barion shop

    Note that Apple’s policies regarding acceptable products and services are more limiting than those of Barion.

    It may happen that even though Barion approves your Barion shop to sell a certain item, you will not be allowed to display the Apple Pay button as a payment option for customers to pay for that item.

  • an account in the Barion Wallet for each of the currencies that you’d like to accept using Apple Pay

Limitations

  • you can’t yet tokenize your customer’s card details when using the Apple Pay button, so recurring payments aren’t available
  • Barion currently only supports Apple Pay button on the web, and not on native iOS apps
  • regardless of the integration detailed here, the Apple Pay button will only be displayed to your customers if they comply with Apple’s requirements:

Steps

Setting up your Apple prerequisites

When using Barion’s Apple Pay API endpoints, Barion gives you an Apple developer account, and registers a Merchant ID, Payment Processing Certificate, and Merchant Identity Certificate for you as a subsidiary of Barion’s Apple Pay credentials.

Verify and register your webshop’s domain name or names:

  1. Log in to your Barion Wallet, and go to your Barion shop’s Shops>Actions>Settings screen.
  2. Click the “Manage Apple Pay settings”, and then “Download domain verification file” to save the verification file for your shop’s domain.
  3. Save the domain verification file that you downloaded in the /.well-known directory of all the sites that your specified domains use, making sure of the following:
    • the file should send the <mimeMap fileExtension="." mimeType="application/json" /> MIME data;
    • the file must be accessible externally, and not be password-protected, or behind a proxy or redirect;
    • the sites must be served over HTTPS.
  4. Enter all the domains that you’d like to use Apple Pay on (into whose root you’ve downloaded the domain verification file) in the text box provided, then click “Save”.

Configuring and displaying the Apple Pay button

  1. Load the button script into your checkout page by adding the following script tag inside the page head:

    <script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

    Always load the always-current 1.latest path instead of a pinned version, and keep the crossorigin attribute — it is required for the native <apple-pay-button> element and for the cross-browser behaviour (native in WebKit, QR code hand-off on other desktop browsers) to work correctly.

This script makes an ApplePaySession available to your site front-end, among other things.

  1. Add the apple-pay-button custom element (for example, <apple-pay-button id="apple-pay-button" buttonstyle="black" type="plain"></apple-pay-button>) to your checkout page. The official SDK renders this element natively — you no longer need to write your own CSS to display it.

    IMPORTANT
    The <apple-pay-button> element's size can't be set with ordinary CSS height/border-radius properties — its internal shadow-DOM content won't follow them. Use the dedicated CSS custom properties instead: --apple-pay-button-height and --apple-pay-button-border-radius.
    apple-pay-button {
      --apple-pay-button-height: 48px;
      --apple-pay-button-border-radius: 8px;
    }
  2. Start a new ApplePaySession when the checkout page loads:

      const request = {
        countryCode: 'US',
        currencyCode: 'USD',
        supportedNetworks: ['visa', 'masterCard', 'discover'],
        merchantCapabilities: ['supports3DS'],
        total: { label: 'Your Merchant Name', amount: '10.00' }
      }
      const applePlaySession = new ApplePaySession(3, request);
    
      // add an isSessionCanceled boolean to easily be able to cancel the session if your user abandons the in-progress payment process
      var isSessionCanceled = false;

The merchant may supply the shipping and billing contact information directly, or request it when starting the ApplePaySession by including the requiredShippingContactFields  and requiredBillingContactFields properties in the payment request. More about the Apple Pay payment request here.

  1. Make sure to only display the Apple Pay button to users who can use it, by have your webshop’s checkout pages do the following when they load:

    Call ApplePaySession.canMakePayments() to check, in a single simple boolean call, whether Apple Pay is available at all on the customer's device/browser — this is the method needed to decide whether to show the button.

    If you additionally need detailed status about a specific merchant and the customer's stored cards, use applePaySession.applePayCapabilities(), passing it your Barion shop’s public Id as the merchantId parameter.

    applePaySession.canMakePaymentsWithActiveCard is deprecated by Apple — use applePayCapabilities instead for that detailed check.

    If Apple can verify your Barion shop as a registered Apple Pay provider, the detailed check reports the following:

    • that your customer's device is capable of using Apple Pay
    • that Apple Pay is enabled on your customer's device, and
    • that the customer has the details of at least one active and web payment-eligible bank card stored in their Apple Pay wallet.
  2. Handle the PaymentCredentialStatus object that the method returns to make a decision about displaying the Apple Pay button.


Handling payments

Set up your webshop to perform these steps each time a user selects the Apple Pay button.

IMPORTANT
The <apple-pay-button> element does not dispatch a standard bubbling DOM click event, so addEventListener / jQuery .on('click', ...) (whether bound to the element or to a container around it) will not fire. Bind your click handler directly to the element's onclick property instead.
document.getElementById('apple-pay-button').onclick = function (event) {
    // start your ApplePaySession here
};
  1. Set up an event handler for ApplePaySession.onvalidatemerchant that notifies your site's back-end, and passes it the event response.

    Don't call the ValidateSession Barion API endpoint directly from the browser, as this could expose your Barion shop's POSKey.

  2. Have your site's back-end call the ValidateSession Barion API endpoint, passing it the onvalidatemerchant event’s ValidationUrl attribute.

    async function validateApplePaySession(POSKey, SessionRequestUrl, ShopUrl) {
      const url = "https://api.test.barion.com/v2/ApplePay/ValidateSession";
      const data = {
        POSKey,
        SessionRequestUrl,
        ShopUrl,
      };
    
      try {
        const response = await fetch(url, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify(data),
        });
    
        if (!response.ok) {
          throw new Error(`Error: ${response.status} ${response.statusText}`);
        }
    
        const result = await response.json();
        return result;
      } catch (error) {
        // handle the error according to your business logic
      }
    }
    
    applePaySession.onvalidatemerchant = async function (event) {
      const validationResult = await validateApplePaySession(POSKey, event.validationURL, ShopUrl);
      
      applePaySession.completeMerchantValidation(validationResult.ApplePaySessionResponse);
    };

    This event is triggered when the Apple Pay payment sheet is displayed to the customer.

  3. Set up an event handler for ApplePaySession.onpaymentauthorized

    Don't call the StartPaymentWithAppleToken Barion API endpoint directly from the browser, as this could expose your Barion shop's POSKey.

  4. that calls the StartPaymentWithAppleToken Barion API endpoint, passing it the event’s following attributes:

    • token
    • shippingContact
    • billingContact

    Note that StartPaymentWithAppleToken is actually a specialized version of the payment/start API endpoint, and so will also require all the usual parameters that you’d pass to that endpoint.

    async function startApplePayPayment(
      POSKey,
      ShippingContact,
      BillingContact,
      Token,
      /** include other required and optional Payment/Start params */
      PaymentStartProperties
    ) {
      const url =
        "https://api.test.barion.com/v2/ApplePay/StartPaymentWithAppleToken";
      const data = {
        POSKey,
        ShippingContact,
        BillingContact,
        Token,
        ...PaymentStartProperties,
      };
    
      try {
        const response = await fetch(url, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify(data),
        });
    
        if (!response.ok) {
          throw new Error(`Error: ${response.status} ${response.statusText}`);
        }
    
        const result = await response.json();
        return result;
      } catch (error) {
        // handle the error according to your business logic
      }
    }
    
    const PaymentStartProperties = {
      PaymentType: "Immediate",
    };
    
    applePaySession.onpaymentauthorized = function (event) {
      startApplePayPayment(
        POSKey,
        event.paymentInfo.shippingContent,
        event.paymentInfo.billingContact,
        event.paymentInfo.Token,
        PaymentStartProperties
      );
    };

    This event is triggered when the customer has authorized the Apple Pay payment using their Touch ID or Face ID.

  5. Set up an event handler for oncancel to implement your business logic for when the user abandons the Apple Pay payment.

    Make sure that your event handler indicates that the session is canceled so the ApplePaySession’s completePayment method doesn’t get executed.

      applePaySession.oncancel = function (event) {
        // your oncancel business logic
    
        isSessionCanceled = true;
      };
  6. Call ApplePaySession.begin to kick off the payment process.

      applePaySession.begin();

    This starts the merchant validation process that results in ApplePaySession.onvalidatemerchant being triggered.

Testing your implementation

The following steps are needed in order to test your implementation:

  1. request access by sending an email to [email protected]!
  2. include an email address, that has no Apple Id yet
  3. we will register & connect it to our test account
  4. after that, you will be able to use Apple's test cards

To test the new cross-browser QR code hand-off (for customers on desktop non-Safari browsers), you need an iPhone running iOS 18 or later — this is a separate, newer requirement that applies only to this specific feature.

macOS is not enough to use Apple Pay. To use Apple Pay natively on macOS, you should configure the Handoff function on your devices. This Handoff requirement applies to Safari on macOS. Non-Safari desktop browsers (including Chrome or Firefox on macOS) don't need Handoff configured at all — they use the QR code hand-off flow instead.

Related links

ValidateSession API endpoint

StartPaymentWithAppleToken API endpoint