Using Apple Pay

Apple Pay is a payment service from Apple that allows users to store sets of card details in the Wallet app and use them for purchases with the device. These include face-to-face purchases with a mobile device (such as an iPhone) and online purchases with the Safari web browser.

Smart Router lets you offer Apple Pay as a payment option to your customers. Go to Dashboard › Settings › Apple Pay to enable Apple Pay, add the payment certificates (which Apple uses to encrypt payment data), and configure the domains where you want to accept payments.

To accept payments with Apple Pay, you must get an Apple Developer account and also integrate our Apple Pay features into your website, as described in the sections below.

Using your Apple Developer account

Before you can start using Apple Pay, you must first create an Apple Developer account, if you have not already done so. When you have an account, follow the instructions to configure Apple Pay, which includes generating the certificates that you will need to accept payments with Smart Router.

The developer account also lets you use a sandbox testing environment that is similar to the one we provide. It lets you simulate payments during development without using any real-world customer data. To enable the sandbox:

  1. Log into App Store Connect.
  2. In Users and Access, go to the Testers page (under the Sandbox heading), and click on the plus sign (“+”) to create a new test user.
  3. Fill out the form, making sure that you note the email and password you provide, and then click Invite.
  4. On your test device, log out of your personal iCloud account and log in using the newly-created test credentials.
  5. Go into Wallet & Apple Pay in your Settings.
  6. Click on Add Credit or Debit Card, and then Enter Card Details Manually.
  7. You can now use any of the Apple Pay test cards. For example, you can use 4761 1200 1000 0492, exp 11/2022 and CVC 533 as a Visa test card.

Adding the Apple Pay button to your website

The HTML sample below shows how to use CSS styling to add the Apple Pay button to your page. Note that the CSS attributes for Apple Pay are specific to Apple’s Safari browser and are not supported in other browsers. The styling uses the white variant of the logo and keeps the button hidden by default.

<style>
  #apple-pay-button {
    display: none;
    background-color: black;
    background-image: -webkit-named-image(apple-pay-logo-white);
    background-size: 100% 100%;
    background-origin: content-box;
    background-repeat: no-repeat;
    width: 100%;
    height: 44px;
    padding: 10px 0;
    border-radius: 10px;
  }
  #apple-pay-button.visible {
    display: block;
  }
</style>
<button id="apple-pay-button"></button>

You should always use JavaScript code to check that Apple Pay is available before showing the button to your customer.

Firstly, follow our API access instructions to enable the processout.js library in your web page. Then, check if the customer’s browser supports Apple Pay and show the button using code like the following:

var client = new ProcessOut.ProcessOut("proj_XypcVbbihw7uzAVj18egy1nZeppStAhu");

client.applePay.checkAvailability(function(err) {
  // Show the button only if there is no error
  if (err) {
    console.log(err);
  } else {
    document.getElementById("apple-pay-button").className += "visible";
  }
);

Tokenizing the user’s card

The Apple Pay payment sheet lets the customer confirm their payment. You must only show the sheet in response to an action from the customer, such as a mouse click. The following code adds an event listener for a click on the Apple Pay button that was created in the HTML.

document.getElementById("apple-pay-button").
  addEventListener("click", tokenizeApplePay);

function tokenizeApplePay() {
  // Respond to the click.
}

You must create an ApplePayPaymentRequest object to tokenize an Apple Pay card (this object is referred to as session in the example code just below). The fields that you must supply at minimum to create the object are:

  • total: an object with fields for the label of the transaction and the amount to pay
  • currencyCode: currency code in ISO 4217 format with 3 letters
  • countryCode: country code in ISO 3166 format with 2 letters

Note that the value in the amount field of total is displayed to the customer in the sheet but Apple Pay does not require you to charge the same amount when you capture the payment. However, we strongly recommend that you charge the same amount that you show on the sheet.

You can also supply many other fields for the session object, but processout.js will supply sensible defaults if you omit them. The example shows how you can use the merchantCertificateId field to select a particular ApplePay merchant certificate for the tokenization:

function tokenizeApplePay() {
  var session = client.applePay.newSession({
    total: {
      label: "Amazing invoice",
      amount: "19.99"
    },
    currencyCode: "USD",
    countryCode: "US",
    merchantCertificateId: "merchant certificate id"
  });
  .
  .
}

Use the session object to activate and respond to the payment sheet:

function tokenizeApplePay() {
  var session = client.applePay.newSession({
    total: {
      label: "Amazing invoice",
      amount: "19.99"
    },
    currencyCode: "USD",
    countryCode: "US",
    merchantCertificateId: "merchant certificate id"
  });

  client.tokenize(session, {
    // Some custom data, such as your internal customer_id
  }, function(card) {
    // Calling session.completePayment with STATUS_SUCCESS closes the
    // Apple Pay payment sheet with a success message
    session.completePayment(ApplePaySession.STATUS_SUCCESS);
    console.log(card.id);

  }, function(err) {
    // STATUS_FAILURE shows an error on the Apple Pay payment sheet
    session.completePayment(ApplePaySession.STATUS_FAILURE);
    console.log(err);

  });
}

Your code should send the card.id token back to the server, where you can use it to capture the payment.

Customizing your integration

You can also add functions to the session object that will be called in response to specific user actions:

  • oncancel: called when the user cancels the payment
  • onpaymentmethodselected: called when the user selects a new payment method
  • onshippingcontactselected: called when the user selects a new shipping contact
  • onshippingmethodselected: called when the user selects a new shipping method

All of these function receive a single event parameter:

session.oncancel = function(event) {
  // Custom action
};

session.onpaymentmethodselected = function(event) {
  // Custom action
};

session.onshippingcontactselected = function(event) {
  // Custom action
};

session.onshippingmethodselected = function(event) {
  // Custom action
};

For example, you could use the oncancel() function to ask the user if they really want to abort the purchase and call event.preventDefault() to prevent the cancellation if they choose to continue.