Skip to main content

Accept Apple Pay™ MPAN Payments

This guide explains how to accept Apple Pay™ payments using Merchant-Provisioned Account Numbers (MPANs) with the Basis Theory platform to handle PCI-sensitive data securely. MPANs are specialized tokens provided by Apple that enable merchants to accept payments for recurring transactions, subscriptions, and other ongoing payment scenarios.

Let’s begin by reviewing the Apple Pay™ payment flow.

When the user clicks the Apple "Pay" button, a sequence of high-level steps is initiated:

  1. Creation of an Apple Pay™ session - The client application calls Basis Theory to initiate an Apple Pay™ session.

  2. Decryption of the payment data - After the user authorizes the payment, the encrypted payment data is sent to Basis Theory for decryption and storage. Basis Theory responds with an Apple Pay™ resource that can be used to process the payment.

  3. Processing of the payment data - The Basis Theory Apple Pay™ resource is forwarded to the payment processor via Basis Theory Proxy, which translates Token back to raw data before sending the request. Upon receiving a successful payment response, the client application can complete the payment and inform the user that the payment was successful.

Accept Apple Pay™

Understanding Apple Pay™ MPANs​

Apple provides MPAN tokens for various payment scenarios:

  • Recurring Payments - Subscriptions, memberships, and regular billing cycles
  • Automatic Reload - Topping up accounts when balances fall below thresholds
  • Deferred Payment - Pre-authorization for services delivered at a later date

When using MPANs, the payment flow includes additional configuration in the Apple Pay™ payment request to specify the type of recurring payment and associated parameters.

Getting Started​

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Be sure to use your work email (e.g., john.doe@yourcompany.com)

Domain Verification​

Domain verification is a key step in getting Apple Pay™ up and running on your site. It is a required step for development and production servers, to confirm that you own the domain where Apple Pay™ will be implemented, preventing unauthorized use and maintaining the integrity of the payment system.

  1. Download and serve the domain association file on your server at https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association.
  2. Add the public domain to your tenant using the Customer Portal or the API

Apple requires the website to be served via HTTPS, which can be tricky during the development phase. Tunneling may represent a good option to preview local projects through a working HTTPS connection. Cloudflare tunnel may be worth checking out.

Creating an Apple Pay™ session​

To initiate the payment modal, an Apple Pay™ session must be started. Basis Theory integrates with Apple to request the payment session.

Create a Public Application​

You will need a Public Application to authenticate requests. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

  • Permissions: apple-pay:session, apple-pay:create
Save the key from the created Public Application as it will be used later in this guide.

Configure Apple Pay™​

Let's add the Apple Pay™ button and modify the session.onvalidatemerchant event handler to call the Create Merchant Session endpoint.

<html>
<head>
    <script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>
    <style>
      apple-pay-button {
        --apple-pay-button-width: 194px;
        --apple-pay-button-height: 64px;
        --apple-pay-button-border-radius: 13px;
        --apple-pay-button-padding: 0px 0px;
        --apple-pay-button-box-sizing: border-box;
      }
    </style>

    <script>
      function onApplePayButtonClicked() {
        if (!ApplePaySession) {
          return;
        }

        const session = createApplePaySession();

        session.onvalidatemerchant = async (event) => {
          const merchantSession = await validateMerchant();
          session.completeMerchantValidation(merchantSession);
        };

        session.begin();
      }

      async function validateMerchant() {
        try {
          const response = await fetch('https://api.basistheory.com/apple-pay/session', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'BT-API-KEY': '<PUBLIC_APPLICATION_KEY>'
            },
            body: JSON.stringify({
              display_name: 'My Store',
              domain: window.location.host
            })
          });

          if (!response.ok) {
            throw new Error(`HTTP error! Status: ${response.status}`);
          }

          const data = await response.json();
          return data;
        } catch (error) {
          console.error('Error validating merchant:', error);
          throw error;
        }
      }
    </script>
</head>
<body>
  <apple-pay-button buttonstyle="black" type="plain" locale="en-US"></apple-pay-button>
  <script>
    // Set up the onclick handler for the Apple Pay™ button
    document.querySelector('apple-pay-button')
      .addEventListener('click', onApplePayButtonClicked);
  </script>
</body>
</html>

Adding the apple-pay-sdk.js script will enable the <apple-pay-button> directive to your website. The validateMerchant function calls Basis Theory to initiate the Apple Pay™ session.

MPANs require an additional configuration passed into the Apple Pay™ment session. Below are example ApplePaySessions for the various types of MPANs.

Each object has slightly different attributes. However, there are two that are shared, managementURL and tokenNotificationURL.

The managementURL attribute should be a URL to a webpage on your site where the user can manage their recurring payments.

The tokenNotificationURL is the URL that Apple will call with events that affect the created MPAN. Basis Theory will be responsible for receiving the events from Apple and updating the token. This URL should be in format of https://api.basistheory.com/apple-pay/{<YOUR_TENANT_ID>}.

Recurring Payment (Subscription)​

function createApplePaySession() {
  return new ApplePaySession(3, {
    "countryCode": "US",
    "currencyCode": "USD",
    "merchantCapabilities": [
      "supports3DS"
    ],
    "supportedNetworks": [
      "visa",
      "masterCard",
      "amex",
      "discover"
    ],
    "total": {
      "label": "Monthly Subscription",
      "type": "final",
      "amount": "9.99"
    },
    "recurringPaymentRequest": {
      "paymentDescription": "Monthly Premium Subscription",
      "regularBilling": {
        "label": "Monthly Premium",
        "amount": "9.99",
        "type": "final"
      },
      "managementURL": "https://yoursite.com/manage-subscription",
      "tokenNotificationURL": "https://api.basistheory.com/apple-pay/{tenantId}"
    }
  });
}

See the documentation on Apple's site for more information on recurring payments.

Automatic Reload​

function createApplePaySession() {
  return new ApplePaySession(3, {
    "countryCode": "US",
    "currencyCode": "USD",
    "merchantCapabilities": ["supports3DS"],
    "supportedNetworks": ["visa", "masterCard", "amex", "discover"],
    "total": {
      "label": "Account Auto-Reload Setup",
      "type": "final",
      "amount": "0.00"
    },
    "automaticReloadPaymentRequest": {
      "paymentDescription": "Automatic Account Reload",
      "automaticReloadBilling": {
        "label": "Account Reload",
        "amount": "25.00",
        "type": "final"
      },
      "billingAgreement": "Automatically reload $25.00 when account balance falls below $5.00",
      "managementURL": "https://yoursite.com/manage-auto-reload"
    }
  });
}

See the documentation on Apple's site for more information on automatic reload payments.

Deferred Payment​

function createApplePaySession() {
  return new ApplePaySession(3, {
    "countryCode": "US",
    "currencyCode": "USD",
    "merchantCapabilities": ["supports3DS"],
    "supportedNetworks": ["visa", "masterCard", "amex", "discover"],
    "total": {
      "label": "Pre-order: Limited Edition Item",
      "type": "final",
      "amount": "149.99"
    },
    "deferredPaymentRequest": {
      "paymentDescription": "Pre-order Payment Authorization",
      "deferredBilling": {
        "label": "Item Charge",
        "amount": "149.99",
        "type": "final"
      },
      "billingAgreement": "Payment will be processed when item ships (estimated 30-45 days)",
      "managementURL": "https://yoursite.com/manage-preorders"
    }
  });
}

See the documentation on Apple's site for more information on deffered payments.

Tokenization​

After the customer has authorized the payment, your application will need to call the Tokenize endpoint with the encrypted Apple Pay™ token.

Let's add the session.onpaymentauthorized event handler and make that request.

<html>
<head>
    <script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>
    <style>
      apple-pay-button {
        --apple-pay-button-width: 194px;
        --apple-pay-button-height: 64px;
        --apple-pay-button-border-radius: 13px;
        --apple-pay-button-padding: 0px 0px;
        --apple-pay-button-box-sizing: border-box;
      }
    </style>

    <script>
      function onApplePayButtonClicked() {
        if (!ApplePaySession) {
          return;
        }

        const session = createApplePaySession();

        session.onvalidatemerchant = async (event) => { ... };

        session.onpaymentauthorized = async (event, session) => {
          try {
            // decrypt and tokenize Apple Pay™
            const applePayToken  = await tokenize(event);
            // present green check to the user before the timeout (30 seconds)
            session.completePayment(ApplePaySession.STATUS_SUCCESS);
          } catch (e) {
            console.error(e);
            session.completePayment(ApplePaySession.STATUS_FAILURE);
          }
        };

        session.begin();
      }

      function createApplePaySession() { ... }

      async function validateMerchant() { ... }

      async function tokenize(event) {
        const response = await fetch('https://api.basistheory.com/apple-pay', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'BT-API-KEY': '<PUBLIC_APPLICATION_KEY>'
          },
          body: JSON.stringify({
            apple_payment_data: event.payment.token
          })
        });

        if (!response.ok) {
          throw new Error(`HTTP error! Status: ${response.status}`);
        }

        const appleToken = await response.json().apple_pay;
        console.log('apple token', appleToken);
        return appleToken;
      }
    </script>
</head>
<body>
  <apple-pay-button buttonstyle="black" type="plain" locale="en-US"></apple-pay-button>
  <script>
    // Set up the onclick handler for the Apple Pay™ button
    document.querySelector('apple-pay-button')
      .addEventListener('click', onApplePayButtonClicked);
  </script>
</body>
</html>

Processing the Payment​

We'll send the Basis Theory Apple Pay™ resource to a Payments Service Provider (PSP) to test charging a card. We'll be doing this from our backend by using a Proxy and a Private Application.

Create a Private Application​

You will need a Private Application to allow your backend to call Basis Theory APIs. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

  • Permissions: proxy:invoke
Save the key from the created Private Application as it will be used later in this guide.

Charge the Payment​

Payment service providers (PSPs) may differ in how they handle this operation, offering workflows like "authorization and capture" or "direct charge."

We'll change our frontend application one last time to pass in the Token ID to the backend to process the payment.

<html>
<head>
    <script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>
    <style>
      apple-pay-button {
        --apple-pay-button-width: 194px;
        --apple-pay-button-height: 64px;
        --apple-pay-button-border-radius: 13px;
        --apple-pay-button-padding: 0px 0px;
        --apple-pay-button-box-sizing: border-box;
      }
    </style>

    <script>
      function onApplePayButtonClicked() {
        if (!ApplePaySession) {
          return;
        }

        const session = new ApplePaySession(3, {
          ...
        });

        session.onvalidatemerchant = async (event) => { ... };

        session.onpaymentauthorized = async (event, session) => {
          try {
            // decrypt and tokenize Apple Pay™
            const applePayToken = await tokenize(event);
            // present green check to the user before the timeout (30 seconds)
            session.completePayment(ApplePaySession.STATUS_SUCCESS);
            // send the token to the backend for payment processing
            const response = await chargePayment(applePayToken.id);
            console.log(response);
          } catch (e) {
            console.error(e);
            session.completePayment(ApplePaySession.STATUS_FAILURE);
          }
        };

        session.begin();
      }

      function createApplePaySession() { ... }

      async function validateMerchant() { ... }

      async function tokenize(event) { ... }

      async function chargePayment(applePayTokenId) {
        return fetch('http://localhost:3000/charge-payment', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            applePayId: applePayTokenId
          })
        });
      }
    </script>
</head>
<body>
  <apple-pay-button buttonstyle="black" type="plain" locale="en-US"></apple-pay-button>
  <script>
    // Set up the onclick handler for the Apple Pay™ button
    document.querySelector('apple-pay-button')
      .addEventListener('click', onApplePayButtonClicked);
  </script>
</body>
</html>

We'll set up and invoke the ephemeral Proxy on our backend.

Request a Payment
curl 'https://api.basistheory.com/proxy' \
 -X 'POST' \
 -H 'Content-Type: application/json' \
 -H 'BT-API-KEY: <PRIVATE_API_KEY>' \
 -H 'BT-PROXY-URL: https://api.sandbox.checkout.com/payments' \
 -H 'Authorization: Bearer <CHECKOUT_AUTH_TOKEN>' \
 -d '{
   "source": {
     "type": "network_token",
     "token_type": "applepay",
     "token": "{{ apple_pay: <APPLE_PAY_TOKEN_ID> | json: \"$.data.number\" }}",
     "expiry_month": "{{ apple_pay: <APPLE_PAY_TOKEN_ID> | json: \"$.data\" | card_exp: 'MM' }}",
     "expiry_year": "{{ apple_pay: <APPLE_PAY_TOKEN_ID> | json: \"$.data\" | card_exp: 'YYYY' }}",
     "eci": "{{ apple_pay: <APPLE_PAY_TOKEN_ID> | json: \"$.authentication.eci_indicator\" }}",
     "cryptogram": "{{ apple_pay: <APPLE_PAY_TOKEN_ID> | json: \"$.authentication.threeds_cryptogram\" }}"
   },
   "amount": 1000,
   "currency": "USD",
   "processing_channel_id": "<CHECKOUT_PROCESSING_CHANNEL_ID>"
 }'

Request a Payment Docs

You may need to ask your payment processor to enable accepting decrypted Apple Pay™ in your account.
You are not restricted to the Payment Processors listed above. As long as your partner can accept cards decrypted Apple Pay™ resources, you can invoke it using the Ephemeral Proxy.

Testing​

Basis Theory does not support Apple’s sandbox environment, requiring the use of an actual card from your Apple Wallet for testing purposes. When operating within a Test tenant, Basis Theory will not return real card data. Although the Apple Pay™ resource generated during development is authentic, the associated Basis Theory Apple Pay™ resource will contain simulated data only.

To access genuine, valid network tokens derived from Apple Pay™ resources, a Production tenant must be utilized.

Preparing for Production​

This checklist will guide you through the critical steps you need to follow before moving your Apple Pay™ integration into production. Ensuring that everything is properly set up and tested reduces the likelihood of errors during live transactions and offers a seamless payment experience to your customers.

Test in Production with a Live Wallet and Card​

  • Before going live, perform test transactions using a Live Apple Pay™ wallet with a personal or corporate card added. This step ensures that everything is functioning correctly in the production environment with real-world payment methods.
  • Keep in mind that Apple Pay™ in production does not behave the same as in testing, so using live payment information is critical.

Handling Transaction Failures​

When a transaction fails, here’s what you should do:

  1. Check the Error Code: Look for any error codes returned as part of the failed transaction response. These error codes typically point to the cause of the failure.
  2. Contact Your Payment Processor: If the error code is unclear, reach out to your Payment Processor to diagnose the issue. As processors handle the transaction flow, they often have the most accurate and actionable information about why a transaction may have failed.
  3. Seek Assistance from Basis Theory (if applicable): If your integration leverages Basis Theory and you’re unable to resolve the issue with your processor, Basis Theory support can assist in identifying potential issues. However, the Processor will usually have the best resources and tools to help address errors swiftly.

Determine Where to Send Apple Pay™ Token Payloads​

Apple Pay™ generates a secure token payload for each transaction. It’s essential to configure your integration properly to ensure these tokens are correctly routed. Follow these steps:

  1. Review Processor Documentation: check the integration and setup documentation provided by your Payment Processor (PSP). They often provide detailed instructions on how and where to send Apple Pay™ token payloads.
  2. Enable Apple Pay™ Support with Your PSP: some payment processors require you to explicitly enable Apple Pay™ within their systems. Reach out to your PSP to ensure Apple Pay™ functionality is activated for your account.
  3. Understand How to Send Tokens: each PSP handles Apple Pay™ tokens differently, so it is critical to verify where the token payloads should be sent, and confirm the API endpoints, required headers, and payload formats specific to your PSP.
  4. Contact PSP for Guidance: if the documentation is unclear, reach out to your PSP’s support team to clarify the process for enabling Apple Pay™ support, and the steps to correctly transmit the token payload for processing.

Final Notes​

  • Keep logs of your test transactions in production for future reference.
  • Double-check all API keys, certificates, and environment configurations to avoid common production issues.
  • If you encounter additional issues or have questions specific to Basis Theory functionality, don’t hesitate to contact Basis Theory’s support team for further assistance.

By following this checklist, you’ll be prepared to seamlessly integrate and go live with Apple Pay™, providing a secure and smooth payment experience for your users.

FAQs​

My Stripe PaymentIntent and SetupIntent fail when using ApplePay.​

For PaymentIntents, the currency for the ApplePay Session and the currency set in the PaymentIntent must match or Stripe will decline the transaction. For SetupIntents, the currency for the ApplePay Session must match the defualt currency of your account - SetupIntents do not allow currency to be overridden.

What's the difference between regular DPAN and MPAN tokens?​

MPANs are merchant-provisioned tokens that offer enhanced security and specific use cases like recurring payments. They have different lifecycle management requirements and may include additional metadata.

Do all payment processors support MPANs?​

Not all payment processors support MPAN processing. Check with your PSP to ensure they can handle merchant-provisioned Apple Pay™ tokens before implementing MPAN support.

Do all card providers suppoert MPANs?​

No. Not all cards processors will supply MPANs. However, nothing changes in the tokenization or payment flows when a card does not support MPANs.

Can I use MPANs for one-time payments?​

While MPANs are designed primarily for recurring scenarios, they can be used for one-time payments if your merchant configuration and payment processor support it.

How do I handle MPAN token updates?​

Basis Theroy will handle the webhooks received from Apple and update your MPAN tokens accordingly.

Last updated on