Skip to main content

Create an Apple Pay Session

Overview​

Create an Apple Pay Session using the validation URL provided by Apple to receive the merchantSession object for payment processing on the web. This endpoint is required to enable Apple Pay on your website.

Resource Access​

  • User Permissions: All users can access this endpoint
  • Endpoint: POST /apple_pay_sessions

Arguments​

ParameterTypeRequiredDescription
display_namestringNoThe merchant name displayed in the Apple Pay sheet (e.g., "Ahrvo Network Test Merchant")
domainstringYesYour registered domain (e.g., "www.yourmerchant.com")
merchant_identitystringYesThe Merchant Identity ID
validation_urlstringYesThe validation URL provided by Apple during the payment flow

Example Request​

curl -X POST \
  'https://api.ahrvo.network/payments/na/apple_pay_sessions' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "display_name": "Acme Retail Store",
    "domain": "www.acmeretail.com",
    "merchant_identity": "IDmerchantExample123",
    "validation_url": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"
  }'

Example Response​

{
  "id": "APSapplePaySession789",
  "session_details": "{\"epochTimestamp\":1623847200000,\"expiresAt\":1623850800000,\"merchantSessionIdentifier\":\"SSH123456789\",\"nonce\":\"abc123def456\",\"merchantIdentifier\":\"merchant.com.acmeretail\",\"domainName\":\"www.acmeretail.com\",\"displayName\":\"Acme Retail Store\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQ...\"}",
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/apple_pay_sessions/APSapplePaySession789"
    }
  }
}

Implementation Flow​

  1. Register Your Domain: Register your domain with Apple through your Apple Developer account
  2. Apple Pay Button Click: User clicks the Apple Pay button on your website
  3. Request Validation URL: Apple provides a validation URL through the Apple Pay JS API
  4. Call This Endpoint: Send the validation URL to this endpoint to create a session
  5. Receive merchantSession: Get the session_details from the response
  6. Parse and Use: Parse the JSON string in session_details and pass it to Apple Pay JS to complete the session
  7. Process Payment: After the user authorizes, you'll receive a payment token to create a Payment Instrument

Example JavaScript Implementation​

// Step 1: User clicks Apple Pay button
const paymentRequest = {
  countryCode: 'US',
  currencyCode: 'USD',
  total: {
    label: 'Your Merchant Name',
    amount: '10.00'
  }
};

const session = new ApplePaySession(3, paymentRequest);

// Step 2: Handle validation
session.onvalidatemerchant = async (event) => {
  // Step 3: Call Ahrvo Network API to create session
  const response = await fetch('https://api.ahrvo.network/payments/na/apple_pay_sessions', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + btoa('username:password'),
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      display_name: 'Acme Retail Store',
      domain: 'www.acmeretail.com',
      merchant_identity: 'IDmerchantExample123',
      validation_url: event.validationURL
    })
  });
  
  const data = await response.json();
  
  // Step 4: Parse session details and complete validation
  const merchantSession = JSON.parse(data.session_details);
  session.completeMerchantValidation(merchantSession);
};

// Step 5: Handle payment authorization
session.onpaymentauthorized = async (event) => {
  // Create Payment Instrument with the token
  const paymentToken = event.payment.token;
  // ... process payment with token
};

session.begin();

Additional Information​

  • Domain Registration: Before using this endpoint, you must register and verify your domain with Apple in your Apple Developer account
  • Session Expiration: Apple Pay sessions are time-limited (typically 5 minutes). Create a new session for each payment attempt
  • Validation URL: The validation URL is provided by Apple during the payment flow and changes for each session
  • Session Details Format: The session_details field contains a JSON string (not a JSON object) that must be parsed before use
  • merchantSession Object: Contains:
    • merchantSessionIdentifier: Unique identifier for this session
    • nonce: Security token for this session
    • merchantIdentifier: Your Apple Merchant ID
    • domainName: Your registered domain
    • displayName: Name shown to the user
    • signature: Cryptographic signature from Apple
    • epochTimestamp and expiresAt: Session validity period
  • Security: The session validation ensures that:
    • Your domain is registered with Apple
    • The request is legitimate and not spoofed
    • The merchant is authorized to process Apple Pay payments
  • Testing: Use Apple's sandbox environment for testing before going live
  • Supported Browsers: Apple Pay on the web is supported in Safari on macOS and iOS
  • Certificate Management: Ahrvo Network manages the merchant certificates required for Apple Pay validation