Apple Pay


Apple Pay is a wallet application that provides the merchant with a one-time use network token that can be used to authorize and capture funds through an Apple Pay approved gateway. Apple Pay handles all the heavy lifting of interacting with the consumer and simply returns the results the consumer has chosen.

This guide assumes you have only completed a basic integration with Songbird. If you have already added other payment brands some steps may already be complete.


You must have the following to complete an Apple Pay integration:

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.

We recommend that all front end development and end-to-end testing be completed on a Mac computer using the Safari browser.

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.


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.

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

Payment Button Container
<div id="Cardinal-Payments"></div>

Button Placement

The 'Cardinal-Payments' div is the generic payment button container for payment buttons. Songbird will inject all payment buttons into this container unless specified otherwise. If you'd like more control over placing specific payment buttons in different locations, check out the advanced payment buttons section.

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 Apple Pay configuration object, passing in which button color to use.

Configure Apple Pay Button Style
  applePay: {
	color: 'black'

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

Custom Apple Pay Button and Logging Settings
  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. 

Looking for Apple Pay objects?

Refer to the response objects section for information on what the Apple Pay Payment object looks like.

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

Example Response JWT
    "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 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.

Looking for more JWE info?

For more information on decrypting a JWE refer to the JWE section.

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.

Looking for more details on Complete?

Refer to the Cardinal.complete section for implementation details on the complete call.

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