iFrame Integration

Embed SabPaisa checkout on your website — no redirect needed. The entire payment flow happens within an embedded frame on your page.

Overview

With iFrame integration, the SabPaisa checkout page loads inside your website. Your customer never leaves your site — the entire payment flow (UPI, Cards, Net Banking, Wallets) happens within an embedded frame on your page.

No Redirect

Customer stays on your domain throughout

All Payment Methods

UPI, Cards, Net Banking, Wallets — all in the iframe

PCI Compliant

Card data stays on SabPaisa's checkout — never on your site

How It Works

Your Server

POST /api/v2/payments to SabPaisa API

SabPaisa API

Returns a checkoutUrl for this session

Your Server

Passes checkoutUrl to your frontend

Your Frontend

Loads checkoutUrl inside an <iframe>

Customer

Completes payment inside the iframe

SabPaisa

iframe redirects to your returnUrl (inside the frame)

SabPaisa

Webhook POST sent to your server with payment confirmation

Step 1 — Create a Payment Session

Call this from your backend server — never from the frontend. Your API key must not be exposed to the browser.

Endpoint

POST/api/v2/payments

Request Body

{ }

1{
2  "merchantId":    "YOUR_MERCHANT_ID",
3  "merchantTxnId": "ORDER_20260414_001",
4  "amount":        50000,
5  "currency":      "INR",
6  "customerName":  "Rahul Sharma",
7  "customerEmail": "[email protected]",
8  "customerPhone": "9876543210",
9  "returnUrl":     "https://yoursite.com/payment/result",
10  "checksum":      "a1b2c3d4...64_hex_chars",
11  "timestamp":     1713081600
12}

The returnUrl is where the customer is redirected after payment — this redirect happens inside the iframe. See Step 3A for how to break out of the iframe and show the result on your full page.

Request Parameters

Parameter	Type	Required	Description
merchantId	string	Yes	Your SabPaisa Merchant ID
merchantTxnId	string	Yes	Your unique order / transaction ID
amount	integer	Yes	Amount in paise (50000 = Rs. 500.00)
currency	string	Yes	Always INR
customerName	string	Yes	Customer's full name
customerEmail	string	Yes	Customer's email address
customerPhone	string	Yes	Customer's 10-digit mobile number
returnUrl	string	Yes	Your page to receive the post-payment redirect
checksum	string	Yes	HMAC-SHA256 signature (see below)
timestamp	integer	Yes	Unix timestamp of the request

Checksum Generation

Base string : merchantId|merchantTxnId|amount|currency|timestamp

Algorithm : HMAC-SHA256 using your Secret Key

Output : 64-character lowercase hex string

1import javax.crypto.Mac;
2import javax.crypto.spec.SecretKeySpec;
3
4String base = merchantId + "|" + merchantTxnId + "|" + amount
5            + "|" + currency + "|" + timestamp;
6
7Mac mac = Mac.getInstance("HmacSHA256");
8mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
9byte[] hash = mac.doFinal(base.getBytes("UTF-8"));
10
11StringBuilder hex = new StringBuilder();
12for (byte b : hash) hex.append(String.format("%02x", b));
13String checksum = hex.toString();

Response

{ }

1{
2  "checkoutUrl": "https://checkout.sabpaisa.in/checkout/sess_abc123xyz",
3  "paymentId":   "sppay_abc123xyz"
4}

Save the checkoutUrl — you will embed this in the iframe in Step 2. The paymentId is useful for reconciliation and support queries.

Step 2 — Embed the Checkout in an iFrame

Instead of redirecting the customer to checkoutUrl, load it inside an iframe on your payment page.

Basic HTML

html

1<div id="sabpaisa-checkout-container">
2  <iframe
3    id="sabpaisa-checkout"
4    src="YOUR_CHECKOUT_URL_HERE"
5    width="100%"
6    height="650"
7    frameborder="0"
8    allow="payment"
9    style="border: none; border-radius: 8px;"
10  ></iframe>
11</div>

Recommended Container Styling

css

1#sabpaisa-checkout-container {
2  max-width: 500px;
3  margin: 20px auto;
4  min-height: 650px;
5}
6
7#sabpaisa-checkout {
8  width: 100%;
9  height: 650px;
10  border: 1px solid #e0e0e0;
11  border-radius: 8px;
12  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
13}
14
15/* Responsive for mobile */
16@media (max-width: 600px) {
17  #sabpaisa-checkout-container { max-width: 100%; margin: 0; }
18  #sabpaisa-checkout { height: 100vh; border-radius: 0; border: none; }
19}

On mobile, the iframe expands to full viewport height for an optimal checkout experience. Always test on both desktop and mobile.

Step 3 — Handle Payment Completion

After the customer completes (or fails) payment, two things happen: the iframe redirects to your returnUrl, and SabPaisa sends a webhook to your server.

AreturnUrl Redirect (Frontend)

After payment, the SabPaisa checkout page redirects to your returnUrl inside the iframe. The redirect URL includes payment status as query parameters:

text

1https://yoursite.com/payment/result
2  ?status=SUCCESS
3  &merchantTxnId=ORDER_20260414_001
4  &paymentId=sppay_abc123xyz

Recommended approach: make your returnUrl page break out of the iframe and show the result on the full page.

html

1<!-- Your returnUrl page: /payment/result -->
2<script>
3  // Break out of iframe — redirect parent to this same URL
4  if (window.self !== window.top) {
5    window.top.location.href = window.location.href;
6  }
7</script>

After payment, the customer seamlessly lands on your full result page — not trapped inside the iframe. Read the status, merchantTxnId, and paymentId from the URL query parameters to render the result.

BWebhook Callback (Server-Side — Source of Truth)

SabPaisa sends an HTTP POST to your configured webhook URL with the final payment status. This uses the same webhook system as all SabPaisa payment flows.

Webhook Payload

{ }

1{
2  "paymentId":     "sppay_abc123xyz",
3  "merchantTxnId": "ORDER_20260414_001",
4  "status":        "SUCCESS",
5  "amount":        50000,
6  "currency":      "INR",
7  "paymentMode":   "UPI"
8}

Status Values

Status	Meaning	Action
SUCCESS	Payment completed successfully	Fulfil the order
FAILED	Payment failed	Prompt customer to retry
EXPIRED	Customer did not complete payment in time	Show expiry message; customer can initiate a new session

Always verify the webhook signature before trusting the payload.
The webhook is the source of truth — use it to update your order status in the database.
Never fulfil an order based solely on the returnUrl query parameters.

For webhook signature verification, retry policy, and event details, see the Webhooks documentation.

Complete Example

A complete payment page with order summary and embedded checkout iframe.

html

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <meta name="viewport" content="width=device-width, initial-scale=1.0">
6  <title>Payment - Your Store</title>
7  <style>
8    body {
9      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
10      background: #f5f5f5; margin: 0; padding: 20px;
11    }
12    .payment-wrapper { max-width: 520px; margin: 0 auto; }
13    .order-summary {
14      background: white; padding: 20px; border-radius: 8px;
15      margin-bottom: 16px; box-shadow: 0 1px 4px rgba(0,0,0,0.1);
16    }
17    .order-total { font-size: 24px; font-weight: bold; color: #1a1a1a; }
18    #checkout-frame {
19      width: 100%; height: 650px;
20      border: 1px solid #e0e0e0; border-radius: 8px; background: white;
21    }
22    @media (max-width: 600px) {
23      body { padding: 0; }
24      #checkout-frame { height: 100vh; border: none; border-radius: 0; }
25    }
26  </style>
27</head>
28<body>
29  <div class="payment-wrapper">
30    <div class="order-summary">
31      <h2>Order Summary</h2>
32      <p>Product: Premium Plan</p>
33      <p class="order-total">Rs. 500.00</p>
34    </div>
35    <iframe id="checkout-frame"
36      src="CHECKOUT_URL_FROM_YOUR_SERVER"
37      frameborder="0" allow="payment"></iframe>
38  </div>
39</body>
40</html>

The returnUrl page that breaks out of the iframe and displays the payment result.

html

1<!DOCTYPE html>
2<html>
3<head><title>Payment Result</title></head>
4<body>
5<script>
6  // Break out of iframe on payment completion
7  if (window.self !== window.top) {
8    window.top.location.href = window.location.href;
9  }
10
11  // Read result from query params
12  const params = new URLSearchParams(window.location.search);
13  const status = params.get('status');
14  const txnId  = params.get('merchantTxnId');
15  // Render result based on status...
16</script>
17<!-- Server-side render the result here -->
18</body>
19</html>

Environments

Environment	Checkout URL Pattern
Staging (Test)	Provided during onboarding
Production	https://checkout.sabpaisa.in/checkout/{sessionId}

Always complete full end-to-end testing on staging before switching to production. Staging API Key and Production API Key are different — do not mix them.

Integration Checklist

Complete all items below before going live.

Get API Key, Merchant ID, and Secret Key from SabPaisa

Implement payment session creation on your server (POST /api/v2/payments)

Generate checksum correctly using HMAC-SHA256

Embed the checkoutUrl in an iframe on your payment page

Create a returnUrl page that breaks out of the iframe (Step 3A)

Set up webhook endpoint to receive payment status (Step 3B)

Implement webhook signature verification

Test on staging environment — all payment modes

Test on mobile — verify responsive iframe behaviour

Switch API Key and URLs to production

Run end-to-end production test with a real transaction

FAQ

Does the customer leave my website?

No. The checkout loads inside an iframe on your site. After payment, the returnUrl page breaks out of the iframe back to your full site — the customer stays on your domain throughout.

Which payment methods are available in the iframe?

All methods — UPI, Credit/Debit Cards, Net Banking, and Wallets. The iframe renders the same checkout as the full-page experience.

Does this work on mobile?

Yes. Use the responsive CSS provided in Step 2. On mobile, the iframe expands to full viewport height.

Is this PCI compliant?

Yes. Card data is entered on SabPaisa's checkout page inside the iframe, not on your website. You never handle or store any sensitive card data.

How do I know when payment is complete?

Two ways: (1) returnUrl redirect inside the iframe — use the iframe-breakout script to show the result on your full page. (2) Webhook callback on your server — this is the source of truth for updating your order status.

What if the customer closes the browser before completing payment?

The payment session will expire after the timeout period. You will receive a webhook with status EXPIRED. Always rely on the webhook for final status, not the returnUrl.

iFrame Integration

Embed SabPaisa checkout on your website — no redirect needed. The entire payment flow happens within an embedded frame on your page.

Overview

No Redirect

Customer stays on your domain throughout

All Payment Methods

UPI, Cards, Net Banking, Wallets — all in the iframe

PCI Compliant

Card data stays on SabPaisa's checkout — never on your site

How It Works

Your Server

POST /api/v2/payments to SabPaisa API

SabPaisa API

Returns a checkoutUrl for this session

Your Server

Passes checkoutUrl to your frontend

Your Frontend

Loads checkoutUrl inside an <iframe>

Customer

Completes payment inside the iframe

SabPaisa

iframe redirects to your returnUrl (inside the frame)

SabPaisa

Webhook POST sent to your server with payment confirmation

Step 1 — Create a Payment Session

Call this from your backend server — never from the frontend. Your API key must not be exposed to the browser.

Endpoint

POST/api/v2/payments

Request Body

{ }

1{
2  "merchantId":    "YOUR_MERCHANT_ID",
3  "merchantTxnId": "ORDER_20260414_001",
4  "amount":        50000,
5  "currency":      "INR",
6  "customerName":  "Rahul Sharma",
7  "customerEmail": "[email protected]",
8  "customerPhone": "9876543210",
9  "returnUrl":     "https://yoursite.com/payment/result",
10  "checksum":      "a1b2c3d4...64_hex_chars",
11  "timestamp":     1713081600
12}

Request Parameters

Parameter	Type	Required	Description
merchantId	string	Yes	Your SabPaisa Merchant ID
merchantTxnId	string	Yes	Your unique order / transaction ID
amount	integer	Yes	Amount in paise (50000 = Rs. 500.00)
currency	string	Yes	Always INR
customerName	string	Yes	Customer's full name
customerEmail	string	Yes	Customer's email address
customerPhone	string	Yes	Customer's 10-digit mobile number
returnUrl	string	Yes	Your page to receive the post-payment redirect
checksum	string	Yes	HMAC-SHA256 signature (see below)
timestamp	integer	Yes	Unix timestamp of the request

Checksum Generation

Base string : merchantId|merchantTxnId|amount|currency|timestamp

Algorithm : HMAC-SHA256 using your Secret Key

Output : 64-character lowercase hex string

1import javax.crypto.Mac;
2import javax.crypto.spec.SecretKeySpec;
3
4String base = merchantId + "|" + merchantTxnId + "|" + amount
5            + "|" + currency + "|" + timestamp;
6
7Mac mac = Mac.getInstance("HmacSHA256");
8mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
9byte[] hash = mac.doFinal(base.getBytes("UTF-8"));
10
11StringBuilder hex = new StringBuilder();
12for (byte b : hash) hex.append(String.format("%02x", b));
13String checksum = hex.toString();

Response

{ }

1{
2  "checkoutUrl": "https://checkout.sabpaisa.in/checkout/sess_abc123xyz",
3  "paymentId":   "sppay_abc123xyz"
4}

Save the checkoutUrl — you will embed this in the iframe in Step 2. The paymentId is useful for reconciliation and support queries.

Step 2 — Embed the Checkout in an iFrame

Instead of redirecting the customer to checkoutUrl, load it inside an iframe on your payment page.

Basic HTML

html

1<div id="sabpaisa-checkout-container">
2  <iframe
3    id="sabpaisa-checkout"
4    src="YOUR_CHECKOUT_URL_HERE"
5    width="100%"
6    height="650"
7    frameborder="0"
8    allow="payment"
9    style="border: none; border-radius: 8px;"
10  ></iframe>
11</div>

Recommended Container Styling

css

1#sabpaisa-checkout-container {
2  max-width: 500px;
3  margin: 20px auto;
4  min-height: 650px;
5}
6
7#sabpaisa-checkout {
8  width: 100%;
9  height: 650px;
10  border: 1px solid #e0e0e0;
11  border-radius: 8px;
12  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
13}
14
15/* Responsive for mobile */
16@media (max-width: 600px) {
17  #sabpaisa-checkout-container { max-width: 100%; margin: 0; }
18  #sabpaisa-checkout { height: 100vh; border-radius: 0; border: none; }
19}

On mobile, the iframe expands to full viewport height for an optimal checkout experience. Always test on both desktop and mobile.

Step 3 — Handle Payment Completion

After the customer completes (or fails) payment, two things happen: the iframe redirects to your returnUrl, and SabPaisa sends a webhook to your server.

AreturnUrl Redirect (Frontend)

After payment, the SabPaisa checkout page redirects to your returnUrl inside the iframe. The redirect URL includes payment status as query parameters:

text

1https://yoursite.com/payment/result
2  ?status=SUCCESS
3  &merchantTxnId=ORDER_20260414_001
4  &paymentId=sppay_abc123xyz

Recommended approach: make your returnUrl page break out of the iframe and show the result on the full page.

html

1<!-- Your returnUrl page: /payment/result -->
2<script>
3  // Break out of iframe — redirect parent to this same URL
4  if (window.self !== window.top) {
5    window.top.location.href = window.location.href;
6  }
7</script>

BWebhook Callback (Server-Side — Source of Truth)

SabPaisa sends an HTTP POST to your configured webhook URL with the final payment status. This uses the same webhook system as all SabPaisa payment flows.

Webhook Payload

{ }

1{
2  "paymentId":     "sppay_abc123xyz",
3  "merchantTxnId": "ORDER_20260414_001",
4  "status":        "SUCCESS",
5  "amount":        50000,
6  "currency":      "INR",
7  "paymentMode":   "UPI"
8}

Status Values

Status	Meaning	Action
SUCCESS	Payment completed successfully	Fulfil the order
FAILED	Payment failed	Prompt customer to retry
EXPIRED	Customer did not complete payment in time	Show expiry message; customer can initiate a new session

Always verify the webhook signature before trusting the payload.
The webhook is the source of truth — use it to update your order status in the database.
Never fulfil an order based solely on the returnUrl query parameters.

For webhook signature verification, retry policy, and event details, see the Webhooks documentation.

Complete Example

A complete payment page with order summary and embedded checkout iframe.

html

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <meta name="viewport" content="width=device-width, initial-scale=1.0">
6  <title>Payment - Your Store</title>
7  <style>
8    body {
9      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
10      background: #f5f5f5; margin: 0; padding: 20px;
11    }
12    .payment-wrapper { max-width: 520px; margin: 0 auto; }
13    .order-summary {
14      background: white; padding: 20px; border-radius: 8px;
15      margin-bottom: 16px; box-shadow: 0 1px 4px rgba(0,0,0,0.1);
16    }
17    .order-total { font-size: 24px; font-weight: bold; color: #1a1a1a; }
18    #checkout-frame {
19      width: 100%; height: 650px;
20      border: 1px solid #e0e0e0; border-radius: 8px; background: white;
21    }
22    @media (max-width: 600px) {
23      body { padding: 0; }
24      #checkout-frame { height: 100vh; border: none; border-radius: 0; }
25    }
26  </style>
27</head>
28<body>
29  <div class="payment-wrapper">
30    <div class="order-summary">
31      <h2>Order Summary</h2>
32      <p>Product: Premium Plan</p>
33      <p class="order-total">Rs. 500.00</p>
34    </div>
35    <iframe id="checkout-frame"
36      src="CHECKOUT_URL_FROM_YOUR_SERVER"
37      frameborder="0" allow="payment"></iframe>
38  </div>
39</body>
40</html>

The returnUrl page that breaks out of the iframe and displays the payment result.

html

1<!DOCTYPE html>
2<html>
3<head><title>Payment Result</title></head>
4<body>
5<script>
6  // Break out of iframe on payment completion
7  if (window.self !== window.top) {
8    window.top.location.href = window.location.href;
9  }
10
11  // Read result from query params
12  const params = new URLSearchParams(window.location.search);
13  const status = params.get('status');
14  const txnId  = params.get('merchantTxnId');
15  // Render result based on status...
16</script>
17<!-- Server-side render the result here -->
18</body>
19</html>

Environments

Environment	Checkout URL Pattern
Staging (Test)	Provided during onboarding
Production	https://checkout.sabpaisa.in/checkout/{sessionId}

Always complete full end-to-end testing on staging before switching to production. Staging API Key and Production API Key are different — do not mix them.

Integration Checklist

Complete all items below before going live.

Get API Key, Merchant ID, and Secret Key from SabPaisa

Implement payment session creation on your server (POST /api/v2/payments)

Generate checksum correctly using HMAC-SHA256

Embed the checkoutUrl in an iframe on your payment page

Create a returnUrl page that breaks out of the iframe (Step 3A)

Set up webhook endpoint to receive payment status (Step 3B)

Implement webhook signature verification

Test on staging environment — all payment modes

Test on mobile — verify responsive iframe behaviour

Switch API Key and URLs to production

Run end-to-end production test with a real transaction

FAQ

Does the customer leave my website?

No. The checkout loads inside an iframe on your site. After payment, the returnUrl page breaks out of the iframe back to your full site — the customer stays on your domain throughout.

Which payment methods are available in the iframe?

All methods — UPI, Credit/Debit Cards, Net Banking, and Wallets. The iframe renders the same checkout as the full-page experience.

Does this work on mobile?

Yes. Use the responsive CSS provided in Step 2. On mobile, the iframe expands to full viewport height.

Is this PCI compliant?

Yes. Card data is entered on SabPaisa's checkout page inside the iframe, not on your website. You never handle or store any sensitive card data.

How do I know when payment is complete?

What if the customer closes the browser before completing payment?

The payment session will expire after the timeout period. You will receive a webhook with status EXPIRED. Always rely on the webhook for final status, not the returnUrl.

Overview#

How It Works#

Step 1 — Create a Payment Session#

Endpoint

Request Body

Request Parameters

Checksum Generation

Response

Step 2 — Embed the Checkout in an iFrame#

Basic HTML

Recommended Container Styling

Step 3 — Handle Payment Completion#

AreturnUrl Redirect (Frontend)

BWebhook Callback (Server-Side — Source of Truth)

Webhook Payload

Status Values

Complete Example#

Environments#

Integration Checklist#

FAQ#

We're Here to Help

Related Pages

Overview#

How It Works#

Step 1 — Create a Payment Session#

Endpoint

Request Body

Request Parameters

Checksum Generation

Response

Step 2 — Embed the Checkout in an iFrame#

Basic HTML

Recommended Container Styling

Step 3 — Handle Payment Completion#

AreturnUrl Redirect (Frontend)

BWebhook Callback (Server-Side — Source of Truth)

Webhook Payload

Status Values

Complete Example#

Environments#

Integration Checklist#

FAQ#

We're Here to Help

Related Pages

Overview

How It Works

Step 1 — Create a Payment Session

Step 2 — Embed the Checkout in an iFrame

Step 3 — Handle Payment Completion

Complete Example

Environments

Integration Checklist

FAQ

Overview

How It Works

Step 1 — Create a Payment Session

Step 2 — Embed the Checkout in an iFrame

Step 3 — Handle Payment Completion

Complete Example

Environments

Integration Checklist

FAQ