Official Integration Guide
Integrate YOUPI PG in 5 Minutes
Universal, framework-independent browser integration. Works with PHP, Node.js, Python, Laravel, Django, Next.js, WordPress, or plain HTML.
1
Add the Official Script to Your Page
Place this single script tag in your HTML. It automatically provides modal checkout, responsive iframe sizing, and button auto-detection.
<!-- Official YOUPI PG Universal Integration Script -->
<script
src="https://<youpi-checkout-host>/youpi.js"
data-youpi-key="YOUR_PUBLIC_KEY">
</script>
2
Map Your Payment Button (Zero JavaScript)
Add data-youpi-pay, data-order-id, and data-amount to any button. The script automatically opens the centered modal checkout on click!
<button
data-youpi-pay
data-order-id="ORDER-1001"
data-amount="499">
Buy Now
</button>
Optional button attributes: data-currency="INR", data-customer-name="Mohit", data-customer-email="mohit@example.com", data-customer-phone="9876543210", data-metadata='{"sku":"TSHIRT-01"}'.
3
Listen to Browser Payment Events (For Frontend UX)
The script emits standardized DOM CustomEvents on window to drive your user experience.
<script>
window.addEventListener('youpi:payment:success', (e) => {
const { order_id, amount_received, utr, payment_mode } = e.detail;
console.log(`Payment confirmed for Order #${order_id}. UTR: ${utr}`);
window.location.href = `/order-success?order_id=${order_id}&amount=${amount_received}&utr=${utr}`;
});
window.addEventListener('youpi:payment:failed', (e) => {
window.location.href = `/order-failed?order_id=${e.detail.order_id}&reason=${e.detail.reason}`;
});
window.addEventListener('youpi:payment:suspicious', (e) => {
window.location.href = `/order-suspicious?order_id=${e.detail.order_id}`;
});
</script>
4
Or Use Programmatic Invocation: Youpi.pay({...})
For dynamic shopping carts (React, Vue, Next.js, Nuxt), call the programmatic API directly:
Youpi.pay({
order_id: "ORDER-1001",
amount: 499,
currency: "INR",
customer: {
name: "Mohit",
email: "mohit@example.com",
phone: "9876543210"
},
metadata: { product_id: "TSHIRT-01" },
handler: function(response) {
// response: { status: "SUCCESS", order_id, amount_received, utr, payment_mode }
alert(`Payment successful! UTR: ${response.utr}`);
},
onFailed: function(response) {
alert(`Payment failed: ${response.reason}`);
}
});
5
Configure Authoritative Backend Webhook (Server-to-Server)
CRITICAL SECURITY INVARIANT: Never mark an order paid based only on client-side browser events. Only fulfill orders after verifying the server-to-server HMAC-SHA256 signed webhook!
// Node.js / Express Webhook Receiver Reference
import crypto from 'node:crypto';
app.post('/api/youpi-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-gateway-signature']; // 'sha256=...'
const webhookSecret = process.env.YOUPI_WEBHOOK_SECRET;
// Verify HMAC-SHA256 signature
const expectedHmac = crypto.createHmac('sha256', webhookSecret).update(req.body).digest('hex');
if (signature !== `sha256=${expectedHmac}`) {
return res.status(401).send('Signature mismatch');
}
const event = JSON.parse(req.body.toString());
if (event.event === 'SUCCESS') {
// Authoritative proof: Mark order as PAID in your database!
db.orders.markPaid(event.orderId, { utr: event.utr, amount: event.amount });
}
res.status(200).json({ received: true });
});
Frequently Asked Developer Questions
Q: What do I put in my HTML?
A: Exactly one script tag: <script src="..." data-youpi-key="KEY"></script> and your button with data-youpi-pay.
Q: What information do I send to YOUPI?
A: Only order_id and amount are required. Currency defaults to INR. Customer info and metadata are optional.
Q: How does the payment modal open?
A: Automatically! Clicking a data-youpi-pay button dims and blurs the background and renders the centered 2-column modal (or mobile drawer).
Q: Which event actually proves the order is paid?
A: ONLY the server-to-server webhook with valid HMAC signature. Browser events are for UI animations only.
Q: What should never be trusted from the browser?
A: Any frontend declaration of payment success. Never mark orders as fulfilled based solely on browser redirects or client callbacks.
Q: Does the browser integration need private API secrets?
A: NO! Only your public merchant key is placed in the browser. Private webhook secrets remain securely on your server.
