Apple Pay Integration with Neolink Payment Gateway

Table of Contents

1. Introduction
2. Branding & Trademark Usage
3. Integration Options
4. Hosted Payment Page Integration
5. Server-to-Server API Integration
6. 3D Secure Authentication
7. Testing Your Integration
8. Troubleshooting
9. Additional Resources

Introduction

This document provides comprehensive guidance for integrating Apple Pay with the Neolink payment gateway. Apple Pay offers a secure, fast payment method that improves conversion by allowing customers to check out without manually entering card details.

Before proceeding with integration, please review these Apple Pay documents:

• Agreements and Guidelines for Apple Developers
• Apple Pay Acceptable Use Guidelines

Neolink payment gateway supports the following features with Apple Pay:

• Card payments via Visa, Mastercard, and American Express networks
• In-app and web-based implementations
• Both hosted checkout and direct API integration methods

Branding & Trademark Usage

When integrating Apple Pay into your website or application, you must adhere to Apple's branding requirements:

• Use the official Apple Pay mark and buttons as provided in the Apple Pay Marketing Guidelines
• Do not modify the Apple Pay button or logo colors, proportions, or appearance
• Maintain appropriate clear space around the Apple Pay button
• Use only approved button variations (black, white, or outlined with proper height-to-width ratio)

Correct usage examples:

• "Pay with Apple Pay"
• "Apple Pay is now available at checkout"

Incorrect usage examples:

• "Pay with ApplePay" (missing space)
• "APay is now available" (using unofficial shorthand)

Official Button Implementation

When displaying the Apple Pay button in your checkout flow, use the official assets:

<!-- Example of proper Apple Pay button implementation -->
<button type="button" class="apple-pay-button apple-pay-button-black">
  <!-- No text needed; the Apple Pay logo is part of the button style -->
</button>

<style>
  .apple-pay-button {
    display: inline-block;
    -webkit-appearance: -apple-pay-button;
    -apple-pay-button-type: plain;
    -apple-pay-button-style: black;
    height: 48px;
    width: 240px;
  }
  .apple-pay-button-black {
    -apple-pay-button-style: black;
  }
</style>

For detailed branding requirements, consult the Apple Pay Identity Guidelines.

Integration Options

Neolink offers two methods for integrating Apple Pay:

1. Hosted Payment Page Integration: Simplest option with minimal setup, where Neolink handles the Apple Pay button display and transaction processing
2. Server-to-Server API Integration: Advanced option providing more control over the checkout experience, requiring direct implementation of Apple Pay JS API

The table below compares these integration methods:

Feature	Hosted Payment Page	Server-to-Server API
Implementation complexity	Low	High
Apple Pay button hosting	Neolink	Merchant
Apple Pay JS API implementation	Not required	Required
3DS handling	Not required	Not required
Customization	Limited	Full control
Apple Developer account required	No	Yes
Domain verification required	No	Yes

Hosted Payment Page Integration

The hosted payment page option is the simplest way to implement Apple Pay, as Neolink handles all Apple Pay integration details.

Integration Steps

1. Request Apple Pay activation: Request Apple Pay activation for your account
2. Implement standard payment page flow: Use the standard Neolink payment page integration
3. No additional code required: The Apple Pay button will automatically appear for supported browsers/devices

Payment Flow

1. Customer initiates purchase on your website
2. Your server creates an order via Neolink API
3. Customer is redirected to the Neolink payment page
4. If the customer's device supports Apple Pay, the button appears automatically
5. Customer selects Apple Pay and completes the payment
6. Customer is redirected back to your website with payment result

Code Example

Create a payment session using the standard Neolink API:

POST /orders/create HTTP/1.1
Authorization: Basic cHJvamVjdDpwYXNzd29yZA==
Content-Type: application/json

{
  "amount": "99.99",
  "currency": "USD",
  "description": "Order #12345",
  "options": {
    "apple_pay_enabled": 1
  }
}

Response:

Location: https://checkout.neolink.io/pay/23014805213622230
Content-Type: application/json

{
  "orders": [
    {
      "id": "23014805213622230",
      "status": "new",
      "amount": "99.99",
      "amount_charged": "0.00",
      "amount_refunded": "0.00",
      "currency": "USD",
      "description": "Order #12345",
      "merchant_order_id": null,
      "created": "2016-08-22 15:39:42",
      "updated": "2016-08-22 15:39:42",
      "card": {},
      "client": {},
      "custom_fields": {},
      "issuer": {},
      "location": {},
      "operations": [],
      "secure3d": {}
    }
  ]
}

The Location header contains the URL where the customer should be redirected to complete the payment.

Note: The Authorization header contains Base64-encoded credentials in the format project:password. In this example, "cHJvamVjdDpwYXNzd29yZA==" is the Base64 encoding of "project:password".

The apple_pay_enabled parameter ensures Apple Pay is available when supported.

Server-to-Server API Integration

The Server-to-Server integration provides complete control over the checkout experience but requires implementing the Apple Pay JS API directly.

Prerequisites

1. Apple Developer Account: You need an Apple Developer account to register your merchant ID
2. Merchant ID: Register a merchant ID with Apple and provide it to the gateway
3. Merchant ID Certificate: Generate and register a merchant ID certificate (keep private - not provided to gateway)
4. Payment Processing Certificate: Generate and register a payment processing certificate and provide the private key to the gateway to decrypt tokens
5. Domain Verification: Verify your domain with Apple
6. Request API access: Request API access to get your gateway merchant ID

Integration Steps

1. Configure Apple Pay JS: Set up the Apple Pay JS API on your website/app

2. Set up payment request:

   const paymentRequest = {
     countryCode: 'US',
     currencyCode: 'USD',
     supportedNetworks: ['visa', 'masterCard', 'amex'],
     merchantCapabilities: ['supports3DS'],
     total: {
       label: 'Your Company Name',
       amount: '99.99'
     }
   };

3. Create payment session:

   const session = new ApplePaySession(3, paymentRequest);
   
   session.onvalidatemerchant = (event) => {
     // Validate the merchant session with your server
     fetch('/validate-merchant', {
       method: 'POST',
       headers: {'Content-Type': 'application/json'},
       body: JSON.stringify({validationURL: event.validationURL})
     })
     .then(res => res.json())
     .then(merchantSession => {
       session.completeMerchantValidation(merchantSession);
     });
   };
   
   session.onpaymentauthorized = (event) => {
     // Send the payment token to your server
     fetch('/process-apple-pay', {
       method: 'POST',
       headers: {'Content-Type': 'application/json'},
       body: JSON.stringify({
         token: event.payment.token,
         amount: '99.99'
       })
     })
     .then(res => res.json())
     .then(result => {
       if (result.success) {
         session.completePayment(ApplePaySession.STATUS_SUCCESS);
       } else {
         session.completePayment(ApplePaySession.STATUS_FAILURE);
       }
     });
   };
   
   session.begin();

4. Handle payment token: Send the encrypted Apple Pay token to Neolink API

5. Process the payment: Use the token_pay endpoint to complete the transaction

Apple Pay Button Implementation

// Check if Apple Pay is available
if (window.ApplePaySession && ApplePaySession.canMakePayments()) {
  const applePayButton = document.getElementById('apple-pay-button');
  applePayButton.style.display = 'block';
  
  applePayButton.addEventListener('click', () => {
    // Start the Apple Pay session as shown above
    const session = new ApplePaySession(3, paymentRequest);
    // Configure session handlers
    session.begin();
  });
}

Payment Processing

When a customer selects Apple Pay, send the payment token to your server, then forward it to Neolink:

// On your server
app.post('/process-apple-pay', (req, res) => {
  const { token } = req.body;
  
  // Base64 encode the entire Apple Pay token as required by the gateway
  const encodedToken = Buffer.from(JSON.stringify(token)).toString('base64');
  
  // Forward to Neolink API
  // Note: Your API endpoint may vary based on your specific integration
  const response = await fetch('https://api.neolink.io/orders/token_pay', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic cHJvamVjdDpwYXNzd29yZA==', // Base64 encoded "project:password"
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: '99.99',
      currency: 'USD',
      description: 'Order #12345',
      payment_type: 'card',
      dsrp: {
        type: 'apple_pay',
        token: encodedToken // Send base64 encoded Apple Pay token
      },
      client: {
        phone: '+1234567890',
        zip: 12345,
        name: 'Customer Name',
        city: 'City',
        email: '[email protected]',
        country: 'USA',
        address: 'Customer Address',
        login: 'customer_login'
      },
      location: {
        ip: customerIpAddress
      }
    })
  });
  
  // Handle response
});

API Request Example

Based on the gateway documentation, the token should be base64 encoded:

curl -X POST -H 'Authorization: Basic cHJvamVjdDpwYXNzd29yZA==' \
  -H 'Content-Type: application/json' \
  'https://api.neolink.io/orders/token_pay' \
  --data '{
    "amount": "100",
    "currency": "USD",
    "description": "Pay for cinema",
    "payment_type": "card",
    "dsrp": {
      "type": "apple_pay",
      "token": "BASE64_ENCODED_APPLE_PAY_TOKEN"
    },
    "client": {
      "phone": "+18961234545",
      "zip": 152589,
      "name": "Fox",
      "city": "City",
      "email": "[email protected]",
      "country": "USA",
      "address": "Some address",
      "login": "foo"
    },
    "location": {
      "ip": "6.6.6.6"
    }
  }'

JSON format:

{
  "amount": "100",
  "currency": "USD",
  "description": "Pay for cinema",
  "payment_type": "card",
  "dsrp": {
    "type": "apple_pay",
    "token": "BASE64_ENCODED_APPLE_PAY_PAYMENT_DATA"
  },
  "client": {
    "phone": "+18961234545",
    "zip": 152589,
    "name": "Fox",
    "city": "City",
    "email": "[email protected]",
    "country": "USA",
    "address": "Some address",
    "login": "foo"
  },
  "location": {
    "ip": "6.6.6.6"
  }
}

Note: Your API endpoint may be different based on your specific integration. The endpoint could be like api.{domain}.com. Your specific endpoints will be provided during the onboarding process.

3D Secure Authentication

3D Secure (3DS) enhances payment security and may be required depending on the card type used with Apple Pay.

3DS with Apple Pay

Apple Pay incorporates strong authentication through biometrics (Face ID or Touch ID), which satisfies the Strong Customer Authentication (SCA) requirements. The built-in security features of Apple Pay eliminate the need for additional 3DS authentication:

1. Hosted Payment Page: No additional 3DS steps required
2. Server-to-Server API: No additional 3DS implementation needed

Token Processing with Apple Pay

When processing Apple Pay tokens, the Neolink API handles all necessary security validations automatically.

Important: The gateway expects the entire Apple Pay token to be base64 encoded. Send the complete token structure received from the client to the gateway after base64 encoding.

Complete Apple Pay Token Structure (from client):

{
  "paymentData": {
    "data": "encrypted_payment_data...",
    "signature": "signature_data...",
    "header": {
      "publicKeyHash": "hash_value",
      "ephemeralPublicKey": "public_key",
      "transactionId": "transaction_id"
    },
    "version": "EC_v1"
  },
  "paymentMethod": {
    "displayName": "MasterCard 5961",
    "network": "MasterCard",
    "type": "debit"
  },
  "transactionIdentifier": "transaction_id"
}

Encode the Entire Token: The entire token structure above should be base64 encoded before sending to the gateway.

The API response will typically include the payment status and order details:

{
  "orders": [{
    "id": "60391976929806541",
    "status": "authorized",
    "secure3d": {
      "dsrp": "1",
      "dsrp_type": "apple_pay",
      "scenario": "none",
      "eci": "5"
    },
    "amount": "99.99",
    "currency": "USD",
    "description": "Order #12345"
  }]
}

Note: Your API endpoint may be different based on your specific integration. The endpoint could be like api.{domain}.com. Your specific endpoints will be provided during the onboarding process.

The response will indicate that the payment was processed using Apple Pay's built-in security features, with no additional 3DS steps required.

Testing Your Integration

Before going live, thoroughly test your Apple Pay integration using a combination of Apple's sandbox environment and Neolink's testing tools.

Apple Pay Sandbox Environment

Apple provides a sandbox environment for testing Apple Pay integrations:

1. Use Apple's test environment: Set up your integration to use the Apple Pay sandbox
2. Test cards: Use Apple's test cards for the sandbox environment
3. Test on supported devices: Test on actual iOS devices or Safari on macOS

Testing Process

When testing your Apple Pay integration with Neolink, follow this approach:

1. UI and Payment Flow Testing:

   • Test the Apple Pay button display and styling
   • Verify the payment sheet appears correctly
   • Test the user experience flow
   • Confirm that tokenized payment data is received by your server

2. End-to-End Testing:

   • Process the tokens generated from Apple's sandbox through Neolink's test environment
   • Test various payment scenarios including authorization, charging, and refunds
   • Once your integration is approved for production, conduct final testing with real cards

Testing Steps

1. Configure test environment: Set up your integration to use Apple's sandbox environment
2. Test merchant validation: Verify your server can validate the merchant session
3. Test payment flow: Ensure the payment sheet displays correctly
4. Test token handling: Verify your server correctly receives and processes the payment tokens
5. Test error handling: Verify your application gracefully handles different response scenarios
6. Complete integration checklist: Verify all items in Apple's integration requirements before going live

Troubleshooting

If you encounter issues during testing:

1. Verify your Apple Developer account is properly configured
2. Ensure your domain is verified with Apple
3. Check that your payment processing certificate is valid
4. Verify the merchant ID is correctly configured
5. Review API responses for specific error messages

For persistent issues, contact Neolink support.

Troubleshooting

Common Issues

Issue	Possible Cause	Solution
Apple Pay button not displaying	Device/browser not supported	Check if the device and browser support Apple Pay (Safari on iOS/macOS)
"Payment method not supported" error	Incorrect card network configuration	Ensure you're requesting supported networks (Visa, Mastercard, etc)
Merchant validation fails	Incorrect merchant configuration	Verify domain verification and merchant ID setup
Payment declined	Test card or incorrect amount format	Check card details and ensure amount is formatted correctly
3DS authentication fails	Incorrect 3DS implementation	Review 3DS flow implementation
Token_pay API errors	Malformed request	Verify all required parameters are included and formatted correctly

Error Response Examples

{
  "failure_type": "validation",
  "failure_message": "Validation failed",
  "order_id": null
}

For persistent issues, contact Neolink support with:

• Your merchant ID/project name
• The order ID if one was generated
• Complete error response
• Steps to reproduce the issue
• Relevant logs from your system

Additional Resources

• Apple Pay Developer Documentation
• Apple Pay JS API Reference
• Apple Pay Identity Guidelines
• Neolink API Documentation
• Neolink Support

---

For additional assistance with your Apple Pay integration, please contact Neolink support.