Browser Support

Apple Pay is only supported on Apple devices and Apple computers within the Safari browser. Devices must contain specific hardware, which generally means they must have been manufactured after 2012. For more information on supported devices please refer to Apple's documentation. Some computers may require the use of iDevices during the Apple Pay transaction in order to complete the transaction. These restrictions are put in place and enforced by Apple - CardinalCommerce has no ability to change them.

Cardinal Cruise uses feature detection to determine if the browser supports Apple Pay. If support is detected and you have Apple Pay integrated, Cardinal Cruise will automatically show the Apple Pay button. If the browser or device is not supported Cardinal Cruise will simply not render the Apple Pay button - no error will be triggered.

Transaction Flow

Below is a diagram that shows the order of events in a successful Apple Pay transaction.

Implementation

The below steps are what needs to be done in addition to completing the basic Songbird implementation.

Order Object Requirements

An Apple Pay integration requires the following information to be passed to Songbird before or during Songbird.setup() execution. This data is required to properly inject the Apple Pay payment button. Failure to pass all required fields will result in Apple Pay not being loaded on your page.

• Amount
• CurrencyCode
• OrderNumber

Add Payment Button

An Apple Pay transaction starts when the consumer clicks the Apple Pay button. Songbird will handle injecting the payment button into your website, so all you need to do is to tell Songbird where to inject the button. You can do this by placing an empty div in the location you'd like the button to be injected with the id of 'Cardinal-Payments' as seen below.

<div id="Cardinal-Payments"></div>

You may pick from a few different available Apple Pay payment buttons to match your site. To change the payment button look, simply pass in the ApplePay Apple Pay configuration object, passing in which button color to use.

Cardinal.configure({
  applePay: {
	color: 'black'
  }
});

Remember, you should only have a single Cardinal.configure execute per page load. So , so if you already have a Cardinal.configure implementation, simply add the applePay object the Apple Pay object to your existing configurations:

Cardinal.configure({
  logging: {
	level: 'on'
  },
  applePay: {
	color: 'black'
  }
});

Handle Apple Pay Response

Cardinal Cruise and Apple Pay will handle all the user interactions up until Apple Pay has returned back card details for you to authorize and capture with. The next step in the integration is to add logic to your payements.validated event to handle specific return values for Apple Pay. 

Apple Pay will also include a JWE value in addition to the normal Payment object included with other payment brands. (The JWE claim contains the card data returned by Apple Pay, refer ).  Refer to the next section 'Decrypt JWE' for more details on getting access to the card data.

The below example is what you should expect the response JWT to contain on a successful Apple Pay transaction.

{
    "iss": "Midas-NoDV-Key",
    "iat": 1496949566,
    "exp": 1496956766,
    "jti": "0f253760-08e0-44a8-afe0-800cedf8bbba",
    "ConsumerSessionId": "6701b0d6-d0b2-49a7-b23b-236dbf2c0b02",
    "ReferenceId": "6701b0d6-d0b2-49a7-b23b-236dbf2c0b02",
    "aud": "5b77e0b0-4c7f-11e7-9789-ebc1317a84eb",
    "Payload": {
        "Validated": true,
        "Payment": {
            "Type": "APPLEPAY",
            "ProcessorTransactionId": "hDKruoNOxw11OfEGtA80",
            "ExtendedData": {
                "CAVV": "AlwaEAYAMxWOwbP4F12MMAACAAA=",
                "DeviceManufacturerIdentifier": "040010030273",
                "ECI": "7",
                "PaymentDataType": "3DSecure"
            },
            "ShippingAddress": {
				"FirstName": "John",
                "LastName": "Doe",
                "Address1": "8100 Tyler",
                "City": "Mentor",
                "State": "Oh",
                "PostalCode": "44060",
                "CountryCode": "US"
            },
            "BillingAddress": {
                "FirstName": "Jane",
                "LastName": "Doe",
                "Address1": "8100 Tyler",
                "City": "Mentor",
                "State": "Oh",
                "PostalCode": "44060",
                "CountryCode": "US"
            },
            "OrderId": "8220903285635803",
            "OrderNumber": "a5s3df219hd237rdjskaec"
        },
        "ActionCode": "SUCCESS",
        "JWE": "eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2R0NNIiwiaXYiOiJPN3VaUDBtSEltbzdtMUZkIiwidGFnIRvQVhSN1RvM3pPVmUtNHhvZyJ9.5Dn853P0dYp6rISfjySyjyBaUovEkzIRIrWKl1WDsZU.gD2VkMo1rCOFOY.P4-NItZ31qj8F-vKabV2NUNot16OMaqhFNUtwQPne0tVh9IQL6ENUn7zM7rKINTMs7BbUMSDcLuSm8trtMKGtdBRzv0P6-DZ21Z9QY2Zr71scY03EnA2WUoNHLaYcr5qsR0lhUk_e.FxeTGkuxRd27WVpwOrroBg",
        "ErrorNumber": 0,
        "ErrorDescription": "Success"
    }
}

Decrypt JWE

Because Apple Pay is a wallet, card details need to be returned back to the merchant to authorize and capture against. Cardinal Cruise uses a JWE to encrypt the card details . A and a successful transaction will include a JWE on the response. To access the account details, this JWE should be sent to your backend to decrypt. Decryption will need to be completed asynchronous and without redirecting from the current payment page. This means that you will most likely have to use an Ajax request to your backend to decrypt the card details. This is due to the Apple Pay restriction that a transaction cannot end until authorization results are returned to Apple. Failure to do so will result in the Apple Pay payment sheet never being dismissed.

Once you have successfully decrypted the card details, you should send in an authorization request to your gateway. This also needs to be done asynchronously on the payments page where the user started the Apple Pay transaction. In most cases, decryption and authorization would occur on the same Ajax request to your backend. The authorization result will need to be relayed back to your front end, as this is the value that Apple Pay needs to complete the transaction and close the payment sheet.

Return Authorization Result

Call the Cardinal.complete function, passing in a complete object that describes the authorization attempt. Once this call has been triggered, the Apple Pay payment sheet will be dismissed with a success or failure status and the transaction is considered to be completed.

Cardinal.complete({
        Status: "Success"
    })
    .then(function(){
        // Executes when the payment sheet has been dismissed
    })
    .catch(function(error){
        // Triggers if any error is thrown. This would include any errors encountered in your .then callback, if you're not properly catching errors.
    });