Documentation

Apple Pay ™ Integation Guide

Accept payments with Apple Pay using the Ecart Pay SDK. As a supported Payment Service Provider (PSP), Ecart Pay handles merchant validation, token decryption, and payment processing — your integration is just a few lines of JavaScript.

Table of Contents

🚀 Getting Started

Prerequisites

Before integrating Apple Pay through the Ecart Pay SDK, ensure:

RequirementDescription
Ecart Pay AccountActive merchant account with the card payment method enabled
HTTPSYour website must be served over HTTPS
Domain VerificationYour domain must be verified with Apple (see Domain Verification)
Order IDYou can create orders via the Ecart Pay Orders API

☝️ Apple Pay Policies & Terms

All merchants using Apple Pay through Ecart Pay must complete the following essential steps:

✅

Comply with Apple Policies

📦 Installation

Add the Ecart Pay SDK <script> tag to your HTML page:

<!-- Production Environment -->
<script src="https://ecartpay.com/sdk/pay.js"></script>

<!-- Sandbox Environment (For testing purposes) -->
<script src="https://sandbox.ecartpay.com/sdk/pay.js"></script>
⚠️

Note

Use the sandbox version for development and testing. Switch to the production script only when you're ready to go live.

The SDK automatically loads the Apple Pay JS SDK when Pay.ApplePay.render() is called. This enables Apple Pay on all supported browsers, including Chrome and Firefox (via QR code on a nearby iPhone).

⚡ Quick Start

<div id="apple-pay-button"></div>

<script src="https://ecartpay.com/sdk/pay.js"></script>
<script>
  // 1. Listen for events
  Pay.ApplePay.on('ready', function () {
    console.log('Apple Pay button is ready');
  });

  Pay.ApplePay.on('success', function (event) {
    console.log('Payment successful:', event.detail);
    if (event.detail.redirect_url) {
      window.location.href = event.detail.redirect_url;
    }
  });

  Pay.ApplePay.on('error', function (event) {
    console.error('Error:', event.detail.message);
  });

  Pay.ApplePay.on('cancel', function () {
    console.log('Payment cancelled by user');
  });

  // 2. Render the button
  Pay.ApplePay.render({
    container: '#apple-pay-button',
    orderId: 'YOUR_ORDER_ID',
    amount: 100.00,
    currency: 'MXN',
    countryCode: 'MX',
    label: 'My Store',
  });
</script>

📋 Required Parameters

ParameterTypeDescription
containerstringCSS selector or DOM element where the Apple Pay button will be rendered
orderIdstringThe Ecart Pay order ID (obtained from the Orders API)
amountnumberTotal amount to charge
currencystringISO 4217 currency code (e.g., MXN, USD)
countryCodestringISO 3166-1 alpha-2 country code (e.g., MX, US)

🧩 Optional Parameters

ParameterTypeDefaultDescription
labelstring'ecartpay'Merchant display name on the payment sheet
supportedNetworksarray['visa', 'masterCard', 'amex', 'discover']Card networks to accept
merchantCapabilitiesarray['supports3DS']Payment capabilities
totalTypestring'final''final' or 'pending'
requiredBillingContactFieldsarray—Fields to request from billing contact
requiredShippingContactFieldsarray—Fields to request from shipping contact
shippingMethodsarray—Available shipping options
shippingTypestring—'shipping', 'delivery', 'storePickup', 'servicePickup'
buttonStylestring'black''black', 'white', 'white-outline'
buttonTypestring'pay''pay', 'buy', 'plain', 'check-out', 'donate'
localestring—Button language (e.g., 'en', 'es')
widthstring'100%'Button width (CSS value)
heightstring'44px'Button height (CSS value)
borderRadiusstring'4px'Corner radius (CSS value)
applePayVersionnumber3Apple Pay JS API version (3–14)
onShippingMethodSelectedfunction—Callback for shipping method changes
onShippingContactSelectedfunction—Callback for shipping contact changes

🌐 Supported Card Networks

Define the card networks you accept using the supportedNetworks parameter:

NetworkValue
Visavisa
MastercardmasterCard
American Expressamex
Discoverdiscover
Pay.ApplePay.render({
  // ...
  supportedNetworks: ['visa', 'masterCard', 'amex'],
});
⚠️

Important

Network values are case-sensitive for Apple Pay (e.g., masterCard, not MASTERCARD).

🔐 Merchant Capabilities

CapabilityDescription
supports3DSSupports 3D Secure authentication (required)
supportsDebitAccepts debit cards
supportsCreditAccepts credit cards

The supports3DS capability is always required by Apple Pay.

🏠 Billing & Shipping Contact

Request customer contact information from the Apple Pay payment sheet:

Pay.ApplePay.render({
  // ...
  requiredBillingContactFields: ['postalAddress', 'email', 'phone'],
  requiredShippingContactFields: ['postalAddress', 'email', 'phone'],
});

Available Contact Fields

FieldDescription
postalAddressFull postal address (street, city, state, zip)
emailEmail address
phonePhone number
nameFull name
📝

How Contact Data Is Handled

When the customer authorizes the payment, the SDK automatically sends the contact information to the Ecart Pay POST /api/applepay/shipping-contact endpoint. This updates the order with the customer's address, email, and phone before processing the payment.

Shipping Methods

You can provide predefined shipping options:

Pay.ApplePay.render({
  // ...
  shippingType: 'shipping',
  shippingMethods: [
    {
      label: 'Standard Shipping',
      detail: '5-7 business days',
      amount: '5.00',
      identifier: 'standard',
    },
    {
      label: 'Express Shipping',
      detail: '1-2 business days',
      amount: '15.00',
      identifier: 'express',
    },
  ],
});

💸 Handling the Payment Response

The SDK handles the entire Apple Pay flow. You only need to listen for events.

Payment Flow

StepDescription
1Customer taps the Apple Pay button
2Apple Pay payment sheet is displayed
3Customer authenticates with Face ID, Touch ID, or passcode
4Merchant validation — SDK calls POST /api/applepay/validate-merchant
5Contact data — SDK sends shipping/billing contact to POST /api/applepay/shipping-contact
6Payment — encrypted token sent to POST /api/process-payment
7Ecart Pay decrypts, validates, and processes the transaction
8SDK emits success or error event
Pay.ApplePay.on('success', function (event) {
  var result = event.detail;
  console.log('Payment status:', result.status);
  if (result.redirect_url) {
    window.location.href = result.redirect_url;
  }
});
✅

Best Practice

Always use the order status from the Orders API (GET /api/orders/:id) as the source of truth for your business logic. Do not rely solely on the SDK event.

📡 Events

EventDescriptionevent.detail
readyButton rendered. native indicates Safari native button{ native: boolean }
unavailableApple Pay is not available for this account{ message: string }
successPayment processed successfully{ status, redirect_url }
errorError during initialization or payment{ message: string }
cancelCustomer cancelled the payment sheet{}
Pay.ApplePay.on('ready', function (e) {
  console.log('Native button:', e.detail.native);
});
Pay.ApplePay.on('unavailable', function (e) { /* hide section */ });
Pay.ApplePay.on('success', function (e) { /* redirect */ });
Pay.ApplePay.on('error', function (e) { /* show error */ });
Pay.ApplePay.on('cancel', function () { /* user dismissed */ });

🎨 Button Styles

The SDK renders two types of buttons depending on the browser:

Native Button (Safari)

In Safari, the SDK renders the official Apple Pay button using the native -webkit-appearance: -apple-pay-button CSS property, which automatically follows Apple's brand guidelines.

Fallback Button (Chrome, Firefox, Edge)

In non-Safari browsers, the SDK renders a styled fallback button with the Apple logo and "Pay" text. If the native CSS property is not supported, the fallback is used automatically.

Style Options

StyleDescription
blackBlack background, white text and logo (default)
whiteWhite background, black text and logo
white-outlineTransparent with border, black text and logo
Pay.ApplePay.render({
  // ...
  buttonStyle: 'black',
  buttonType: 'pay',
  borderRadius: '8px',
  height: '48px',
});

🖥️ Cross-Browser Support

BrowserExperience
Safari (macOS/iOS)Native Apple Pay with Face ID, Touch ID, or passcode
ChromeApple Pay via QR code — scan with iPhone to authenticate
FirefoxApple Pay via QR code — same cross-device flow
EdgeApple Pay via QR code — same cross-device flow
👍

How It Works

The SDK automatically loads the Apple Pay JS SDK which enables the QR code flow in non-Safari browsers. No additional configuration is required by the merchant.

🔒 Domain Verification

Apple Pay requires that your domain is verified before accepting payments.

How It Works

Apple verifies domain ownership by checking for a specific file at:

https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association.txt

Steps

StepAction
1Contact Ecart Pay support to register your domain with Apple Pay
2Ecart Pay provides the apple-developer-merchantid-domain-association.txt file
3Host the file at /.well-known/apple-developer-merchantid-domain-association.txt
4Ensure the file is accessible over HTTPS without authentication or redirects
⚠️

Important

The domain verification file must be served with Content-Type: text/plain and must be accessible at the exact path shown above. Each domain (including subdomains) requires its own verification.

🧪 Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Apple Pay Checkout - Ecart Pay</title>
    <style>
        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; }
        .checkout { max-width: 480px; margin: 40px auto; padding: 24px; background: #fff; border-radius: 12px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
        #apay-container { min-height: 48px; margin: 16px 0; }
        .status { padding: 12px; border-radius: 8px; margin-top: 12px; display: none; font-size: 14px; }
        .status.success { display: block; background: #d1fae5; color: #065f46; }
        .status.error { display: block; background: #fee2e2; color: #991b1b; }
    </style>
</head>
<body>
    <div class="checkout">
        <h2>Checkout</h2>
        <p>Total: <strong>$100.00 MXN</strong></p>
        <div id="apay-container"></div>
        <div id="status" class="status"></div>
    </div>

    <script src="https://ecartpay.com/sdk/pay.js"></script>
    <script>
        var statusEl = document.getElementById('status');

        Pay.ApplePay.on('success', function (event) {
            statusEl.className = 'status success';
            statusEl.textContent = 'Payment successful!';
            if (event.detail.redirect_url) {
                window.location.href = event.detail.redirect_url;
            }
        });

        Pay.ApplePay.on('error', function (event) {
            statusEl.className = 'status error';
            statusEl.textContent = 'Error: ' + event.detail.message;
        });

        Pay.ApplePay.on('cancel', function () {
            statusEl.className = 'status error';
            statusEl.textContent = 'Payment cancelled.';
        });

        Pay.ApplePay.on('unavailable', function (event) {
            statusEl.className = 'status error';
            statusEl.textContent = event.detail.message;
        });

        // Replace YOUR_ORDER_ID with a real order ID from the Ecart Pay Orders API
        Pay.ApplePay.render({
            container: '#apay-container',
            orderId: 'YOUR_ORDER_ID',
            amount: 100.00,
            currency: 'MXN',
            countryCode: 'MX',
            label: 'My Store',
            buttonStyle: 'black',
            buttonType: 'pay',
            borderRadius: '8px',
            supportedNetworks: ['visa', 'masterCard', 'amex'],
            requiredShippingContactFields: ['postalAddress', 'email', 'phone'],
            requiredBillingContactFields: ['postalAddress'],
        });
    </script>
</body>
</html>
📝

Note

You can copy and paste this into an .html file and run it locally to test. Remember to use HTTPS (Apple Pay requires it) and the sandbox SDK for testing.

🧪 Testing

Use the Sandbox environment for testing:

<script src="https://sandbox.ecartpay.com/sdk/pay.js"></script>

Apple Pay Sandbox Testing

StepAction
1Create a Sandbox Tester Account in Apple Developer
2Add test cards to your sandbox Apple Pay wallet
3Test on a device signed into the sandbox account

Refer to the Apple Pay Sandbox Testing Guide for detailed instructions.

🚀 Going to Production

StepAction
1Verify your production domain with Apple (see Domain Verification)
2Switch to production SDK: <script src="https://ecartpay.com/sdk/pay.js"></script>
3Verify your Ecart Pay account is active and card payment method is enabled
4Test the complete flow on Safari (Mac/iOS), Chrome, and Firefox with real Apple Pay cards

🔎 Resources

Apple Pay Documentation

ResourceLink
Apple Pay on the Webdeveloper.apple.com/apple-pay/web
Apple Pay JS API ReferenceApple Pay JS API
Human Interface GuidelinesApple Pay HIG
Acceptable Use GuidelinesAUG
Sandbox TestingTesting Guide

Ecart Pay Documentation

ResourceLink
SDK JS Documentationdocs.ecartpay.com/docs/sdks
Orders APIdocs.ecartpay.com/docs/orders
3D Secure Flowdocs.ecartpay.com/docs/3d-secure

Updated about 2 months ago