How to Integrate Hydrogen Popup for Subscription Payments – Hydrogen

This tutorial explains how to integrate Hydrogen’s payment gateway into your website using the Inline JavaScript method. This setup will allow users to initiate recurring monthly payments through a popup modal. Below is a detailed guide to each step of the process.

1. Environment Setup

To begin the integration, first obtain your Public Key from the Hydrogen merchant dashboard. The Public Key is used for front-end operations like triggering the payment modal. You will also need a Secret Key later for backend operations, such as verifying and processing transactions. These keys ensure that payments are securely processed and associated with your Hydrogen account.

2. Include the Required Script

For the payment modal to function, the required JavaScript library must be included in your website's HTML file. This script provides the necessary functions to trigger the payment process. Here’s how to include it in the <head> or the <body> section of your HTML file:

<!-- Payment Gateway Script -->
<script src="<https://js.hydrogenpay.com/inline.js>" module></script>

This script is important because it contains the logic to launch the payment popup and communicate with Hydrogen's servers.

3. Create Subscription Button

To trigger the payment modal, a button must be added to your webpage. When a user clicks this button, the payment modal will open, allowing them to complete the subscription process. Here’s a simple example of a subscription button:

<button id="myBtn" onclick="openDialogModal()">Subscribe Now</button>

The button’s onclick attribute is tied to a JavaScript function called openDialogModal(), which will be defined later to handle the modal.

4. Set Up the Payment Data

Create a JavaScript object containing the payment details. This object includes parameters such as the amount, customer details, and frequency for recurring payments. The frequency is set to monthly (2) in the example below, and the payment will continue until the specified end date which is December, 2025 in this example. Find the complete breakdown of the parameters on the documentation.

  let paymentDetails = {
      amount: 1324,
      email: "devsportaltest@gmail.com",
      customerName: "Dev Portal",
      currency: "NGN",
      description: "Monthly Subscription",
      meta: "Subscription Payment",
      callback: "https://hydrogenpay.com",
      frequency: 2,
      isRecurring: true,
      endDate: "2025-12-31T23:59:59.000Z",
      isAPI: true,
    };

5. Copy the API Keys

You will need to use your Public Key, which is available in the Hydrogen dashboard. For testing purposes, Hydrogen provides a sandbox API key. Replace this key with your live API key when switching to production.

let token  = "PK_TEST_cca53e0b3bc7847aff94502b8a585f84"; //

In this example, the token holds the sandbox API key. Ensure that this is updated with the correct production key before going live.

6. Implement the Payment Modal Function

To launch the payment modal, define the openDialogModal() function. This function will be triggered when the "Subscribe Now" button is clicked. It uses Hydrogen's handlePgData method to handle the payment, passing the paymentDetails object and API key as arguments. If the transaction is successful, the response will include a transaction reference for future use. If there’s an error, it will be logged in the console.

async function openDialogModal() {
  try {
    let transactionResponse = await handlePgData(paymentDetails, token);
    console.log("Transaction reference:", transactionResponse);
  } catch (error) {
    console.error("Error initiating payment:", error);
  }
}

When the openDialogModal function is called, a payment modal will appear where customers can complete the recurring subscription payment process.

7. Payment Confirmation and Callback URL

After the payment is completed, the customer will be redirected to the callback URL specified in the paymentDetails object. The callback URL is responsible for handling payment confirmation. Typically, this means verifying the transaction and updating the user's subscription status.

Example of a simple callback handler on the backend:

app.post("/payment-confirmation", (req, res) => {
  const transactionRef = req.body.transactionRef;
  
  if (transactionRef) {
    // Verify the payment via API and update the user's subscription status
    console.log(`Payment successful with reference: ${transactionRef}`);
  } else {
    console.log("Payment failed or canceled");
  }
});

This Node.js example receives the payment details, verifies the transaction reference, and updates your database to reflect the user’s new subscription status.

8. Testing the Payment Flow

Before switching to production, it’s crucial to test the integration using Hydrogen’s Test Key and Test Cards. Testing allows you to verify that the payment flow, including the popup modal and the callback URL, works as expected. Ensure that payments are processed correctly, and check if your backend can properly handle and update transactions.

9. Switch to Production

Once testing is complete, switch from the sandbox environment to the live environment. This is done by updating the Public Key in your script with the live version and toggling from test mode to live mode on your Hydrogen dashboard. After completing this, your website will be ready to accept live, recurring payments from customers.

This detailed tutorial provides everything needed to integrate Hydrogen’s payment gateway using the Inline JavaScript method. The integration allows for seamless recurring payments through a popup modal. Remember to switch from the test key to the live key once your integration is ready for production.

Related to