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 Webopen_in_newLink opens new window.
Checkout.JS
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).
Create two files with the name of ‘apple-developer-merchantid-domain-association’ where one with .txt extension and another one without extension under a folder named ‘.well-known’ in your domain. For example: https://yourdomain/.well-known/apple-developer-merchantid-domain-association.txt
Host the demo and production validation files to your server.
- Go to the validation file path.
Refer the following paths for demo and production validation files:
-Demo validation file: https://demo.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtopen_in_newLink opens new window
-Production validation file: https://api.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtopen_in_newLink 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.
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 guidelinesopen_in_newLink opens new window, Apple Pay Identity Guidelinesopen_in_newLink opens new window, and Apple Pay on the Web Human Interface Guidelinesopen_in_newLink opens new window
- All pages that include Apple Pay must be served over HTTPSopen_in_newLink opens new window
- Merchant domains must have a valid SSL certificate
Visit the Apple’s Developer Documentationopen_in_newLink opens new window for Apple Pay to see the full set of requirements and best practices.
Additional Requirements
- Merchant domains that will host Apple Pay button have to be registered with Apple as a part of Authorized Referrers before enabling Apple Pay on the web.
- Terminal should be Internet or Retail / Service Terminal with Omnicommerce option on
To use Apple Pay on the Web with XML API, you must take the following steps:
Create two files with the name of ‘apple-developer-merchantid-domain-association’ where one with .txt extension and another one without extension under a folder named ‘.well-known’ in your domain. For example: https://yourdomain/.well-known/apple-developer-merchantid-domain-association.txt
Host the demo and production validation files to your server.
- Go to the validation file path.
Refer the following paths for demo and production validation files:
-Demo validation file: https://demo.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtopen_in_newLink opens new window
-Production validation file: https://api.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txtopen_in_newLink opens new window - Highlight and copy the entire file 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 merchant contact information under the Converge Contact Information Settings to avoid failure.
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 Documentationopen_in_newLink 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
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>alpha.myvirtualmerchant.com</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>