Introduction

Apple Pay allows customers to checkout with cards saved on their Apple Wallet accounts via the web. Neon Pay provides an easy-to-use checkout experience powered by Apple Pay. 

Terms and Conditions

By using Neon Pay JS to integrate Apple Pay into your checkout process, you agree to and must adhere to the Apple Pay APIs acceptable use policy and accept the terms defined in the Apple Pay API Terms of Service.

Supported Authorization Methods and Card Networks

Neon Pay supports the following card networks in the US for charging:

  • American Express
  • Discover
  • MasterCard
  • Visa

How It Works

Neon Pay handles much of the communication

  1. Customer interacts with the Apple Pay button
  2. This requests a session from Apple through a secure connection through Neon Pay
  3. The customer accepts the payment and authorizes an Apple Token to be returned to the application
  4. Application requests a Neon Pay token via the Neon Pay JS API
  5. Neon Pay JS sends the encrypted payload to Neon Pay’s servers, which will decrypt card information for tokenization.
  6. Neon Pay sends a Neon Pay token to your application
  7. Application sends a charge request to Neon Pay’s Charge API
  8. Neon Pay sends the application the payment response
  9. Application informs their customer of the payment outcome

Prerequisites

The Neon Pay merchant must first have Apple Pay enabled. Currently, it can be enabled in two ways. Neon Pay Support staff have the ability to enable it on behalf of clients from within the Neon Pay portal. Developers also can enable Apple Pay processing on behalf of merchants connected to their application through an UPDATE Merchant request to the Neon Pay API (ie. PUT /merchants/{id}). The parameter supplied to this endpoint is has_apple_pay = true. 

Additionally, if applications create new merchant accounts through the Neon Pay API, developers will be able to enable Apple Pay processing within that POST request (ie POST /merchants will accept has_apple_pay as a parameter on creation. 

Apple Pay is only available through Neon Pay JS version 1.2 or later.

Server & Domain Setup Neon Pay JS 1.2 – 1.5:

Apple Pay requires certain server requirements be met to authorize and complete the Apple Pay payment sheet. Apple requires all domains utilizing our processing certificate be registered through their Mass Enablement API. Neon Pay has made this configuration easy by adding a merchant.domains array to our merchant model. To implement a new domain for a merchant developers can make a PUT api/merchants/{id} request and pass a domains parameter that will be an array of all the domains (including subdomains) the merchant will be using to transact with Apple Pay on. Domains should follow the following format: google.com, facebook.com, app.neononepay.com. 

Note that subdomains must be registered so abc.example.com and xyz.example.com would BOTH need to be submitted if both will be hosting payment forms. Once submitted to the Neon Pay API, these domains will be passed along to Apple through our integration and will be allowed to use the Apple Pay payment modal without server certificate issues. 

In addition, every website/domain using the Apple Pay modal will need to upload a single file to a .well-known directory at the root of the server. Apple will use this file to verify your domain is appropriately registered in their API and allowed to render the Apple Pay modal. This file can be retrieved from the GET api/files/apple-domain API endpoint. Apple Pay will look for this file at {server_root}/.well-known/apple-developer-merchantid-domain-association. 

Server & Domain Setup for Neon Pay JS 2.0 or higher:

Apple Pay for Stripe is only available through Neon Pay JS 2.0 or higher.

Apple Pay requires certain server requirements be met to authorize and complete the Apple Pay payment sheet. Apple requires all domains utilizing our processing certificate be registered through their Mass Enablement API or through Stripe’s Domain registration depending on the merchant. Neon Pay has made this configuration easy by adding a merchant.domains array to our merchant model. 

Before submitting a request for a domain, applications need to retrieve the appropriate domain association file for the Merchant.  Apple will use this file to verify your domain is appropriately registered in their API and allowed to render the Apple Pay modal. This can be done through the GET /api/files/apple-domain?merchant_id=# endpoint for Payrix Merchants. For Stripe merchants, this file can be retrieved from Stripe directly from https://stripe.com/files/apple-pay/apple-developer-merchantid-domain-association. Apple Pay will look for this file at {server_root}/.well-known/apple-developer-merchantid-domain-association. Note: This also means that the same domain cannot host both Payrix merchants and Stripe merchants as the files have the same name so only one can be in the .well-known folder. 

To implement a new domain for a merchant developers can make a PUT /api/merchants/{id} request and pass a domains parameter that will be an array of all the domains (including subdomains) the merchant will be using to transact with Apple Pay on. Domains should follow the following format: google.com, facebook.com, app.neononepay.com. Note: The domain association file above must be present for a domain to be listed from this endpoint. If it’s not present, Stripe will send a validation failure. 

Note that subdomains must be registered so abc.example.com and xyz.example.com would BOTH need to be submitted if both will be hosting payment forms. Once submitted to the Neon Pay API, these domains will be passed along to Apple through our integration and will be allowed to use the Apple Pay payment modal without server certificate issues. 

Integrate through Neon Pay JS

The Apple Pay button can be added to your payment page as a standalone option, with or without the standard credit card fields provided by Neon Pay JS. 

  1. If you do not already have one, generate a public API key for your application within the Neon Pay portal.
  2. Initialize the Neon Pay JS and the field object for Apple Pay in your payment form, see a developer example here.
    • This will add the Apple Pay button through an IFrame, which your customer will be able to interact with.
    • Remember! When offering Apple Pay as an option, the button should be placed at equal prominence as other payment options according to the Apple Pay Brand Guidelines.
  3. Generate and catch the Neon Pay token via Neon Pay JS’s createToken API method.
    • We highly recommend that developers pass billing information as additional token information. This will decrease the risk of a charge not being authorized because of issues in cardholder address verification.
    • Your application will not need to handle or interact with any encrypted Apple Pay payment or transaction data. Neon Pay JS is responsible for decrypting that information for tokenization. In return, your application will receive a secure token and basic card information. 
  4. Use the Neon Pay token in your application’s request to Neon Pay’s Charge API.
  5. Handle any errors and inform your customer about the payment’s outcome.
<form id="paymentForm" action="#" method="POST">
    <h2>Payment Form</h2>
    <div id="applePayButton"></div>
    <input type="hidden" id="token" value="" />
    <input id="paymentSubmit" type="submit" value="Process Payment" />
</form>
 
<script src="https://cdn.sbx.neononepay.com/3.0/neonpay.js"></script>
<script type="text/javascript">
    // Set up the NeonPay fields on your form
    var neonpay = new NeonPay('public_f8564752122b08cc9c20c374562d5cc7', '19', {swipe: true});
    var applepay= neonpay.createField('applepay', {price: '25.00', label: 'Donation', storeName: 'Give Today'});

    (async () => {
        // Check if merchant can process payments first
        const result = await neonpay.canMakePayments();

        if (result) {
            applepay.mount('#applePayButton');
        } else {
            // There was an error and the payment is not possible for this configuration
            document.querySelector('#applePayButton').style.display = 'none';
        }
    })();
 
    var paymentForm = document.getElementById('paymentForm');
    var tokenField = document.getElementById('token');
 
    // Intercept form submission and retrieve token
    paymentForm.addEventListener('submit', function (event) {
        event.preventDefault();
 
        var tokenData = {
            first_name: 'Robert',
            middle_name: 'Norman',
            last_name: 'Ross',
            email: 'bob@ross.net',
            phone: '+18888606366',
            address_line_1: '4545 N. Ravenswood Ave.',
            address_line_2: '2nd Floor',
            address_city: 'Chicago',
            address_state: 'IL',
            address_zip: '60640',
            address_country: 'US'
        };
 
        var token = neonpay.createToken(applepay, tokenData).then(function(result) {
            // Pass the token to your Charge API call using
            // a hidden input that your form will serialize
            // or to an intermediary API on your server
            if (result.token) {
                tokenField.value = result.token;
            }
        });
    });
</script>

Testing Your Integration

Apple Pay is supported within Neon Pay’s sandbox environment. Please develop and test your integration through the sandbox version of Neon Pay JS, available at https://cdn.sbx.neononepay.com/3.0/neonpay.js.

When you’re ready to integrate for production, use https://cdn.app.neononepay.com/3.0/neonpay.js.

Test Cards & Neon Pay JS:

Apple offers a variety of test card options: https://developer.apple.com/apple-pay/sandbox-testing/. We’d like to point out that these test cards can only be used to test Payrix merchant implementations. If using a Stripe Merchant, they require a real card be inputted into the Apple Wallet. The card will not be charged in any way as tokens/charges are still going to Stripe Sandbox environment, but this is a limitation of the Stripe Apple Pay integration. More information can be found here: https://support.stripe.com/questions/testing-apple-pay-with-stripe.

Helpful Links

Apple Pay Programming Guide

Apple Pay Brand Guidelines