Apple Pay: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
(44 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{PageTitle|title=Apple Pay integration}}
{{PageTitle|title=Apple Pay integration}}
__NOTOC__
{{TableOfContents}}
Apple Pay™ is a payment option for the customer. Apple securely stores the customer's card information and hands it over to the merchant for processing.
{{NotificationBox|title=NOTE|text=We currently only support Apple Pay for the web, native iPhone app support is coming soon.|color=#1993c7}}
{{NotificationBox|title=NOTE|text=We currently only support Apple Pay for the web, native iPhone app support is coming soon.|color=#1993c7}}


== Introduction ==
== Implementation modes ==
Apple Pay can be emebedded two ways into your payment flow. In the first case, it will be displayed on Barion Smart Gateway, which needs no further development on your side, however you should request it from Customer Care [https://secure.barion.com/Remark/Create through the ticketing]. The second option is to display the Apple Pay button on your site ("integrated mode"), however this needs configuration and development on your side. This page will discuss the latter.
Apple Pay can be emebedded two ways into your payment flow. In the first case, it will be displayed on Barion Smart Gateway ("Hosted Gateway"), which needs no further configuration and/or development on your side. The second option is to display the Apple Pay button on your site ("integrated mode"), however this needs configuration and development on your side. This page will discuss the latter.
* Barion Smart Gateway Apple Pay demo: https://demomerchant.shop/en/DemoClub/Pay (click the Pay button)
* Apple Pay Hosted Gateway demo: https://test.demomerchant.shop/en/DemoClub/Pay (click the Pay button)
* Apple Pay integrated mode demo: https://demomerchant.shop/en/DemoGame/Pay
* Apple Pay integrated mode demo: https://test.demomerchant.shop/en/DemoGame/Pay
 
== Prerequisites ==
{{NotificationBox|title=IMPORTANT|text=To integrate this feature you have to develop the integration yourself! You need to understand Javascript code and it is also required to modify your webshop's server code!|color=#FF7A3D}}
* you must have a Barion wallet
* the beforementioned Barion wallet must have and approved shop
* for every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be an USD account created in your wallet.
* all the example codes assume the availability of jQuery


== Limitations ==
== Limitations ==
=== Technical ===
Using Apple Pay as a token payment is currently not possible.
Using Apple Pay as a token payment is currently not possible.


Apple Pay will be visible to shoppers fulfilling the following criteria:
=== Shopper ===
Apple Pay will only be visible to shoppers fulfilling the following criteria:
* Use an [https://support.apple.com/en-us/HT208531 Apple Pay-compatible device]
* Use an [https://support.apple.com/en-us/HT208531 Apple Pay-compatible device]
* Use [https://support.apple.com/en-us/HT208531#notes Safari]
* Use [https://support.apple.com/en-us/HT208531#notes Safari]
Line 17: Line 27:
* Have an [https://support.apple.com/guide/iphone/set-up-apple-pay-iph9b7f53382/ios existing card added to their Apple Pay wallet]
* Have an [https://support.apple.com/guide/iphone/set-up-apple-pay-iph9b7f53382/ios existing card added to their Apple Pay wallet]


Moreover the shop must not provide [https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/ prohibited items by Apple]
=== Shop ===
* Your shop must not sell [https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/ prohibited items by Apple]
* Your site must use https!


== Prerequisits ==
==Payment Process==
{{NotificationBox|title=IMPORTANT|text=To integrate this feature you have to develop the integration yourself! You need to understand Javascript code and it is also required to modify your webshop's server code!|color=#FF7A3D}}
# The customer clicks the Apple Pay button.
* you must have a Barion wallet
# Apple Pay session has to be created using the library provided by Apple as discussed [[#Create an Apple Pay session|here]].
* the beforementioned Barion wallet must have and approved shop
# The JS code receives a session data
* For every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be an USD account created in your wallet.
# The JS code sends this information to the server side of the merchant
* all the example codes assume the availability of jQuery
# The server side gathers the information necessary to call the [[ApplePay-ValidateSession|/v2/ApplePay/ValidateSession]] endpoint.
# Apple Pay screen is displayed, where the customer can select the card, shipping address and contact details.
# The JS code receives the encrypted card information.
# The JS code sends the encrypted information to the sever side of the merchant
# The server side gathers the information needed to call the [[ApplePay-StartPaymentWithAppleToken|/v2/ApplePay/StartPaymentWithAppleToken]] endpoint.
# The Barion API handles the request, decrypts the packages and charges the card. The result of the payment is sent back to the caller.
# The merchant's server communicates the result to the client side and the webshop renders the result of the payment.


==  Configuration ==
==  Configuration ==
# Domain verification file
=== Domain verification file===
#: First head over to secure.barion.com, and under [https://secure.barion.com/Shop Manage My Shops] page select the appropriate one, and from the dropdown, click on settings. At the bottom click the Manage Apple Pay settings blue button under the Apple Pay Settings section. On the next page  Click on the Download domain verification file button, which will download a domain association file. You should place this file at the content root of all of your sites, you're about to use apple pay in integrated mode.
First head over to secure.barion.com, and under [https://secure.barion.com/Shop Manage My Shops] page select the appropriate one, and from the dropdown, click on settings. At the bottom click the Manage Apple Pay settings blue button under the Apple Pay Settings section. On the next page  Click on the Download domain verification file button, which will download a domain association file. You should place this file at the content root of all of your sites, you're about to use apple pay in integrated mode.
#: The file must:
The file must:
#:* Have Content-Type: text/plain in the header.
* mimemap for extension "." should be set to "application/json", for eg.:
#:* Be externally accessible.
*: <syntaxhighlight lang="xml"><mimeMap fileExtension="." mimeType="application/json" /></syntaxhighlight>
#:* Not be password protected.
* be externally accessible.
#:* The file cannot be behind a proxy or redirect.
* not be password protected.
# Configure Domains
* the file cannot be behind a proxy or redirect.
#: On the exact same page you've downloaded the domain association file, enter all the domains (one in each line, without https:// or https://) you're intending to use Apple Pay.
* your site must use https.
# Request Apple Pay to be enabled
 
#: Head over to the Customer Center, and [https://secure.barion.com/Remark/Create request Apple Pay to be enabled for your shop].
===Configure Domains===
On the exact same page you've downloaded the domain association file, enter all the domains (one in each line, without https:// or https://) you're intending to use Apple Pay.


== Development ==
== Development ==
Line 46: Line 65:
Add the Apple Pay button to your checkout page as discussed [https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_javascript here]
Add the Apple Pay button to your checkout page as discussed [https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_javascript here]
===Create an Apple Pay session===
===Create an Apple Pay session===
When the user taps the Apple Pay button, provide a payment request and create the [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession session] as discussed [https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/creating_an_apple_pay_session here]
When the user taps the Apple Pay button, provide a payment request and create the [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession session] as discussed [https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/creating_an_apple_pay_session here]. Create a variable which will store, if the Apple Pay UI is dismissed (isSessionCanceled).


===Subscribe to the <code>[https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778021-onvalidatemerchant onvalidatemerchant]</code> event===
===Subscribe to the <code>[https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778021-onvalidatemerchant onvalidatemerchant]</code> event===
Call your backend, which will in turn call the Barion Api [[ApplePay-ValidateSession|ValidateSession]] endpoint in the event handler with the provided url as the payload:
Call your backend, which will in turn call the Barion Api [[ApplePay-ValidateSession|ValidateSession]] endpoint in the event handler with the provided url as the payload, if the payment ui is not dismissed meanwhile:
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
appleSession.onvalidatemerchant = function (event) {
appleSession.onvalidatemerchant = function (event) {
Line 63: Line 82:
success: function (response, status, xhr) {
success: function (response, status, xhr) {
const merchantSession = JSON.parse(response.ApplePaySessionResponse);
const merchantSession = JSON.parse(response.ApplePaySessionResponse);
appleSession.completeMerchantValidation(merchantSession);
if(!isSessionCanceled) {
appleSession.completeMerchantValidation(merchantSession);
}
},
},
error: function (xhr, status, error) {
error: function (xhr, status, error) {
Line 98: Line 119:
}
}
});
});
};
</syntaxhighlight>
===Subscribe to the <code>[https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778029-oncancel oncancel]</code> event===
This method gets called every time the Apple Pay UI is dismissed. You should implement your needs accordingly (for eg. re-enable pay button). Furthermore indicate that the session was canceled, so the completePayment won't be executed.
<syntaxhighlight lang="javascript">
appleSession.onpaymentauthorized = function (event) {
          // TODO: enable Apple Pay button
           
            isSessionCanceled = true;
};
};
</syntaxhighlight>
</syntaxhighlight>
Line 111: Line 143:
   total: { label: 'Your Merchant Name', amount: '1000.00' },
   total: { label: 'Your Merchant Name', amount: '1000.00' },
};
};
var isSessionCanceled = false;
var appleSession = new ApplePaySession(3, request);
var appleSession = new ApplePaySession(3, request);
appleSession.onvalidatemerchant = function (event) {...}
appleSession.onvalidatemerchant = function (event) {...}
appleSession.onpaymentauthorized = function (event) {...}
appleSession.onpaymentauthorized = function (event) {...}
applePaySession.begin();
appleSession.begin();
</syntaxhighlight>
</syntaxhighlight>


Line 122: Line 156:
** [[ApplePay-StartPaymentWithAppleToken|/v2/ApplePay/StartPaymentWithAppleToken]]
** [[ApplePay-StartPaymentWithAppleToken|/v2/ApplePay/StartPaymentWithAppleToken]]
* Apple
* Apple
** [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession | ApplePaySession interface]
** [https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession ApplePaySession interface]

Revision as of 10:45, 14 December 2021

Apple Pay integration

Apple Pay™ is a payment option for the customer. Apple securely stores the customer's card information and hands it over to the merchant for processing.

NOTE
We currently only support Apple Pay for the web, native iPhone app support is coming soon.

Implementation modes

Apple Pay can be emebedded two ways into your payment flow. In the first case, it will be displayed on Barion Smart Gateway ("Hosted Gateway"), which needs no further configuration and/or development on your side. The second option is to display the Apple Pay button on your site ("integrated mode"), however this needs configuration and development on your side. This page will discuss the latter.

Prerequisites

IMPORTANT
To integrate this feature you have to develop the integration yourself! You need to understand Javascript code and it is also required to modify your webshop's server code!
  • you must have a Barion wallet
  • the beforementioned Barion wallet must have and approved shop
  • for every currency you plan to conduct payments in you have to make sure there is an account created in your Barion wallet. This means that if you plan to have USD payments then there should be an USD account created in your wallet.
  • all the example codes assume the availability of jQuery

Limitations

Technical

Using Apple Pay as a token payment is currently not possible.

Shopper

Apple Pay will only be visible to shoppers fulfilling the following criteria:

Shop

Payment Process

  1. The customer clicks the Apple Pay button.
  2. Apple Pay session has to be created using the library provided by Apple as discussed here.
  3. The JS code receives a session data
  4. The JS code sends this information to the server side of the merchant
  5. The server side gathers the information necessary to call the /v2/ApplePay/ValidateSession endpoint.
  6. Apple Pay screen is displayed, where the customer can select the card, shipping address and contact details.
  7. The JS code receives the encrypted card information.
  8. The JS code sends the encrypted information to the sever side of the merchant
  9. The server side gathers the information needed to call the /v2/ApplePay/StartPaymentWithAppleToken endpoint.
  10. The Barion API handles the request, decrypts the packages and charges the card. The result of the payment is sent back to the caller.
  11. The merchant's server communicates the result to the client side and the webshop renders the result of the payment.

Configuration

Domain verification file

First head over to secure.barion.com, and under Manage My Shops page select the appropriate one, and from the dropdown, click on settings. At the bottom click the Manage Apple Pay settings blue button under the Apple Pay Settings section. On the next page Click on the Download domain verification file button, which will download a domain association file. You should place this file at the content root of all of your sites, you're about to use apple pay in integrated mode. The file must:

  • mimemap for extension "." should be set to "application/json", for eg.:
    <mimeMap fileExtension="." mimeType="application/json" />
  • be externally accessible.
  • not be password protected.
  • the file cannot be behind a proxy or redirect.
  • your site must use https.

Configure Domains

On the exact same page you've downloaded the domain association file, enter all the domains (one in each line, without https:// or https://) you're intending to use Apple Pay.

Development

Include the Apple Pay SDK

Include the following code snippet in the header of your checkout page: <script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>

Display the Apple Pay button

Add the Apple Pay button to your checkout page as discussed here

Create an Apple Pay session

When the user taps the Apple Pay button, provide a payment request and create the session as discussed here. Create a variable which will store, if the Apple Pay UI is dismissed (isSessionCanceled).

Subscribe to the onvalidatemerchant event

Call your backend, which will in turn call the Barion Api ValidateSession endpoint in the event handler with the provided url as the payload, if the payment ui is not dismissed meanwhile:

	 appleSession.onvalidatemerchant = function (event) {
		// TODO: disable Apple Pay button
		const data = {
			SessionValidationUrl: event.validationURL
		};

		$.ajax({
			method: "POST",
			url: "https://yourserver.com/ValidateApplePaySession",
			data: data,
			success: function (response, status, xhr) {
				const merchantSession = JSON.parse(response.ApplePaySessionResponse);
				if(!isSessionCanceled) {
					appleSession.completeMerchantValidation(merchantSession);
				}
			},
			error: function (xhr, status, error) {
				// failure callback
				// TODO: enable Apple Pay button
			}
		});
	};

Subscribe to the onpaymentauthorized event

Call your backend, which will in turn call the Barion Api StartPaymentWithAppleToken endpoint in the event handler with the provided payment payload:

	appleSession.onpaymentauthorized = function (event) {
		let cart = {
			Payload = event.payment
			PaymentType = "Immediate",
			Mode = "",
		};

		$.ajax({
			method: "POST",
			url: "https://yourserver.com/StartApplePayment",
			data: cart,
			success: function (response, status, xhr) {
				if (response.IsSuccessful && response.PaymentStatus === 40) {
					appleSession.completePayment(appleSession.STATUS_SUCCESS);
				} else {
					appleSession.completePayment(appleSession.STATUS_FAILURE);
				}
			},
			error: function (xhr, status, error) {
				appleSession.completePayment(appleSession.STATUS_FAILURE);
			}
		});
	};

Subscribe to the oncancel event

This method gets called every time the Apple Pay UI is dismissed. You should implement your needs accordingly (for eg. re-enable pay button). Furthermore indicate that the session was canceled, so the completePayment won't be executed.

	appleSession.onpaymentauthorized = function (event) {
          	// TODO: enable Apple Pay button
            
            isSessionCanceled = true;
	};

Call ApplePaySession.begin method

Call the begin method, and the merchant validation process begins. So your final client side code will look like this:

var request = {
  countryCode: 'HU',
  currencyCode: 'HUF',
  supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'],
  merchantCapabilities: ['supports3DS'],
  total: { label: 'Your Merchant Name', amount: '1000.00' },
};
var isSessionCanceled = false;

var appleSession = new ApplePaySession(3, request);
appleSession.onvalidatemerchant = function (event) {...}
appleSession.onpaymentauthorized = function (event) {...}
appleSession.begin();

API reference