Apple Pay on the Web

Converge can integrate with Apple^® Pay on the Web to process payments. Apple Pay on the Web is available through the following Converge integration options:

Converge Hosted Payments Page
Checkout.js
XML API

Converge allows Hosted Payment Page (HPP), and Checkout.js merchants with Apple Pay as a payment method to add surcharge fees to eligible credit cards.

Hosted Payments Pages

Users can toggle Apple Pay support on or off using the HPP customization screen. Apple Pay will display automatically at checkout while it is enabled. For more details on how to enable Apple Pay, refer to Set Up Apple Pay on the WebLink opens new window.

note

Make sure to remove HTTP Referrers from Converge System Setup Support Settings, before enabling Apple Pay on the Web on Converge Payment Extensions Settings. The HTTP referrers can be added back after Apple pay on the Web is enabled on Converge.

Checkout.JS

Requirements

Make sure Apple Pay on the Web is enabled on your eCommerce Terminal.

Merchant setup

Create a folder named ‘.well-known’ in your domain. Then create two validation files within the folder:

‘apple-developer-merchantid-domain-association.txt’ (with .txt extension)
‘apple-developer-merchantid-domain-association’ (without extension)

For example, the path would be: https://yourdomain/.well-known/apple-developer-merchantid-domain-association.txt.

Host the validation files on your server.

Go to the validation file path.
Refer to the following paths for demo and production validation files:
-Demo validation file: https://demo.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtLink opens new window
-Production validation file: https://api.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtLink opens new window

Highlight and copy the entire content and paste it to the two files (with and without txt extension) created under ‘.well-known’ folder.

Verify if the merchant domain is authorized using the Converge System Setup Support Settings.

note

Make sure to set your contact information under the Converge Contact Information Settings to avoid failure.

Authorized Referrers

Merchant domain that hosts the Apple Pay button should be a part of Authorized Referrers to use Apple Pay on the Web. However, If the Merchant domain is not a part of the Authorized Referrers, then complete the following steps:

a. Login to Converge and go to Settings.
b. On the Payment Extensions, disable Apple Pay on the Web (if enabled).
c. Go to System Setup Support Settings and add Authorized Referrers.
d. Enable Apple Pay on the Web. Once successfully enabled, you can remove Authorized Referrers.

To use Apple Pay on the Web with Checkout.js, you must take the following steps:

Include Converge Checkout.js and render an Apple Pay on the Web button on your page.
Prepare a session token.
Provide callback as shown in the example code below.

Example Checkout.js Integration

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    <title>Embedded Payment Demo</title>
    <style>
      .apple-pay-button {
      -webkit-appearance: -apple-pay-button;
      -apple-pay-button-type: buy;
      display: inline-block;
      width: 100px;
      min-height: 30px;
      border: 1px solid black;
      background-image: -webkit-named-image(apple-pay-logo-black);
      background-size: 100% calc(60% + 2px);
      background-repeat: no-repeat;
      background-color: white;
      background-position: 50% 50%;
      border-radius: 5px;
      padding: 0px;
      margin: 5px auto;
      transition: background-color .15s;
      cursor: pointer;
      }
    </style>
    <script src="https://api.demo.convergepay.com/hosted-payments/Checkout.js"></script>
    <script>
      var callback = {
        onError: function (error) {
                        showResult("error", error);
        },
        onDeclined: function (response) {
                        showResult("declined", JSON.stringify(response));
        },
        onApproval: function (response) {
                        showResult("approval", JSON.stringify(response));
        },
        onCancelled: function () {
                        showResult("cancelled", "");
        }
      };

      function initiateEwallets () {
        var paymentData = {
                        ssl_txn_auth_token: document.getElementById('token').value
                                        };
        ConvergeEmbeddedPayment.initApplePay('applepay-button', paymentData, callback);
        return false;
      }

      function showResult (status, msg, hash) {
        document.getElementById('txn_status').innerHTML = "<b>" + status + "</b>";
                        document.getElementById('txn_response').innerHTML = msg + "</b>";
                        document.getElementById('txn_hash').innerHTML = hash;
      }

      function confirmSurcharge() {
        
            var agree = $("#agreeToSurcharge").is(":checked");
            if(agree){
                var callback = {
                    onError: function (error) {
                        showResult("error", error);
                    },
                    onDeclined: function (response) {
                        showResult("declined", JSON.stringify(response));
                    },
                    onApproval: function (response) {
                        showResult("approval", JSON.stringify(response));
                    },
                    onCancelled: function () {
                        showResult("cancelled", "");
                    },
                    onSurcharge: function(response) {
                        showResult("Surchange Approval", JSON.stringify(response));
                    }
                };
                ConvergeEmbeddedPayment.creditSurchargeDecision(true, callback);
            }
        }
    </script>

  </head>
  <body>
    <form>
      Transaction Token: <input type="text" id="token" name="token"> <br>
      <button onclick="return initiateEwallets();">Initiate Checkout.js</button> <br>
    </form>
    <br>
    <div id="sc_button" style="display:none">
            <input type="checkbox" id="agreeToSurcharge" name="agreeToSurcharge" value="agreeToSurcharge">
            <label for="agreeToSurcharge">Agree to Surcharge ?</label>
            </p>
            <button id="scbutton" onclick="return confirmSurcharge();">Confirm surchange</button>
    </div>
    <br>
    <div id="applepay-button" class="apple-pay-button"></div>
    <br>
    Transaction Status:<div id="txn_status"></div>
    <br>
    Transaction Response:<div id="txn_response"></div>
    <br>
    Transaction Hash Value:<div id="txn_hash"></div>
  </body>

</html>

XML API

XML API users must meet Apple Pay standards and requirements before integrating their website with Apple Pay.

Apple Pay Website Requirements

To use Apple Pay with XML API, your website must adhere to the following standards:

Your website must comply with the Apple Pay guidelinesLink opens new window, Apple Pay Identity GuidelinesLink opens new window, and Apple Pay on the Web Human Interface GuidelinesLink opens new window
All pages that include Apple Pay must be served over HTTPSLink opens new window
Merchant domains must have a valid SSL certificate

Visit the Apple’s Developer DocumentationLink opens new window for Apple Pay to see the full set of requirements and best practices.

Merchant setup

Create a folder named ‘.well-known’ in your domain. Then create two validation files within the folder:

‘apple-developer-merchantid-domain-association.txt’ (with .txt extension)
‘apple-developer-merchantid-domain-association’ (without extension)

For example, the path would be: https://yourdomain/.well-known/apple-developer-merchantid-domain-association.txt.

Host the validation files on your server.

Go to the validation file path.
Refer to the following paths for demo and production validation files:
-Demo validation file: https://demo.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtLink opens new window
-Production validation file: https://api.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtLink opens new window
Highlight and copy the entire content and paste it to the two files (with and without txt extension) created under ‘.well-known’ folder.

Verify if the merchant domain is authorized using the Converge System Setup Support Settings.

note

Make sure to set your contact information under the Converge Contact Information Settings to avoid failure.

Merchant domain that hosts the Apple Pay button should be a part of authorized referrers to use Apple Pay on the Web. However,if the merchant domain is not a part of the authorized referrers, then complete the following steps:

Make sure Apple Pay on the Web is enabled on your eCommerce Terminal.

Apple Pay Button Creation for XML API

XML API users must include an Apple Pay button in their website. You can find steps for creating and styling buttons in the Apple Pay Developer DocumentationLink opens new window.

Field Reference

Field Name	Description
`ssl_merchant_id`	Your Merchant ID
`ssl_user_id`	Your API User Name
`ssl_pin_id`	Your PIN
`ssl_amount`	Transaction Amount
`ssl_transaction_type`	Transaction Type
`ewalletaction`	Action to perform with e-wallet
`applepayUrl`	URL for Apple Pay processing
`applepayDomain`	Domain registered with Apple Pay
`ssl_transaction_source`	Source of transaction request
`ssl_applepay_web`	Apple Pay Payment Token
`ssl_applepay_billing`	Billing address for Apple Pay
`ssl_applepay_shipping`	Shipping address for Apple Pay

Sample Codes

important

In all of these examples, you will have to change the data values, such as my_merchant_id, my_user_id, my_pin, my_domain, and transaction data to match your Converge account and meet the needs of your website.
Code samples provided are for demonstration only and should not be used for live transactions. All sensitive merchant data, including transaction amounts and your Converge credentials, should be placed in server side code.

Cert/Demo applepayUrl: https://apple-pay-gateway-cert.apple.com/paymentservices/startSession
Production applepayUrl: https://apple-pay-gateway.apple.com/paymentservices/startSession

Get Session Request:

xmldata=
<txn>
  <ssl_merchant_ID>my_merchant_id</ssl_merchant_ID>
  <ssl_user_id>my_user_id</ssl_user_id>
  <ssl_pin>my_pin</ssl_pin>
  <ssl_transaction_type>EWALLETINQUIRY</ssl_transaction_type>
  <ewalletaction>applepaySession</ewalletaction>
  <applepayUrl>https://apple-pay-gateway-cert.apple.com/paymentservices/startSession</applepayUrl>
  <applepayDomain>my_domain</applepayDomain>
</txn>

Apple Pay Session Response:

<txn>
  <applepaySession>
      {"epochTimestamp":1557932006440,"expiresAt":1557935606440,"merchantSessionIdentifier":"SSHA0B20BE3B7E645EFB8EBAE91F81069C0_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24","nonce":"465a2042","merchantIdentifier":"2B61E0688F2FC23911AC584F4FEFA52AA675CA1C34A51658BCCC0ACE07450822","domainName":"ex.com","displayName":"Merchant Name","signature":"308006092a864886f70d0101...18ffdae3ecb000000000000"}
  </applepaySession>
</txn>

Merchant uses the ApplePay session and gets Apple Pay payment data and it sends it to Converge for decryption and transaction processing.

Apple Pay Transaction Request:

xmldata=
<txn>
  <ssl_merchant_ID>my_merchant_id</ssl_merchant_ID>
  <ssl_user_id>my_user_id</ssl_user_id>001044-dev
  <ssl_pin>my_pin</ssl_pin>
  <ssl_transaction_type>CCSALE</ssl_transaction_type>
  <ssl_transaction_source>X_HPP</ssl_transaction_source>
  <ssl_applepay_web>
    {"version":"EC_v1","data":"51ZPGwbuhhtfJ/839ksS6voUzAU34g/DWZaikfZ0velZQonWvcIuqQcKjLlobCiOG8RRN6bq5V9rF3hkhxU1GBem4LHtZ/+eYttjSA6YGNZjObCfNaFFJQdvRtBkmNNdMoiCE2FRotwjKJGgKTbGh46a3kFHUr/sFZeGdNue75CuICs58DTmfIhRSdKFq0yrc0Mb2bxDUHzIDnTvns4Pyu5Vbzjr8IAh9+DCms2oVJrvwwucjV3G6y8/ZG/gAB8lskw33IAlkKSsdoQ37zT2saRWCDt2ycwuIHz7/7Nd1oiWJ/sFO/aRePsK1kZn75sjOqsX4Ee1o9Y9bOElsOFI5fwAyUAX8yzSJSv5V+v0UOQRJaW50kAvA5u4A18oePMiTHnRwZaBeYzYKjPR","signature":"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","header":{"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEr5QHLJ2aSOI+xJC0UKluE8/PqjDHuCjUsEGfnkDKAtBMy/vqs/3tGvakoKKB5OMhP9qZPQ0Dy+lCFe0aSkTBFg==","publicKeyHash":"HtzEQzrtccElcDdut4iVHvyf1PiwiHCEo2yvFyuCtqE=","transactionId":"9230d92ffcb5ded6b25f6928652505155f33dff2b1837819a79122c890f66935"}}
  </ssl_applepay_web>
  <ssl_applepay_billing></ssl_applepay_billing>
  <ssl_applepay_shipping></ssl_applepay_shipping>
</txn>

Cash Advance

Apple Pay

Magento Guide

Apple Pay on the Web

Hosted Payments Pages

Checkout.JS

Requirements

Merchant setup

Authorized Referrers

Example Checkout.js Integration

XML API

Apple Pay Website Requirements

Merchant setup

Apple Pay Button Creation for XML API

Field Reference

Sample Codes