Apple Pay

Apple Pay integration

Learn to offer the Apple Pay button as a payment option in your Barion shop when the customer uses a supported browser (typically Safari) on an eligible device.

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

• 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
  • the Barion shop complies with Apple’s acceptable use guidelines, including not selling prohibited products or services

  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:
  • they’re using an Apple Pay-compatible device
  • they’re viewing your webshop using a browser that supports Apple Pay
  • they’re located in a country or region where Apple Pay is available

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 content root 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 src="https://applepay.cdn-apple.com/jsapi/v1.1.0/apple-pay-sdk.js"></script>

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

2. Add the apple-pay-button element (for example, <div id="apple-pay-button"></div>) to your checkout page, and use the CSS included in the button script to display it.

3. Start a new ApplePaySession when the checkout page loads:

     const request = {
       countryCode: 'US',
       currencyCode: 'USD',
       supportedNetworks: ['visa', 'masterCard', 'amex', '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;

4. 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 [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778027-canmakepayments the applePaySession.canMakePayments method], passing it your Barion shop’s public ID.

   If Apple can verify your Barion shop as a registered Apple Pay provider, the method checks 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.
5. Handle [https://developer.apple.com/documentation/apple_pay_on_the_web/paymentcredentialstatus 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.

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

If you’re located in one of the countries or regions where the Apple Pay sandbox environment is available, use Apple’s Sandbox testing to try out your integration.

Related links

ValidateSession API endpoint

StartPaymentWithAppleToken API endpoint