Integrate the OnlinePay Checkout with your website

Overview

Merchants who have their own website or online store can integrate the OnlinePay Checkout using either a Hosted Payments Page (HPP) or an iFrame method. Both options provide a secure way for shoppers to complete their payments while allowing merchants to maintain their branding and user experience. This allows merchants to have the flexibility to choose the integration method that best suits their business needs and customer preferences.

The Checkout is created by making a POST request to the https://au.gsc.verifone.cloud/oidc/checkout-service/v2/checkout endpoint with the required parameters. This generates a payment page including the amount and payment methods available for the shopper to complete their purchase.

Integration Methods

HPP (Hosted Payments Page):

• The customer is redirected to the OnlinePay Hosted secure payment page.
• Optional return_url for redirecting back to your site.
• Best for Apple Pay integration.
• Simple implementation with automatic return handling.

iFrame Integration:

• A payment form embedded within your website.
• The customer stays on your domain throughout the process.
• Uses JavaScript postMessage API for communication.
• A more seamless user experience for merchants wanting to keep customers on-site.
• Requires additional JavaScript for handling payment results.

ℹ️

While both methods support all payment types, merchants who want to include Apple Pay should use the HPP integration method for the best customer experience.

Prerequisites

Before you begin integrating the OnlinePay Checkout, ensure you have the following:

• Merchant account and API credentials. See Authentication and environment variables. These are obtained from the OnlinePay Dashboard. Without them, you cannot make API requests.
• A secure backend environment. This includes a server capable of handling API requests to OnlinePay. You should never expose your API credentials on the client side (browser). HTTPS must be enabled for all endpoints.
• SSL/TLS certificate. Your site must run over HTTPS for PCI DSS compliance and for the (optional) return_url parameter to work. For more information about PCI DSS compliance and your obligations, see PCI DSS.
• A webhook endpoint. While not required, we strongly recommend that you set up a webhook endpoint to receive notifications about the status of payments and other transaction events.

Backend configuration

1. Secure your environment

Create a .env file to store your environment variables or add them to your hosting platform's environment variable settings. If you are using a .env file, ensure it is included in your .gitignore file to prevent it from being committed to version control.

You can obtain the required values from the OnlinePay Dashboard. See Authentication and environment variables.

ONLINEPAY_USER_UID=b1234567-xxxx
ONLINEPAY_API_KEY=your-api-key
ONLINEPAY_ENTITY_ID=org-xxxx
ONLINEPAY_PPC_ID=ppc-xxxx
ONLINEPAY_3DS_ID=3ds-xxxx

2. Install dependencies

If you already have a Node.js backend, ensure that express and fetch (or node-fetch) are installed. Install dotenv if you plan to use a .env file for environment variables.

npm install express node-fetch dotenv

3. Create a Secure API endpoint

Create an API endpoint on your server that will validate the incoming request from your frontend and make a POST request to the OnlinePay Checkout API to create a new checkout session, then return the checkout URL to the frontend.

⚠️

When using 3D Secure authentication, customer billing information is required. The checkout will fail if the required customer fields are not provided.

Required customer fields for 3D Secure

• billing.first_name (Required)
• billing.last_name (Required)
• billing.address_1 (Required)
• billing.city (Required)
• billing.country_code (Required - 2-letter ISO code, e.g., 'AU')
• email_address (Required)
• billing.postal_code (Conditional - required if available)
• billing.state (Conditional - required if available)

Wallet Payment Methods

To enable Google Pay and Apple Pay, include the respective configurations in your checkout request:

• Google Pay: Requires 3D Secure configuration with SCA compliance level WALLET.
• Apple Pay: Uses SCA compliance level NONE as Apple Pay handles authentication internally.

The following example uses Express.js to create a simple server with an endpoint to create a checkout session.

import 'dotenv/config';
import express from 'express';
import fetch from 'node-fetch';

const app = express();
app.use(express.json());

app.post('/api/checkout', async (req, res) => {
  const { cartTotalCents, customerData } = req.body;
  const auth = Buffer.from(`${process.env.ONLINEPAY_USER_UID}:${process.env.ONLINEPAY_API_KEY}`).toString('base64');

  const body = {
    entity_id: process.env.ONLINEPAY_ENTITY_ID,
    currency_code: 'AUD',
    amount: cartTotalCents,
    merchant_reference: `ORD-${Date.now()}`,
    interaction_type: 'IFRAME',
    // Note: return_url is not required for iFrame implementation
    
    // Customer data required for 3D Secure payments
    customer_details: {
      entity_id: process.env.ONLINEPAY_ENTITY_ID,
      email_address: customerData.email,
      billing: {
        first_name: customerData.billing.firstName,
        last_name: customerData.billing.lastName,
        address_1: customerData.billing.address,
        city: customerData.billing.city,
        country_code: customerData.billing.countryCode, // e.g., 'AU'
        postal_code: customerData.billing.postalCode,
        state: customerData.billing.state
      }
    },
    
    // Include the payment methods you want to offer to customers
    configurations: {
      card: {
        shopper_interaction: 'ECOMMERCE',
        payment_contract_id: process.env.ONLINEPAY_PPC_ID,
        threed_secure: { 
          threeds_contract_id: process.env.ONLINEPAY_3DS_ID, 
          enabled: true,
          total_items: '01', 
        }
      },
      google_pay: {
        card: {
          threeds_secure: {
            threeds_contract_id: process.env.ONLINEPAY_3DS_ID
          },
          authorization_type: 'FINAL_AUTH',
          sca_compliance_level: 'WALLET',
          shopper_interaction: 'ECOMMERCE',
          payment_contract_id: process.env.ONLINEPAY_PPC_ID
        }
      },
      apple_pay: {
        card: {
          sca_compliance_level: 'NONE',
          shopper_interaction: 'ECOMMERCE',
          payment_contract_id: process.env.ONLINEPAY_PPC_ID
        }
      }
    }
  };

  const resp = await fetch('https://au.gsc.verifone.cloud/oidc/checkout-service/v2/checkout', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${auth}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify(body)
  });

  const data = await resp.json();
  res.json({ checkoutUrl: data.url });
});

app.listen(3000, () => console.log('Server running on port 3000'));

Frontend integration

When implementing 3D Secure payments, ensure your checkout form collects the required customer information before sending the request to your backend:

For iFrame implementation, add a container element to your HTML:

<div id="checkout-container" style="width: 100%; min-height: 600px;">
  <!-- Your checkout form goes here initially -->
  <!-- Will be replaced with iFrame after form submission -->
</div>

// Example frontend checkout form data
const checkoutData = {
  cartTotalCents: 2500, // $25.00
  customerData: {
    email: '[email protected]',
    billing: {
      firstName: 'John',
      lastName: 'Smith',
      address: '123 Collins Street',
      city: 'Melbourne',
      state: 'VIC',
      postalCode: '3000',
      countryCode: 'AU'
    }
  }
};

// Send to your backend API
const response = await fetch('/api/checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(checkoutData)
});

const { checkoutUrl } = await response.json();
window.location.href = checkoutUrl; // Redirect to payment page

4. Implement webhook handling (recommended)

Set up a webhook endpoint on your server to handle notifications from OnlinePay about payment status updates. This ensures you can update your order status based on the payment outcome. This endpoint must be HTTPS-enabled.

app.post('/webhook/onlinepay', (req, res) => {
  console.log('Webhook received:', req.body);
  
  if (req.body.eventType === 'Checkout - Transaction succeeded') {
    const orderId = req.body.content.merchant_reference.replace('ORD-', '');
    
    // Update your order status to "paid"
    // await updateOrderStatus(orderId, 'paid');
    
    // Send confirmation email
    // await sendOrderConfirmation(orderId);
    
    console.log(`Payment SUCCESS for order: ${orderId}`);
  } else if (req.body.eventType === 'Checkout - Transaction failed') {
    console.log('Payment FAILED');
  }
  
  res.status(200).send('OK');
});