Skip to main content

Google 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 Google Pay™ with the Neolink payment gateway. Google 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 Google Pay™ documents:

Neolink payment gateway supports the following features with Google Pay™:

  • Card payments via Visa and Mastercard networks
  • PAN_ONLY and CRYPTOGRAM_3DS authentication methods
  • 3D Secure authentication for enhanced security
  • Both hosted checkout and direct API integration methods

Branding & Trademark Usage​

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

  • Include the trademark symbol (™) after "Google Pay" the first time it appears on each page or screen
  • Use the official Google Pay logo and button assets as provided in the Google Pay Brand Guidelines
  • Do not modify the Google Pay button or logo colors, proportions, or appearance
  • Maintain appropriate clear space around the Google Pay button (minimum 14dp on all sides)
  • Use only approved button variations (black or white backgrounds with proper height-to-width ratio)

Correct usage examples:

  • "Pay with Google Pay™"
  • "Google Pay™ is now available at checkout"

Incorrect usage examples:

  • "Pay with GooglePay" (missing space and trademark)
  • "GPay is now available" (using unofficial shorthand)

Official Button Implementation​

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

<!-- Example of proper Google Pay button implementation -->
<button type="button" class="gpay-button">Buy with Google Pay</button>

For detailed branding requirements, consult the Google Pay Web Brand Guidelines or Google Pay Android Brand Guidelines depending on your platform.

Integration Options​

Neolink offers two methods for integrating Google Pay™:

  1. Hosted Payment Page Integration: Simplest option with minimal setup, where Neolink handles the Google 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 Google Pay™ API

The table below compares these integration methods:

FeatureHosted Payment PageServer-to-Server API
Implementation complexityLowHigh
Google Pay™ button hostingNeolinkMerchant
Google Pay API implementationNot requiredRequired
3DS handlingAutomaticManual implementation
CustomizationLimitedFull control
Google registration requiredNoYes

Hosted Payment Page Integration​

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

Integration Steps​

  1. Request Google Pay™ activation: Email [email protected] to enable Google Pay™ for your account
  2. Implement standard payment page flow: Use the standard Neolink payment page integration
  3. No additional code required: The Google 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 Google Pay™, the button appears automatically
  5. Customer selects Google 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": {
    "google_pay_enabled": 1
  }
}

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 google_pay_enabled parameter ensures Google 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 Google Pay™ API directly.

Prerequisites​

  1. Register with Google: Create a Google Pay™ developer account
  2. Request API access: Email [email protected] to get your gateway merchant ID
  3. Implement Google Pay™ API: Follow Google's implementation guide

Integration Steps​

  1. Configure Google Pay™ API: Set up the Google Pay™ API client on your website/app

  2. Set up tokenization specifications:

    const tokenizationSpecification = {
      type: 'PAYMENT_GATEWAY',
      parameters: {
        'gateway': 'neolinkprocessing',
        'gatewayMerchantId': 'YOUR_NEOLINK_MERCHANT_ID'
      }
    };

  3. Configure allowed payment methods:

    const allowedCardNetworks = ['VISA', 'MASTERCARD'];
    const allowedCardAuthMethods = ['PAN_ONLY', 'CRYPTOGRAM_3DS'];

  4. Billing Address Configuration:

    Note: Neolink does not require billing address information for processing Google Pay™ transactions. The BillingAddressParameters configuration is optional and not used for address verification purposes.

    If you still want to collect billing address information for your own purposes, you can configure it as follows:

    const paymentDataRequest = {
      // Other configuration...
      
      // Optional billing address configuration
      billingAddressParameters: {
        format: 'MIN', // or 'FULL' if you need detailed address
        phoneNumberRequired: false
      }
    };

  5. Handle payment token: Send the encrypted Google Pay™ token to Neolink API

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

Google Pay™ Button Implementation​

// Load Google Pay API
const googlePayClient = new google.payments.api.PaymentsClient({
  environment: 'PRODUCTION' // or 'TEST' for sandbox
});

// Create button
const button = googlePayClient.createButton({
  onClick: onGooglePayButtonClicked,
  buttonType: 'pay'
});
document.getElementById('google-pay-container').appendChild(button);

Payment Processing​

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

// On your client
function onGooglePayButtonClicked() {
  googlePayClient.loadPaymentData(paymentDataRequest)
    .then(function(paymentData) {
      // Send paymentData.paymentMethodData.tokenizationData.token to your server
      fetch('/process-google-pay', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({googlePayToken: paymentData.paymentMethodData.tokenizationData.token})
      });
    });
}

// On your server
app.post('/process-google-pay', (req, res) => {
  const { googlePayToken } = req.body;
  
  // 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',
      dsrp: {
        type: 'google_pay',
        token: googlePayToken
      },
      location: {
        ip: customerIpAddress
      }
    })
  });
  
  // Handle response
});

API Request Example​

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

{
  "amount": "99.99",
  "currency": "USD",
  "description": "Order #12345",
  "dsrp": {
    "type": "google_pay",
    "token": "ENCRYPTED_GOOGLE_PAY_TOKEN"
  },
  "location": {
    "ip": "customer.ip.address"
  }
}

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 Google Pay™.

3DS Requirements by Card Type​

Google Pay™ supports two types of card credentials:

  1. PAN_ONLY: Physical card details stored in Google Pay™

    • 3DS Required: Yes, standard 3DS flow applies
    • Implementation: Handle 3DS challenge flow when indicated by the API

  2. CRYPTOGRAM_3DS: Tokenized virtual card stored on device

    • 3DS Required: No, authentication is performed by Google Pay™
    • Implementation: No additional steps needed

Handling 3DS for PAN_ONLY Cards​

When processing a PAN_ONLY card through Google Pay™, you may need to handle 3DS authentication:

  1. Hosted Payment Page: 3DS is automatically handled
  2. Server-to-Server API: You must implement 3DS handling

3DS Flow for Server-to-Server Integration​

If the payment requires 3DS authentication, the API will return a response with 3DS details:

{
  "orders": [{
    "id": "60391976929806541",
    "status": "prepared",
    "form3d": {
      "threeDSSessionData": "NjAzOTE5NzY5Mjk4MDY1NDE=",
      "method": "POST",
      "action": "https://checkout.neolink.io/complete/secure3d20"
    },
    "form3d_html": "<form id=\"form3d\" method=\"POST\" action=\"https://checkout.neolink.io/complete/secure3d20\"><input type=\"hidden\" name=\"threeDSSessionData\" value=\"NjAzOTE5NzY5Mjk4MDY1NDE=\"></form><script>window.onload = function() {document.forms['form3d'].submit();}</script>",
    "secure3d": {
      "dsrp": "0",
      "scenario": "unknown",
      "reason": "force3d",
      "eci": "0",
      "version": "2"
    }
  }]
}

Note: The checkout domain in the example above may be different based on your specific integration. It could be like checkout.{domain}.com. Your specific endpoints will be provided during the onboarding process.

You need to:

  1. Display the 3DS challenge to the customer (using the provided form3d_html)
  2. Handle the 3DS completion
  3. Check the final status of the payment

Testing Your Integration​

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

Google Pay Test Environment​

Google Pay™ provides a dedicated test environment that automatically displays mock test cards in the payment sheet. To use this environment, set the environment parameter to 'TEST':

const googlePayClient = new google.payments.api.PaymentsClient({
  environment: 'TEST'
});

When the environment is set to 'TEST', the Google Pay payment sheet will display a suite of test cards specifically for integration testing, without requiring you to add actual cards to your Google account.

Mock Test Cards​

Your integration will use Google's mock test cards when in the TEST environment. These mock cards provide:

  • Visa and Mastercard card networks
  • The PAN_ONLY authentication method
  • A billing address in the US
  • Various shipping addresses

The tokens generated with these mock cards can be processed by Neolink's test environment, as it accepts any valid card format.

Testing Process​

When testing your Google Pay™ integration with Neolink, you can use a streamlined approach:

  1. UI and Payment Flow Testing:

    • Use Google's TEST environment with mock cards to verify your Google Pay button displays correctly
    • Test the payment sheet flow and user experience
    • Confirm that tokenized payment data is received by your server

  2. End-to-End Testing:

    • Process the tokens generated from Google's mock cards 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 in the PRODUCTION environment

Testing Steps​

  1. Configure test environment: Set up your integration to use the 'TEST' environment for Google Pay™
  2. Test payment sheet flow: Verify the user interface works correctly
  3. Test token handling: Ensure your server correctly receives and handles the encrypted payment tokens
  4. Test your error handling: Verify your application gracefully handles different response scenarios
  5. Complete integration checklist: Verify all items in the Google Pay integration checklist before requesting production access

Troubleshooting​

If you encounter issues during testing:

  1. Verify you've set the correct gateway parameters (gateway: 'neolinkprocessing')
  2. Ensure you're using the TEST environment for UI testing
  3. Check that your server correctly receives the encrypted payment token
  4. Review API responses for specific error messages

For persistent issues, contact Neolink support at [email protected].

Troubleshooting​

Common Issues​

IssuePossible CauseSolution
Google Pay™ button not displayingDevice/browser not supportedCheck if the browser is on the supported list
"Payment method not supported" errorIncorrect card network configurationEnsure you're only requesting VISA and Mastercard networks
Payment declinedTest card or incorrect amount formatCheck card details and ensure amount is formatted correctly
3DS authentication failsIncorrect 3DS implementationReview 3DS flow implementation
Token_pay API errorsMalformed requestVerify 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 at [email protected] 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​

For additional assistance with your Google Pay™ integration, please contact Neolink support at [email protected].