Paytul Integration Guide

This document describes the complete workflow and implementation steps required to integrate Paytul into your platform.

You must generate the checkout access token on the backend and pass it to the frontend before opening the checkout modal.

Include the Paytul SDK

Add the Paytul Checkout SDK by including this script in your frontend:

<script src="https://pay.crowdera.org/checkout.js"></script>

Generate Checkout Access Token

Your backend must generate a checkout access token by calling the following API:

POST ${backend_server}/payments/generate/token

Example helper for generating the access token:

const generatePgAccessToken = async () => {
  const client_id = process.env.PAYMENT_GATEWAY_CLIENT_ID;
  const client_secret = process.env.PAYMENT_GATEWAY_SECRET;
  const auth = Buffer.from(client_id + ":" + client_secret).toString("base64");
  const response = await fetch(
    `${process.env.PAYMENT_GATEWAY_URL}/api/v1/oauth/token`,
    {
      method: "POST",
      headers: {
        Authorization: `Basic ${auth}`,
      },
    },
  );

  if (!response.ok) {
    throw new Error("Failed to fetch access token");
  }

  const { access_token } = await response.json();
  return access_token;
};

The generated access_token is required to open the Paytul checkout.

Initialize and Open Checkout

Once you have the access_token, open the Checkout using the global window.Paytul.open() method:

window.Paytul.open({
  ...payload,
  access_token,
  closeModalDelay: 4000,
  theme: {
    title: organization_name,
    headerColor: "#1069B2",
    textColor: "white",
  },
  handler: async function (response) {
    try {
      const res = await handleSuccessPayment(response);
      if (res) {
        const redirectUrl = res?.redirect_url || "/success";
        router?.push?.(redirectUrl);
      }
    } catch (error) {
      console.error("Payment verification failed:", error);
    }
  },
});

Customization Options

Option	Description
theme.headerColor	Sets the background color of the checkout header.
theme.textColor	Sets the header text color.
closeModalDelay	Controls how long the modal remains open after payment (in milliseconds).
payload	Contains the required data for checkout initialization.
handler()	Callback function triggered after successful payment.

Handler Function (Callback)

The handler function is executed once the payment is verified successfully. You can:

Call backend APIs
Execute business logic (e.g., send confirmation email)
Redirect the user to a success page

Checkout Flow Overview

Step 1 - User Opens Checkout: After calling window.Paytul.open(), the checkout modal opens. Users enter personal or billing information on the first page.
Step 2 - Payment Method Selection: Available payment gateways are displayed based on supported currency and configuration.
Step 3 - Payment Completion: The handler callback is triggered, you can validate the payment or call a verification API, and the user is redirected to the defined redirect URL.

Redirect After Payment

Inside the handler callback, set the redirection logic:

const redirectUrl = res?.redirect_url || "/success";
router?.push?.(redirectUrl);

You may configure this URL dynamically from your backend as well.

Summary

Load SDK - https://pay.crowdera.org/checkout.js
Generate access token from backend - /payments/generate/token
Open Checkout using window.Paytul.open()
User enters details - Page 1
User selects payment method - Page 2
Payment success triggers handler
User is redirected to the success page