Apple Pay

Integration Prerequisites

1. Please provide your test environment domain to Onerway for Apple Pay domain registration. Without this, payment processing will fail.
2. Before testing Apple Pay, merchants must create a test account. Note: do not select Mainland China as the account region.
3. After creating the test account, bind a non-Mainland test card to the Apple test device.
4. Use the Apple Wallet app for card binding. If only domestic banks appear during card binding, change the Country and Region setting on your test device to a non-Mainland country such as the United States.

For detailed information, see Apple Pay Sandbox Testing Guide

API Request Parameters

POST

Important Note

Apple Pay supports both subscription and standard credit card payments:

• For standard credit card payments: Set subProductType: 'DIRECT' in the Payment Intent
  Creation request
• For subscription payments: Set subProductType: 'SUBSCRIBE' in the Payment Intent
  Creation request

SDK Integration Process

The Apple Pay integration process consists of three main phases as illustrated below:

1. Payment Intent Creation

In this phase:

• Client submits order information to the merchant server
• Merchant server sends a payment request to Onerway with transaction details including merchantNo, orderAmount, and txnOrderMsg parameters
• txnOrderMsg must contain returnUrl (for synchronous notification) and notifyUrl (for webhook notification)
• Onerway creates a transaction record and returns a transactionId and redirectUrl
• The initial transaction status is Unfinished (U)

2. SDK Payment Process

In this phase:

• Client loads the Onerway SDK JavaScript library
• Client initializes the SDK with the transactionId, redirectUrl and mode: 'ApplePay'
• SDK renders the Apple Pay button embedded in the merchant's website/app
• Customer clicks the Apple Pay button and completes payment through Apple's interface
• The payment result is returned directly without requiring 3DS verification in most cases

3. Payment Result Notification

In this phase:

• Synchronized notification:

  • SDK receives the transaction result and triggers the onPaymentCompleted or onError callback function
  • The callback provides essential result parameters including transactionId and status

• Asynchronous notification (webhook):

  • Simultaneously, Onerway sends detailed payment result data to the notifyUrl via HTTP POST
  • The webhook contains complete transaction information including transactionId, status, paymentMethod, walletTypeName, and signature for verification
  • Webhook data is more comprehensive than the synchronized notification and should be used as the source of truth

• Webhook acknowledgment:

  • Merchant server must respond with transactionId to acknowledge receipt of the webhook
  • If no successful response is received, Onerway will retry sending the webhook up to 3 times at 30-minute intervals
  • Implement idempotent processing to handle potential duplicate notifications

Apple Pay Configuration Options

Property	Type	Required	Description
applePayButtonType	String	No	defines the text that appears on the Apple Pay button. Refer to ApplePayButtonType
applePayButtonColor	String	No	Apple Pay button theme. Options: - black: Standard black button (default, highest contrast) - white: White button with black Apple Pay logo (for dark backgrounds) - white-outline: White button with a black outline and black Apple Pay logo (for complex backgrounds)
buttonWidth	String	No	Button width, e.g., 200px or 100%
buttonHeight	String	No	Button height, e.g., 40px
buttonRadius	String	No	Button border radius, e.g., 4px

Supported Locales

Apple Pay supports the following locales for localization:

Language Code	Language Name	Apple Pay Support	Google Pay Support
ar	Arabic	Yes	Yes
ca	Catalan	Yes	Yes
cs	Czech	Yes	Yes
da	Danish	Yes	Yes
de	German	Yes	Yes
el	Greek	Yes	Yes
en	English	Yes	Yes
es	Spanish	Yes	Yes
fi	Finnish	Yes	Yes
fr	French	Yes	Yes
hr	Croatian	Yes	Yes
id	Indonesian	Yes	Yes
it	Italian	Yes	Yes
ja	Japanese	Yes	Yes
ko	Korean	Yes	Yes
ms	Malay	Yes	Yes
no	Norwegian	Yes	Yes
nl	Dutch	Yes	Yes
pl	Polish	Yes	Yes
pt	Portuguese	Yes	Yes
ru	Russian	Yes	Yes
sk	Slovak	Yes	Yes
sv	Swedish	Yes	Yes
th	Thai	Yes	Yes
tr	Turkish	Yes	Yes
uk	Ukrainian	Yes	Yes
zh	Simplified Chinese	Yes	Yes
vi	Vietnamese	Yes	No
he	Hebrew	Yes	No
hi	Hindi	Yes	No
hu	Hungarian	No	Yes
ro	Romanian	No	Yes
zh-TW	Traditional Chinese	No	Yes
bg	Bulgarian	No	Yes
et	Estonian	No	Yes
sr	Serbian	No	Yes
sl	Slovenian	No	Yes

API Usage Examples

Request

{
    "billingInformation": "{\"address\":\"824 Blind Lane\",\"city\":\"North Ameliaside\",\"country\":\"US\",\"email\":\"john.doe@example.com\",\"firstName\":\"John\",\"identityNumber\":\"14364522468\",\"lastName\":\"Doe\",\"phone\":\"18057477053\",\"postalCode\":\"12308-1270\",\"province\":\"CO\"}",
    "merchantCustId": "CustId-I5PE-DN25",
    "merchantNo": "800209",
    "merchantTxnId": "apay-195307a0-f5de-4e9d-ad3d-faf1c6ac9d10",
    "merchantTxnTime": "2025-05-05 13:14:23",
    "orderAmount": "35.99",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"259 Wilton Street\",\"city\":\"Denaton\",\"country\":\"US\",\"email\":\"john.doe@example.com\",\"firstName\":\"John\",\"identityNumber\":\"20373861755\",\"lastName\":\"Doe\",\"phone\":\"15690923060\",\"postalCode\":\"29150-8270\",\"province\":\"CO\"}",
    "sign": "698917d17492a3205ccff0d030d84cc6fef9ab903edf50998560cc374f3b419c",
    "subProductType": "DIRECT",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"16384\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"iPhone Case\\\",\\\"num\\\":\\\"1\\\",\\\"price\\\":\\\"35.99\\\",\\\"type\\\":\\\"accessory\\\"}]\",\"returnUrl\":\"https://merchant-site.com/return\",\"notifyUrl\":\"https://merchant-site.com/webhook\",\"screenHeight\":\"780\",\"screenWidth\":\"320\",\"timeZoneOffset\":\"-660\",\"transactionIp\":\"158.63.117.41\",\"userAgent\":\"Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.0 Mobile/15E148 Safari/604.1\"}",
    "txnType": "SALE"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1919259367895859200", // Use this for SDK initialization
        "responseTime": "2025-05-05 13:14:26",
        "txnTime": null,
        "txnTimeZone": "+08:00",
        "orderAmount": "35.99",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "U",
        "redirectUrl": "https://sandbox-checkout-sdk.onerway.com", // Use this for SDK initialization
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "subscriptionManageUrl": null,
        "sign": "119a387fb282fe9d8eb82f86a4287e582bc833a71bdd42767be665be031964d8"
    }
}

SDK Initialization

After receiving the transactionId and redirectUrl from the Payment Intent Creation API, initialize the SDK with the following steps:

// Import the Onerway SDK script
const script = document.createElement('script');
script.src = 'https://checkout-sdk.onerway.com/v3/';
document.body.appendChild(script);

// Create container for SDK rendering
const container = document.createElement('div');
container.id = 'onerway_checkout';
document.body.appendChild(container);

// Initialize the SDK with Apple Pay configuration
script.onload = function() {
  const transactionId = '1919259367895859200'; // From payment intent creation response
  const redirectUrl = 'https://sandbox-checkout-sdk.onerway.com'; // From payment intent creation response
  
  const pacypay = new Pacypay(transactionId, {
    container: 'onerway_checkout', // Container ID for SDK rendering
    locale: 'en',                  // Language preference
    environment: 'sandbox',        // 'sandbox' or 'production'
    mode: 'ApplePay',              // Must be 'ApplePay' for Apple Pay transactions
    redirectUrl: redirectUrl,      // From payment intent creation response
    config: {
      applePayButtonType: 'buy',   // Button type: 'add-money', 'book', 'buy', etc.
      applePayButtonColor: 'black', // Button color: 'black', 'white', 'white-outline'
      buttonWidth: '100%',          // Button width
      buttonHeight: '44px',         // Button height
      buttonRadius: '4px',          // Button border radius
    },
    onPaymentCompleted: function(result) {
      // Handle payment result
      const paymentData = result.data;
      const respCode = result.respCode;
      const respMsg = result.respMsg;
      
      if(respCode === '20000') {
        switch(paymentData.status) {
          case 'S': // Success
            console.log('Payment successful');
            // Update UI, redirect to success page, etc.
            break;
          case 'F': // Failure
            console.log('Payment failed');
            // Show error message, offer retry option, etc.
            break;
          default:
            console.log('Unexpected status:', paymentData.status);
        }
      } else {
        console.error('Error processing payment:', respMsg);
      }
    },
    onError: function(error) {
      console.error('SDK error:', error);
      // Handle SDK initialization errors
    }
  });
};

SDK Callback Responses

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919315843586850816",
    "responseTime": "2025-05-05 16:59:18",
    "txnTime": "2025-05-05 16:58:50",
    "txnTimeZone": "+08:00",
    "orderAmount": "10.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "S", // Successful payment
    "redirectUrl": null,
    "contractId": null,
    "tokenId": null,
    "eci": "05",
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": null,
    "subscriptionManageUrl": null,
    "sign": "5a1b0c3d2e4f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
  }
}

Webhook Notifications

{
  "notifyType": "TXN", 
  "transactionId": "1925132987104890880", 
  "txnType": "SALE", 
  "merchantNo": "800259",
  "merchantTxnId": "G_jN_p_xBdNWhrAE0Co6dQQ5whaYl1Oh07",
  "responseTime": "2025-05-21 18:14:23",
  "txnTime": "2025-05-21 18:14:06",
  "txnTimeZone": "+08:00",
  "orderAmount": "5.00",
  "orderCurrency": "USD",
  "status": "S", 
  "cardBinCountry": "NZ",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "7bd1c8fd54c86873f7c9c70e77d968d5725ac85ccc8b6938f2c2dc74a0c917bd",
  "paymentMethod": "VISA", 
  "walletTypeName": "ApplePay", 
  "channelRequestId": "8002591925133054498705409"
}

Implementation Best Practices

1. Domain Registration: Always register your domain with Apple Pay through Onerway before implementation
2. Testing: Test thoroughly in a sandbox environment before going to production
3. Error Handling: Implement robust error handling for a smooth user experience
4. Device Detection: Only show Apple Pay as an option on compatible devices
5. Transaction Verification: Always verify transaction results through webhook notifications
6. Region Considerations: Be aware that Apple Pay availability varies by region
7. Button Placement: Follow Apple's Human Interface Guidelines for optimal button placement
8. Button Sizing: Use Apple's recommended height of 44px for optimal tappability on mobile devices

Webhook Notifications

Apple Pay transactions generate the same webhook notifications as standard card payments. For detailed information about webhook structure and processing, refer to the Webhook Notification Documentation.

Troubleshooting

If you encounter issues with Apple Pay integration:

1. Domain Verification: Ensure your domain is properly registered with Apple Pay through Onerway
2. Device Compatibility: Verify the test devices meet Apple Pay requirements
3. Test Cards: Confirm you're using valid test cards from non-mainland regions
4. Browser Support: Test with Safari on compatible iOS or macOS devices
5. Error Logs: Check browser console for JavaScript errors during SDK initialization
6. Redirect URL: Ensure the redirect URL parameter matches the one from the doTransaction response
7. Transaction Status: Always verify payment status through server-side webhook notifications

For additional assistance, contact Onerway support with your merchant ID and transaction details.