iFrame Checkout Integration Steps

Embed the Pine Labs checkout experience inside an iFrame on your page.

The iFrame integration uses the same API as Hosted checkout — Generate Checkout Link — with integration_mode set to IFRAME. The steps are identical to the Hosted checkout integration. The only difference is how you display the checkout to the customer.

Generate Token
Generate Checkout Link (with integration_mode: IFRAME)
Load the Pine Labs Online Web SDK
Open the Checkout using handleCheckout
Handle Payment

Before you begin

Sign up for a Pine Labs account and retrieve your client_id and client_secret
Store credentials securely on your backend
All API calls must be from your backend server
Use TLS 1.2 or higher

Environment	Base URL
UAT (Sandbox)	`https://pluraluat.v2.pinepg.in`
Production	`https://api.pluralonline.com`

Step 1. Generate Token

Authenticate with Pine Labs to get an access token.

Endpoint: POST /api/auth/v1/token

Bash

curl --request POST \
  --url https://pluraluat.v2.pinepg.in/api/auth/v1/token \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
  --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
  --data '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'

See Generate Token API reference.

Step 2. Generate Checkout Link

Create an order and get the checkout URL. Set integration_mode to IFRAME.

Endpoint: POST /api/checkout/v1/orders

Bash

curl --request POST \
  --url https://pluraluat.v2.pinepg.in/api/checkout/v1/orders \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
  --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
  --header 'accept: application/json' \
  --data '{
    "merchant_order_reference": "112345",
    "order_amount": {
      "value": 1100,
      "currency": "INR"
    },
    "integration_mode": "IFRAME",
    "pre_auth": false,
    "allowed_payment_methods": [
      "CARD", "UPI", "NETBANKING", "WALLET"
    ],
    "callback_url": "https://yoursite.com/payment/success",
    "failure_callback_url": "https://yoursite.com/payment/failure",
    "purchase_details": {
      "customer": {
        "email_id": "kevin.bob@example.com",
        "first_name": "Kevin",
        "last_name": "Bob",
        "mobile_number": "9876543210",
        "country_code": "91"
      }
    }
  }'

The response includes a redirect_url. Pass this to handleCheckout in Step 4.

See Create Order API reference.

Step 3. Load the Pine Labs Online Web SDK

Include the Plural Web SDK script on your page before your checkout script.

HTML

<script src="https://checkout.pluralonline.com/v3/web-sdk-checkout.js"></script>

Step 4. Open the Checkout

Use the redirect_url from Step 2 to open the Pine Labs checkout via the SDK. The SDK internally manages the iFrame rendering and lifecycle — you do not need to create an <iframe> element manually.

HTML

<button id="pay_button">Pay</button>

<script src="https://checkout-staging.pluralonline.com/v3/web-sdk-checkout.js"></script>
<script>
  function handleCheckout(redirectUrl) {
    const options = {
      redirectUrl,                              // The redirect_url from Step 2
      successHandler: async function (response) {
        // Called when payment completes successfully
        // response contains order_id, status, signature, and other details
        console.log('Payment successful:', response);

        // Verify the payment signature server-side before fulfilling the order
        // See Step 5.2 for signature verification
      },
      failedHandler: async function (response) {
        // Called when payment fails or is cancelled
        console.log('Payment failed:', response);
      },
    };

    const plural = new Plural(options); // Initialise the Plural SDK
    plural.open(options);               // Open the checkout iFrame modal
  }

  // Trigger checkout when the user clicks Pay
  document.getElementById('pay_button').onclick = function () {
    handleCheckout('{redirect_url}'); // Replace with the redirect_url from Step 2
  };
</script>

Step 5. Handle Payment

5.1 Handle success and failure in SDK callbacks

The successHandler and failedHandler callbacks receive the payment response object directly.

JavaScript

successHandler: async function (response) {
  const { order_id, status, signature } = response;

  // 1. Send order_id and signature to your backend
  // 2. Verify the signature server-side (mandatory — see Step 5.2)
  // 3. Fulfil the order on confirmation of a verified payment
},

failedHandler: async function (response) {
  const { order_id, status } = response;

  // Show an appropriate error message to the customer
  // Optionally allow the customer to retry
},

5.2 Verify payment signature

This step is mandatory. Verify the SHA256 HMAC signature server-side before fulfilling the order.

Build a request string from the callback response parameters, sorted alphabetically by key, joined with &
Generate SHA256 HMAC using your secret_key
Compare with the signature in the response

See Hosted checkout — Integration steps for the full signature verification implementation.

5.3 Check order status

Use Get Order by Order ID to confirm the payment status server-side.

Bash

GET /api/pay/v1/orders/{order_id}

Post-integration: Manage transactions

Capture order (pre-auth only)

If pre_auth: true, capture the payment after verification:

Bash

PUT /api/pay/v1/orders/{order_id}/capture

See Capture Order API.

Cancel order

Bash

PUT /api/pay/v1/orders/{order_id}/cancel

See Cancel Order API.

Webhooks

Configure webhooks for reliable server-to-server notifications.

Test your integration

Test scenario	Details
Cards	Use test card details in UAT
Net Banking	Test via SBI in UAT
UPI	Test your transactions via simulator
iFrame rendering	Test on Chrome, Firefox, Safari, Edge, and mobile browsers
Responsive layout	Test on multiple screen sizes