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:

• Terms of Service
• Acceptable Use Policy

If you're evaluating the platform rather than implementing right now, see the white-label payment gateway overview.

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 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:

Feature	Hosted Payment Page	Server-to-Server API
Implementation complexity	Low	High
Google Pay™ button hosting	Neolink	Merchant
Google Pay API implementation	Not required	Required
3DS handling	Automatic	Manual implementation
Customization	Limited	Full control
Google registration required	No	Yes

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: Request Google Pay™ activation 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
  }
}

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 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: Request API access 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;
  
  / Base64 encode the entire Google Pay token as required by the gateway
  const encodedToken = Buffer.from(JSON.stringify(googlePayToken).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',
      dsrp: {
        type: 'google_pay',
        token: encodedToken
      },
      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": "BASE64_ENCODED_GOOGLE_PAY_TOKEN"
  },
  "location": {
    "ip": "customer.ip.address"
  }
}

Note: The Google Pay token must be base64 encoded before sending to the gateway. The original token structure looks like:

{
  "signature": "MEQCID2+6F+VWOVFl0WzEWmJLQ+Yyu6hvKfmLfau+Vhcn15jAiB5lXB4qS9tj+smxM6CYpS6D5Jy9Uk7iIfblV+qDrBs+Q==",
  "intermediateSigningKey": {
    "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAErfdKolfpy1W9Kfz8b/4eczsrJ1Zm2wTHbznpWFKbPxbPSQDV2o/7+62yPHKckqPJR7Gs/yiTLaWIq6L9M4x1w\\u003d\\u003d\",\"keyExpiration\":\"1751582620000\"}",
    "signatures": [
      "MEUCIENG3AXKnawqRnKgWK0VwCZX8TGUzwZH8daLf3VVAoAJAiEAhM1LtT0XCP5idLvHoxaWjp55yEfwA7ZcGINBV0XWYxM="
    ]
  },
  "protocolVersion": "ECv2",
  "signedMessage": "{\"encryptedMessage\":\"N+D5mrmv/pPUyCBNoUMR0oX9ypV5pIJ2pjdNm0Qvqg6j2BA9IxYmTVkmVNA445SS9YLxk/Et4QDjGTnOx8VYg9FDRkOccuidOz5mNPlbQblpkqBV4TN0aVnm0GkBd6+oIHCj2juFkxzuN9UoJndoFVcHloodCnMoXA3hdVeQpM1WOZNvwYpGV51VLa/NCu58Ob9+Ky3AuDYLc53b5IBUEFzj/SGBWW0voLQyyZ9M++6u5fnvGA29gJYtrUTKfdPijSTU7Jj3hZ1wzAqxrUGyhSsLEKghmu+5zlo0ikAltVHm3ylCwewn03rvOvM8yLIDO4SZ6UMUfv9d9HWuUEGGm47SAqnPxS8t8f/dgHI9rVdGqmfUl3+uBpeDAO4qvmsMv6MWaUDIP4PsbxIteaHZ2Ur0d3ehF5zPel+Lq2zEQXb1woJrHVS73DuBbiYLzd1Ol6wIET8vPBtcEkdKGvcp13HfBHDzPNqEuM/ukiDHA7qCUooKrTEbeJPzwqOo7kZ2pR3O2F61wEpsc/vcONToVV+AekH64rqRiGnEZZhXy089Qsfa/VYcYD8\\u003d\",\"ephemeralPublicKey\":\"BMvyISANVvctFeCWhibFZOrBL3eRT3ZblvZbNhIxkufGixQWnzdbewpqwpxayS+uZX138xoDpl6QdF6ftAFHXYc\\u003d\",\"tag\":\"aQAcUBB5sHKF1S/sm2cow0VLzwAIBarTJA99yp2M3z0\\u003d\"}"
}

This entire structure should be base64 encoded before sending to the gateway.

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.

Troubleshooting

Common Issues

Issue	Possible Cause	Solution
Google Pay™ button not displaying	Device/browser not supported	Check if the browser is on the supported list
"Payment method not supported" error	Incorrect card network configuration	Ensure you're only requesting VISA and Mastercard networks
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

Next step: explore the acquirer processing solution for routing, settlement and failover controls beyond Google Pay.

Additional Resources

• Google Pay Web developer documentation
• Google Pay Web integration checklist
• Google Pay Web Brand Guidelines
• Neolink API Documentation
• Neolink Support

---

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