Apple Pay: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
m (TLS1.1->1.2)
No edit summary
 
(4 intermediate revisions by 2 users not shown)
Line 57: Line 57:
<ol start="2" style="list-style-type: decimal;">
<ol start="2" style="list-style-type: decimal;">
<li><p>Add the <code>apple-pay-button</code> element (for example, <code>&lt;div id="apple-pay-button"&gt;&lt;/div&gt;</code>) to your checkout page, [https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_css and use the CSS included in the button script to display it].</p></li>
<li><p>Add the <code>apple-pay-button</code> element (for example, <code>&lt;div id="apple-pay-button"&gt;&lt;/div&gt;</code>) to your checkout page, [https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_css and use the CSS included in the button script to display it].</p></li>
<li><p>Start a new ApplePaySession when the checkout page loads:</p></li></ol>
<li><p>Start a new ApplePaySession when the checkout page loads:</p>
 
<syntaxhighlight lang="javascript">  const request = {
<syntaxhighlight lang="javascript">  const request = {
     countryCode: 'US',
     countryCode: 'US',
Line 69: Line 68:


   // add an isSessionCanceled boolean to easily be able to cancel the session if your user abandons the in-progress payment process
   // add an isSessionCanceled boolean to easily be able to cancel the session if your user abandons the in-progress payment process
   var isSessionCanceled = false;</syntaxhighlight>
   var isSessionCanceled = false;</syntaxhighlight></li>
<ol start="4" style="list-style-type: decimal;">
  <li>
<li><p>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:</p>
    <p>Make sure to only display the Apple Pay button to users who can use it, by have your webshop’s checkout pages do
<ol style="list-style-type: decimal;">
      the following when they load:</p>
<li>Call [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778027-canmakepayments the <code>applePaySession.canMakePayments</code> method], passing it your Barion shop’s public ID.</li></ol>
    <p>Call [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778027-canmakepayments
        the <code>applePaySession.canMakePayments</code> method], passing it your Barion shop’s public ID.</p>


<p>If Apple can verify your Barion shop as a registered Apple Pay provider, the method checks the following:</p>
    <p>If Apple can verify your Barion shop as a registered Apple Pay provider, the method checks the following:</p>
</li></ol>
    <ul>
<ul>
      <li>that your customer's device is capable of using Apple Pay</li>
  <li>that your customer's device is capable of using Apple Pay</li>
      <li>that Apple Pay is enabled on your customer's device, and</li>
  <li>that Apple Pay is enabled on your customer's device, and</li>
      <li>that the customer has the details of at least one active and web payment-eligible bank card stored in their Apple
  <li>that the customer has the details of at least one active and web payment-eligible bank card stored in their Apple Pay wallet.</li>
        Pay wallet.</li>
</ul>
    </ul>
<ol start="4" style="list-style-type: decimal;">
  </li>
<li><ol start="2" style="list-style-type: decimal;">
  <li>Handle [https://developer.apple.com/documentation/apple_pay_on_the_web/paymentcredentialstatus the
<li>Handle [https://developer.apple.com/documentation/apple_pay_on_the_web/paymentcredentialstatus the <code>PaymentCredentialStatus</code> object] that the method returns to make a decision about displaying the Apple Pay button.</li></ol>
        <code>PaymentCredentialStatus</code> object] that the method returns to make a decision about displaying the
</li></ol>
        Apple Pay button.
  </li>
</ol>
=== Handling payments ===
=== Handling payments ===


Line 91: Line 93:


<ol style="list-style-type: decimal;">
<ol style="list-style-type: decimal;">
<li><p>Set up an event handler for [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778021-onvalidatemerchant <code>ApplePaySession.onvalidatemerchant</code>] that calls [[ApplePay-ValidateSession|the ValidateSession Barion API endpoint]], passing it the <code>onvalidatemerchant</code> event’s <code>ValidationUrl</code> attribute.</p>
<li><p>Set up an event handler for [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778021-onvalidatemerchant <code>ApplePaySession.onvalidatemerchant</code>] that notifies your site's back-end, and passes it the event response.</p><blockquote>Don't call the ValidateSession Barion API endpoint directly from the browser, as this could expose your Barion shop's POSKey.</blockquote></li>
<li><p>Have your site's back-end call [[ApplePay-ValidateSession|the ValidateSession Barion API endpoint]], passing it the <code>onvalidatemerchant</code> event’s <code>ValidationUrl</code> attribute.</p>
<syntaxhighlight lang="javascript">async function validateApplePaySession(POSKey, SessionRequestUrl, ShopUrl) {
<syntaxhighlight lang="javascript">async function validateApplePaySession(POSKey, SessionRequestUrl, ShopUrl) {
   const url = "https://api.test.barion.com/v2/ApplePay/ValidateSession";
   const url = "https://api.test.barion.com/v2/ApplePay/ValidateSession";
Line 120: Line 123:
}
}


applePaySession.onvalidatemerchant = function (event) {
applePaySession.onvalidatemerchant = async function (event) {
   validateApplePaySession(POSKey, event.validationURL, ShopUrl);
   const validationResult = await validateApplePaySession(POSKey, event.validationURL, ShopUrl);
 
  applePaySession.completeMerchantValidation(validationResult.ApplePaySessionResponse);
};</syntaxhighlight>
};</syntaxhighlight>
<blockquote><p>This event is triggered when the Apple Pay payment sheet is displayed to the customer.</p></blockquote></li>
<blockquote><p>This event is triggered when the Apple Pay payment sheet is displayed to the customer.</p></blockquote></li>
<li><p>Set up an event handler for [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778020-onpaymentauthorized <code>ApplePaySession.onpaymentauthorized</code>] that calls the [[ApplePay-StartPaymentWithAppleToken|StartPaymentWithAppleToken Barion API endpoint]], passing it the event’s following attributes:</p>
<li><p>Set up an event handler for [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778020-onpaymentauthorized <code>ApplePaySession.onpaymentauthorized</code>]</p><blockquote>Don't call the StartPaymentWithAppleToken Barion API endpoint directly from the browser, as this could expose your Barion shop's POSKey.</blockquote></li>
<li>that calls the [[ApplePay-StartPaymentWithAppleToken|StartPaymentWithAppleToken Barion API endpoint]], passing it the event’s following attributes:</p>
<ul>
<ul>
<li>token</li>
<li>token</li>
<li>shippingContact</li>
<li>shippingContact</li>
<li>billingContact</li></ul>
<li>billingContact</li></ul>
</li></ol>
<blockquote>Note that <code>StartPaymentWithAppleToken</code> is actually a specialized version of [[Payment-Start-v2|the payment/start API endpoint]], and so will also require all the usual parameters that you’d pass to that endpoint.
<blockquote>Note that <code>StartPaymentWithAppleToken</code> is actually a specialized version of [[Payment-Start-v2|the payment/start API endpoint]], and so will also require all the usual parameters that you’d pass to that endpoint.
</blockquote>
</blockquote>
Line 188: Line 192:


<blockquote>This event is triggered when the customer has authorized the Apple Pay payment using their Touch ID or Face ID.</blockquote>
<blockquote>This event is triggered when the customer has authorized the Apple Pay payment using their Touch ID or Face ID.</blockquote>
<ol start="3" style="list-style-type: decimal;">
</li>
<li><p>Set up an event handler for <code>oncancel</code> to implement your business logic for when the user abandons the Apple Pay payment.</p>
<li><p>Set up an event handler for <code>oncancel</code> to implement your business logic for when the user abandons the Apple Pay payment.</p>
<p>Make sure that your event handler indicates that the session is canceled so the ApplePaySession’s <code>completePayment</code> method doesn’t get executed.</p>
<p>Make sure that your event handler indicates that the session is canceled so the ApplePaySession’s <code>completePayment</code> method doesn’t get executed.</p>
Line 196: Line 200:
     isSessionCanceled = true;
     isSessionCanceled = true;
   };</syntaxhighlight></li>
   };</syntaxhighlight></li>
<li><p>Call [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778001-begin ApplePaySession.begin] to kick off the payment process.</p></li></ol>
<li><p>Call [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778001-begin ApplePaySession.begin] to kick off the payment process.</p>
<syntaxhighlight lang="javascript">  applePaySession.begin();</syntaxhighlight>
<blockquote>This starts the merchant validation process that results in <code>ApplePaySession.onvalidatemerchant</code> being triggered.</blockquote></li></ol>


<syntaxhighlight lang="javascript">  applePaySession.begin();</syntaxhighlight>
<blockquote>This starts the merchant validation process that results in <code>ApplePaySession.onvalidatemerchant</code> being triggered.</blockquote>
=== Testing your implementation ===
=== Testing your implementation ===



Latest revision as of 11:11, 12 September 2024

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

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

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

  2. 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;
  3. 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.
  4. 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