Apple Pay Web Session

The Apple Pay Web Session API enables merchants to validate their domain with Apple Pay during the onvalidatemerchant event. This API is called when a customer initiates an Apple Pay transaction on a web page, and Apple Pay requires the merchant to prove their identity before allowing the payment to proceed.

The API returns a session object that must be passed to the completeMerchantValidation method to complete the Apple Pay Web validation process.

Integration Prerequisites

Before implementing Apple Pay Web Session validation, ensure you have:

• A valid Apple Pay merchant account with domain verification completed
• Apple Pay merchant certificate properly configured
• Access to the Onerway payment gateway API
• Implemented Apple Pay Web integration on your website
• Technical capability to handle asynchronous validation flows

Apple Pay Web Session Usage

Apple Pay Web Session validation is a critical step in the Apple Pay Web integration process:

1. Domain Validation: Proves your domain is authorized to accept Apple Pay payments
2. Security: Ensures only verified merchants can process Apple Pay transactions
3. Session Management: Provides temporary session data for completing Apple Pay authorization
4. Real-time Processing: Must be handled immediately when the onvalidatemerchant event is triggered

API Request Parameters

POST

Parameter	Type	Length	Required	Signed	Description
appId	String	20	Yes	Yes	Merchant application ID assigned by Onerway for website identification.
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
requestId	String	64	Yes	Yes	Unique request identifier for tracking and deduplication.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
verifyUrl	String	256	Yes	Yes	Apple Pay validation URL from the payment session event.
website	String	128	Yes	Yes	Merchant website domain name registered with Apple Pay.

Response

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

The data field contains a JSON string with Apple Pay session information:

Name	Type	Description
└─ data	String	Apple Pay merchant session data as JSON string. This data should be passed directly to the Apple Pay session completion handler.

Integration Process

The Apple Pay Web Session API is used within the Apple Pay Web integration flow:

Integration Steps

1. Initialize Apple Pay Session: Create an Apple Pay session on your web page
2. Handle Validation Event: Listen for the onvalidatemerchant event
3. Call Session API: Send the validation URL to Onerway's Apple Pay Web Session API
4. Complete Validation: Pass the returned session data to completeMerchantValidation
5. Continue Payment: Proceed with the Apple Pay payment flow

API Usage Examples

Request Example

Request

{
  "appId": "1727880846378401792",
  "merchantNo": "800209",
  "requestId": "ZYRDGXQSDEUMFFXVWEU",
  "sign": "c46ea8b12bcc3392a6b8a58207a71f634442a8ea650d7cdb97494e1ec5f413c9",
  "verifyUrl": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
  "website": "rundown-beret.biz"
}

Response

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": "{\"epochTimestamp\":1752027594903,\"expiresAt\":1752031194903,\"merchantSessionIdentifier\":\"SSHC70E8352BAB64DA1ABD5534864FB1D7D_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\"nonce\":\"493ee68c\",\"merchantIdentifier\":\"A719B735608A23CC132E86CF3C67E22C446673B495D53A28FD2FA671B5B86C87\",\"domainName\":\"rundown-beret.biz\",\"displayName\":\"rundown-beret.biz\",\"signature\":\"308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e43082038ba003020102020859d8a1bcaaf4e3cd300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3231303432303139333730305a170d3236303431393139333635395a30623128302606035504030c1f6563632d736d702d62726f6b65722d7369676e5f5543342d53414e44424f5831143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d030107034200048230fdabc39cf75e202c50d99b4512e637e2a901dd6cb3e0b1cd4b526798f8cf4ebde81a25a8c21e4c33ddce8e2a96c2f6afa1930345c4e87a4426ce951b1295a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604140224300b9aeeed463197a4a65a299e4271821c45300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020347003044022074a1b324db4249430dd3274c5074c4808d9a1f480e3a85c5c1362566325fbca3022069369053abf50b5a52f9f6004dc58aad6c50a7d608683790e0a73ad01e4ad981308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018830820184020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553020859d8a1bcaaf4e3cd300b0609608648016503040201a08193301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3235303730393032313935345a302806092a864886f70d010934311b3019300b0609608648016503040201a10a06082a8648ce3d040302302f06092a864886f70d010904312204206eea5fe324e35a0f4a87d568594a2334f3ad5e52ea2d1ad9b6de048605c83fda300a06082a8648ce3d04030204473045022100eff116376d607a5c43681ffe5ade91eafd5640723b8ff00a0a8f2b934f42d18e022059139c887992a14f6fa5fc61b3f3ba4ed454d1a295a6952d9068e561eb027f70000000000000\",\"operationalAnalyticsIdentifier\":\"rundown-beret.biz:A719B735608A23CC132E86CF3C67E22C446673B495D53A28FD2FA671B5B86C87\",\"retries\":0,\"pspId\":\"A719B735608A23CC132E86CF3C67E22C446673B495D53A28FD2FA671B5B86C87\"}"
}

JavaScript Integration Example

// Apple Pay Web integration example
const session = new ApplePaySession(3, paymentRequest);

session.onvalidatemerchant = async (event) => {
  try {
    // Call Onerway Apple Pay Web Session API
    const response = await fetch('/api/txn/apiCheckApplePay', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        appId: '1727880846378401792',
        merchantNo: '800209',
        requestId: generateRequestId(),
        sign: generateSignature(),
        verifyUrl: event.validationURL,
        website: window.location.hostname
      })
    });

    const result = await response.json();
    
    if (result.respCode === '20000') {
      // Parse the session data and complete validation
      const sessionData = JSON.parse(result.data);
      session.completeMerchantValidation(sessionData);
    } else {
      session.abort();
    }
  } catch (error) {
    console.error('Apple Pay validation failed:', error);
    session.abort();
  }
};

session.begin();

Common Error Scenarios

Invalid Domain Configuration

Error: Domain not registered with Apple Pay
Cause: The website parameter doesn't match a domain registered in your Apple Pay merchant configuration
Solution: Ensure your domain is properly registered and verified with Apple Pay

Expired Validation URL

Error: Apple Pay validation URL has expired
Cause: The verifyUrl from the onvalidatemerchant event has expired
Solution: Handle the validation request immediately when the event is triggered

Invalid Signature

Error: Request signature validation failed
Cause: The sign parameter is incorrect or generated with wrong parameters
Solution: Verify your signature generation process and ensure all parameters are included

Session Timeout

Error: Apple Pay session timeout
Cause: The merchant validation process took too long
Solution: Optimize your validation flow to complete within Apple Pay's timeout limits

Implementation Best Practices

1. Handle Validation Immediately: Call the API as soon as the onvalidatemerchant event is triggered
2. Secure Domain Registration: Ensure your domain is properly registered and verified with Apple Pay
3. Error Handling: Implement robust error handling for validation failures
4. Session Management: Use the returned session data immediately with completeMerchantValidation
5. Timeout Handling: Implement timeout handling for the validation process
6. Security: Always validate the signature and use HTTPS for all communications

Merchant Integration Checklist

• Domain registered and verified with Apple Pay
• Apple Pay merchant certificate configured
• onvalidatemerchant event handler implemented
• API integration with proper signature generation
• Error handling for validation failures
• Session timeout handling implemented
• HTTPS enabled for all Apple Pay interactions
• Testing completed in Apple Pay sandbox environment