Use Recurly.js to process Apple Pay transactions. Recurly.js supports Apple Pay out of the box. To get started, ensure your site is configured to accept Apple Pay transactions.

Setting up your Apple Pay integration in Recurly.js involves two parts:

1. Displaying the button
2. Invoking the purchase flow

Prerequisites and limitations

• Site configuration – Apple Pay must already be enabled and verified in your Recurly admin settings. Follow the Apple Pay on the Web setup guide before adding client-side code.
• Browser / device support – Customers must use Safari (macOS 10.14.4+, iOS 12.2+) or another Apple Pay–capable browser/device.
• Token lifetime – Tokens returned from the Apple Pay flow follow standard Recurly.js rules: reusable for up to 20 minutes, then permanently expire.
• Braintree processing – If you route Apple Pay through Braintree you must supply a valid client authorization string when instantiating recurly.ApplePay.

Key details

Displaying The Button

Your button styling needs to adhere to Apple’s specifications.

See Apple's documentation on Displaying the Apple Pay Button for guidelines on display and styling the button.

Invoking The Purchase Flow

Configure a new instance of recurly.ApplePay as follows.

// Handle when the token has been generated to keep the payment sheet in the "Processing"
// state until the onPaymentAuthorized callback has completed
function onPaymentAuthorized({ payment }) {
  const { recurlyToken: token, billingContact, shippingContact } = payment;
  // Submit the token to your server
  console.log('Apple Pay succeeded.',
              'Token:', token.id,
              'billingContact:', billingContact,
              'shippingContact', shippingContact);
}

const applePay = recurly.ApplePay({
  country: 'US',
  currency: 'USD',
  label: 'My Subscription', // This text will be displayed on the Apple Pay payment sheet as "My Subscription"
  total: '29.00',
  callbacks: {
    onPaymentAuthorized,
  }
});

// When the ApplePay instance is ready, bind the Apple Pay button click
// to applePay.begin
applePay.ready(function () {
  $('#my-apple-pay-button').on('click', function () {
    applePay.begin();
  });
});

// Handle errors. These may occur at any point in the Apple Pay flow
applePay.on('error', function (err) {
  // err.code, err.message
  console.error('Apple Pay error', err);
});

ApplePay via Braintree

If you're processing Apple Pay transactions with Braintree, you'll pass a client authorization during instantiation:

const applePay = recurly.ApplePay({
  country: 'US',
  currency: 'USD',
  label: 'My Subscription', // This text will be displayed on the Apple Pay payment sheet as "My Subscription"
  total: '29.00',
  callbacks: {
    onPaymentAuthorized,
  }
  braintree: {
    clientAuthorization: MY_CLIENT_AUTHORIZATION
  }
});

Additional configuration

If you are using the recurly.Pricing.Checkout class to calculate checkout prices, you may pass
your pricing instance instead of providing a total.

const pricing = recurly.Pricing.Checkout();

const applePay = recurly.ApplePay({
  // ...
  pricing: pricing
});

To provide additional customer data to tokens generated by recurly.ApplePay, you may pass a form
reference. recurly.ApplePay will collect customer data from the form just as would occur during credit card tokenization. See Getting a Token for more information on building such a form.

const applePay = recurly.ApplePay({
  // ...
  form: document.querySelector('#my-payment-form')
});

Integration Notes

• Recurly.js will automatically pull in the billing info from the customer's Apple account if their Apple Pay setup is complete with full billing information in their Apple Wallet. If the user does NOT have a billing name or address attached to their card in their Apple Wallet, the Apple Pay flow will prompt the customer for a billing address.
• If you choose to include a Recurly.js payment form, any billing name or address fields entered on that form will replace the billing address in the user's Apple Wallet on the payment sheet. The user can always change their billing address once the payment sheet has loaded.
• Integration examples

Reference

fn - recurly.ApplePay

Arguments

ApplePay options.callbacks Arguments

ApplePay options.paymentRequest Arguments

Returns

A new recurly.ApplePay instance

fn - applePay.ready

Arguments

Returns

Nothing.

event - Emits

paymentAuthorized

This event is fired when the customer has authorized the payment presented on the Apple Pay payment sheet.

Payload

token

This event is fired when the customer has completed the Apple Pay payment sheet flow. Recurly has received the payment details, and generated this token to be used in our API.

Payload

error

This event is emitted when any error is encountered, whether during setup of the Apple Pay payment sheet, or during payment authorization. It will be useful to display errors to your customer if a problem occurs during the Apple Pay flow.

Payload