PayUI Digital Wallets

Digital wallets are coming soon. This page explains the preparation steps and how wallets will behave once enabled.

PayUI will provide 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

Merchant Enablement: Ensure Card Not Present is enabled on your merchant account (when wallets are available)
Configuration: Include wallet types in your Payment Request (when enabled):

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

Automatic Display: PayUI detects device/browser capabilities and shows appropriate wallet buttons
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

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.