Local Development and Testing Setup

This guide shows how to test the DNA Payments Apple Pay 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 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.

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 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.
• 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.