PayUI Digital Wallets

PayUI provides pre-integrated digital wallet support for Apple Pay and Google Pay. Wallet buttons will appear automatically when available, but your merchant account must have Card Not Present enabled, and Apple Pay requires domain registration before it can be used on your site.

How It Works

1. Merchant Enablement: Ensure Card Not Present is enabled on your merchant account
2. Configuration: Include wallet types in your Payment Request:

{
    "paymentMethods": [
        "card",
        "apple_pay",
        "google_pay"
    ]
}

3. Automatic Display: PayUI detects device/browser capabilities and shows appropriate wallet buttons
4. Seamless Processing: Wallet payments are processed automatically like card payments

Google Pay

The Google Pay button appears when:

• The browser supports the Google Pay API
• The user has a valid payment method in their Google Pay wallet
• google_pay is included in the Payment Request’s paymentMethods
• Your merchant account has Card Not Present enabled

Google Pay requires no additional integration, setup, or domain registration. Simply include google_pay in the paymentMethods array of your Payment Request:

{
    "paymentMethods": ["card", "google_pay"],
    "payment": {
        "amount": 100
    }
}

Apple Pay

The Apple Pay button appears when:

• The browser is Safari on a supported Apple device
• The user has a valid card in their Apple Wallet
• apple_pay is included in the Payment Request’s paymentMethods
• Your merchant account has Card Not Present enabled
• Your domain has been registered for Apple Pay (see below)

Apple Pay Domain Registration

Before Apple Pay can be used on your website, you must register your domain with Apple. This is a one-time setup per domain.

Domains must be Fully Qualified Domain Names (FQDN) (for example yourdomain.com or checkout.yourdomain.com).

Notes:

• Register every domain/subdomain that will host the PayUI checkout page.
• Do not include https://, paths, or ports in the domain value.
• Maximum 50 domains per merchant account (and maximum 50 domains per request).

Step 1: Host the Domain Association File

Download the Apple Pay domain association file and host it at:

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

Important: The file must be accessible via HTTPS and served with Content-Type: text/plain or application/octet-stream.

Quick checklist:

• The URL returns HTTP 200 (no redirects).
• The file contents are served as-is (no HTML wrapping).
• The path is exactly /.well-known/apple-developer-merchantid-domain-association.

Example verification (from your machine):

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

You should see HTTP/1.1 200 and the file contents in the response body.

Step 2: Register Your Domain

POST /management/applepaydomains
Content-Type: application/json
X-Api-Key: {your-api-key}

{
    "domains": [
        "yourdomain.com",
        "checkout.yourdomain.com"
    ]
}

Example request (curl):

curl -X POST "https://sandbox.api.gpaunz.com/management/applepaydomains" \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -d '{
        "domains": [
            "yourdomain.com",
            "checkout.yourdomain.com"
        ]
    }'

Tip: If Apple cannot retrieve the .well-known file for a domain, registration will fail. Verify Step 1 again (HTTPS, 200 OK, no redirects).

Managing Domains

Endpoint	Method	Description
/management/applepaydomains	GET	List all registered domains
/management/applepaydomains	POST	Register new domains (up to 50 total)
/management/applepaydomains	DELETE	Remove registered domains

Example: list domains

curl -X GET "https://sandbox.api.gpaunz.com/management/applepaydomains" \
    -H "X-Api-Key: YOUR_API_KEY"

Example: delete domains

curl -X DELETE "https://sandbox.api.gpaunz.com/management/applepaydomains" \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: YOUR_API_KEY" \
    -d '{
        "domains": [
            "checkout.yourdomain.com"
        ]
    }'

Common Errors

Error	Cause	Solution
Domain verification failed	File not found at .well-known path	Ensure file is hosted and accessible via HTTPS
Status code 500	Apple couldn’t fetch the file	Check firewall rules, SSL certificate validity

Wallet Payment Handling

When wallets are enabled, PayUI handles wallet payment processing automatically. From your integration perspective, wallet payments work identically to card payments — listen for the same process event, which returns the same payload structure regardless of payment method.