Skip to main content

Local Development and Testing Setup

This guide shows how to test the DNA Payments Apple Pay Express Checkout button against the sandbox while developing on localhost.

Apple Pay requires HTTPS, so a public HTTPS URL is needed even for local development. We recommend ngrok as the default path.

Prerequisites​

Before you begin, make sure the following are in place:

  • ngrok is installed: Download ngrok.
  • Access to the DNA Payments test-portal to register your ngrok domain (test-portal.dnapayments.com).
  • Apple Sandbox tester account signed in on the device you will test from. The sandbox account is for the iCloud login on the test device, not for the merchant integration. Follow Apple's sandbox testing guide.
  • A page with the Apple Pay Express Checkout integration code (see Full Example) served by your existing dev server.

Step 1: Expose your dev server through ngrok​

Run your dev server as you normally would, then in a separate terminal expose it via ngrok:

ngrok http 3000   # replace 3000 with your dev-server port

ngrok prints a public HTTPS URL such as https://random-id.ngrok-free.app. Keep this terminal open: the URL is only valid while ngrok is running.

Step 2: Register the ngrok domain in test-portal​

Log in to test-portal.dnapayments.com and navigate to:

Settings → Online payment methods → Apple Pay → Add new domain

Paste the bare host (without scheme), for example random-id.ngrok-free.app.

Add Domain

caution

The ngrok URL changes every time you restart ngrok (unless you have a paid static-domain plan). You will need to re-register each new ngrok hostname in test-portal. If the domain is missing, the button still renders, but tapping it triggers 1003 FAILED_TO_VALIDATE_APPLE_PAY_SESSION in onError (merchant validation runs only after the click).

Step 3: Test the Apple Pay Express Checkout integration​

Open the ngrok HTTPS URL in a browser that supports Apple Pay. Walk through the Apple Pay sheet to authorize the payment: the SDK selects the appropriate authentication method (biometric or cross-device) for your browser and device automatically. Verify the scenarios:

  • The Apple Pay button renders inside your container.
  • onClick fires when the user taps the button.
  • The Apple Pay sheet shows your shippingMethods and asks for shipping contact / billing contact based on payload.
  • onShippingContactSelected fires when the user picks or changes the address: your handler updates the total / available methods.
  • onShippingMethodSelected fires when the user picks a shipping method: your handler updates the total.
  • onPaymentSuccess fires after a successful sandbox payment.
  • onCancel fires when the user dismisses the sheet.
  • onError fires on any failure: see Handling Error Codes.
note

The test device must be signed in to an Apple Sandbox tester account (the iCloud account, not your regular Apple ID), and a sandbox card must be added to Wallet. The exact menu paths differ between iOS, iPadOS and macOS versions, so follow Apple's sandbox testing guide for the current procedure.