Apple Pay Web Integration

1. Overview

This document describes how external merchants integrate Apple Pay on the Web through UseePay.

For this Apple Pay API integration, the correct payment flow is:

Frontend gets Apple Pay token from ApplePaySession

Frontend sends token and order data to merchant backend

Merchant backend directly calls paymentIntents()->create(...)

Merchant backend sends:
payment_method_data.type = apple_pay
payment_method_data.apple_pay.encrypted_payment_data = Apple Pay token
confirm = true
auto_capture = true

This flow does not require frontend to create a PaymentIntent first.

2. Roles

Merchant frontend is responsible for:

Loading Apple Pay Web SDK

Checking Apple Pay availability

Getting Apple Pay configuration from merchant backend

Starting ApplePaySession

Sending merchant validation request to merchant backend

Sending Apple Pay token and order data to merchant backend

Merchant backend is responsible for:

Returning Apple Pay configuration

Completing merchant validation through UseePay

Receiving Apple Pay token and order data

Directly creating and confirming payment through UseePay

UseePay is responsible for:

Returning Apple Pay configuration

Returning Apple merchant session

Processing Apple Pay token during payment creation

3. High-Level Flow

1. Frontend loads Apple Pay SDK
2. Frontend calls merchant backend to get Apple Pay configuration
3. Frontend checks Apple Pay availability
4. Frontend creates ApplePaySession
5. Frontend calls merchant backend for merchant validation
6. User authorizes payment in Apple Pay sheet
7. Frontend receives Apple Pay token
8. Frontend sends token + order data to merchant backend
9. Merchant backend calls paymentIntents.create(...)
10. Merchant backend sets confirm=true and auto_capture=true
11. Frontend completes Apple Pay session with success or failure

4. Prerequisites

Before integration:

Apple Pay must be enabled for the UseePay merchant account

Apple Pay merchant identifier must be configured

Domain verification must be completed

Payment page must use HTTPS

Testing must be done in Safari on macOS or iOS

Wallet must contain an active supported card

5. Frontend Preparation

5.1 Load Apple Pay SDK

Merchant page should load Apple official SDK directly:

5.2 Prepare Apple Pay container

5.3 Check availability on page load

6. Merchant Backend APIs

Merchant backend should expose these APIs to frontend:

POST /api/payment/apple-pay/configuration

POST /api/payment/apple-pay/validate

POST /api/payment

Their responsibilities are:

POST /api/payment/apple-pay/configuration
Get Apple Pay configuration

POST /api/payment/apple-pay/validate
Get Apple merchant session

POST /api/payment
Receive Apple Pay token and directly create + confirm payment

7. UseePay APIs Used by Merchant Backend

Merchant backend will call:

POST /api/v1/payment_method_configurations

POST /api/v1/payment_methods/apple_pay/merchant_session

paymentIntents()->create()

Environment base URLs:

Production: https://openapi.useepay.com

UAT: https://openapi1.uat.useepay.com

8. Step 1: Get Apple Pay Configuration

8.1 Frontend example

8.2 Merchant backend -> UseePay

Request example:

{
  "currency": "USD",
  "host": "demo.example.com",
  "merchant_name": "Your Store Name",
  "os_type": "WEB",
  "amount": 31.58
}

9. Step 2: Build ApplePayPaymentRequest

10. Step 3: Start ApplePaySession

11. Step 4: Merchant Validation

11.1 Frontend example

11.2 Merchant backend -> UseePay

Converted request example:

{
  "display_name": "Your Store Name",
  "host": "demo.example.com",
  "merchant_identifier": "merchant.com.example.useepay",
  "merchant_id": "5000000000xxxxx",
  "validationURL": "https://apple-pay-gateway.apple.com/paymentservices/startSession"
}

12. Step 5: Receive Apple Pay Token and Submit Payment

This is the key step.

After frontend receives Apple Pay token, it should directly send token and order data to merchant backend.
Merchant backend then directly creates and confirms the payment.

12.1 Frontend example

12.2 Payment request example

{
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "phone": "+1 3235550123",
  "shippingAddress": {
    "address": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zipCode": "90001",
    "country": "US"
  },
  "billingAddress": {
    "address": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zipCode": "90001",
    "country": "US"
  },
  "paymentMethods": ["apple_pay"],
  "items": [
    {
      "name": "Product A",
      "description": "Product description",
      "price": 19.99,
      "quantity": 1
    }
  ],
  "totals": {
    "subtotal": "19.99",
    "shipping": "9.99",
    "tax": "1.60",
    "totalAmount": "31.58",
    "currency": "USD"
  },
  "payment_method_data": {
    "type": "apple_pay",
    "apple_pay": {
      "merchant_identifier": "merchant.com.example.useepay",
      "encrypted_payment_data": {
        "version": "EC_v1",
        "data": "...",
        "signature": "...",
        "header": {
          "ephemeralPublicKey": "...",
          "publicKeyHash": "...",
          "transactionId": "..."
        }
      }
    }
  }
}

13. Step 6: Merchant Backend Directly Creates and Confirms Payment

Merchant backend processing logic:

1. Receive order data and payment_method_data from frontend
2. Verify payment_method_data.type == "apple_pay"
3. Read merchant_identifier
4. Read encrypted_payment_data
5. Build payment create parameters
6. Set payment_method_data.type = "apple_pay"
7. Set payment_method_data.apple_pay.encrypted_payment_data
8. Set confirm = true
9. Set auto_capture = true
10. Call UseePay paymentIntents.create(paymentParams)
11. Return create result to frontend

Create parameters example:

paymentParams = {
  amount: 31.58,
  currency: "USD",
  merchant_order_id: "ORD_1710000000_1234",
  return_url: "https://merchant.example.com/payment/callback",
  order: ...,
  customer: ...,
  device_data: ...,
  payment_method_types: ["apple_pay"],
  payment_method_data: {
    type: "apple_pay",
    billing: ...,
    apple_pay: {
      merchant_identifier: "merchant.com.example.useepay",
      encrypted_payment_data: ...
    }
  },
  confirm: true,
  auto_capture: true
}

This is the backend call that actually uses the Apple Pay token.

14. Payment Result Handling

Success:

Failure:

15. Recommended Backend Response Format

Success example:

{
  "success": true,
  "data": {
    "id": "pi_xxx",
    "status": "succeeded",
    "merchant_order_id": "ORD_xxx"
  },
  "timestamp": "2026-03-20T10:00:00+08:00"
}

Error example:

{
  "success": false,
  "data": {
    "error": {
      "message": "Payment creation failed",
      "code": 400
    }
  },
  "timestamp": "2026-03-20T10:00:00+08:00"
}

16. Common Mistakes

16.1 Wrong payment flow

Wrong:

Create PaymentIntent first

Receive Apple Pay token

Confirm an existing PaymentIntent

Correct:

Receive Apple Pay token

Directly call merchant backend /api/payment

Merchant backend directly calls paymentIntents.create(...)

Merchant backend sets confirm=true and auto_capture=true

16.2 Wrong token field

Always use:

{
  "payment_method_data": {
    "type": "apple_pay",
    "apple_pay": {
      "merchant_identifier": "...",
      "encrypted_payment_data": {}
    }
  }
}

16.3 Merchant validation mismatch

Check:

domainName

merchantIdentifier

domain verification status

UAT vs production environment

17. Integration Checklist

Load Apple official SDK in merchant page

Prepare Apple Pay button area

Backend supports POST /api/payment/apple-pay/configuration

Backend supports POST /api/payment/apple-pay/validate

Backend supports POST /api/payment

Frontend gets merchant session successfully

Frontend receives Apple Pay token successfully

Frontend sends token and order data to /api/payment

Backend directly creates payment successfully

10.

Backend sets confirm=true and auto_capture=true

18. Summary

The correct Apple Pay API integration flow is:

Get Apple Pay configuration

Open Apple Pay

Validate merchant

Receive Apple Pay token

Send token + order data to merchant backend

Backend directly calls paymentIntents.create(...)

Backend sets confirm=true and auto_capture=true

The key point is:

Apple Pay token is used in payment creation

The backend directly creates and confirms payment in one call

Apple Pay Web Integration (API Integration)

Apple Pay Web Integration#

1. Overview#

2. Roles#

3. High-Level Flow#

4. Prerequisites#

5. Frontend Preparation#

5.1 Load Apple Pay SDK#

5.2 Prepare Apple Pay container#

5.3 Check availability on page load#

6. Merchant Backend APIs#

7. UseePay APIs Used by Merchant Backend#

8. Step 1: Get Apple Pay Configuration#

8.1 Frontend example#

8.2 Merchant backend -> UseePay#

9. Step 2: Build ApplePayPaymentRequest#

10. Step 3: Start ApplePaySession#

11. Step 4: Merchant Validation#

11.1 Frontend example#

11.2 Merchant backend -> UseePay#

12. Step 5: Receive Apple Pay Token and Submit Payment#

12.1 Frontend example#

12.2 Payment request example#

13. Step 6: Merchant Backend Directly Creates and Confirms Payment#

14. Payment Result Handling#

15. Recommended Backend Response Format#

16. Common Mistakes#

16.1 Wrong payment flow#

16.2 Wrong token field#

16.3 Merchant validation mismatch#

17. Integration Checklist#

18. Summary#

Apple Pay Web Integration

1. Overview

2. Roles

3. High-Level Flow

4. Prerequisites

5. Frontend Preparation

5.1 Load Apple Pay SDK

5.2 Prepare Apple Pay container

5.3 Check availability on page load

6. Merchant Backend APIs

7. UseePay APIs Used by Merchant Backend

8. Step 1: Get Apple Pay Configuration

8.1 Frontend example

8.2 Merchant backend -> UseePay

9. Step 2: Build ApplePayPaymentRequest

10. Step 3: Start ApplePaySession

11. Step 4: Merchant Validation

11.1 Frontend example

11.2 Merchant backend -> UseePay

12. Step 5: Receive Apple Pay Token and Submit Payment

12.1 Frontend example

12.2 Payment request example

13. Step 6: Merchant Backend Directly Creates and Confirms Payment

14. Payment Result Handling

15. Recommended Backend Response Format

16. Common Mistakes

16.1 Wrong payment flow

16.2 Wrong token field

16.3 Merchant validation mismatch

17. Integration Checklist

18. Summary