@sk-py/upi-qr/README.md

Generate NPCI-compliant UPI QR codes for Indian digital payments. Supports payee VPA, amount, transaction note, and more.

# @sk-py/upi-qr

> Generate NPCI-compliant UPI QR codes for Indian digital payments  
> Works in Node.js and React – returns both a Base64 QR image and a UPI intent string.

---


## Table of Contents

1. [Installation](#installation)  
2. [Features](#features)  
3. [Usage](#usage)  
   - [Node.js Example](#nodejs-example)  
   - [React Example](#react-example)  
4. [API Reference: `generateUPIQR()`](#api-reference-generateupiqr)  
5. [Component Props: `UPIQRComponent`](#component-props-upiqrcomponent)  
6. [Production Tips](#production-tips)  
7. [Author & License](#author--license)  
8. [Publishing Scope](#publishing-scope)  
9. [Contributing](#contributing)

---


## Installation

```bash
# Using npm
npm install @sk-py/upi-qr

# Or with yarn
yarn add @sk-py/upi-qr
```

> **Peer Dependency:**  
> React ≥ 18.0.0 (for the React component)

---


## Features

- 🎯 Generate UPI payment URLs compliant with NPCI  
- 🖼️ Produce Base64-encoded QR code images  
- ⚙️ Support all standard UPI fields:
  - Payee VPA & Name (required)
  - Amount, Currency, Transaction Note, Transaction Reference, URL (optional)
- 🔗 Return both:
  1. `qr` – Base64 data-URI (PNG)
  2. `intent` – `upi://pay?...` URL for deep-linking
- 🎨 Ready-to-use React component for quick integration

---


## Usage

### Node.js Example

```js
import { generateUPIQR } from '@sk-py/upi-qr';

async function createUPIPayment() {
  try {
    const { qr, intent } = await generateUPIQR({
      payeeVPA:    'merchant@bank',
      payeeName:   'Acme Corp',
      amount:      '150.00',
      transactionNote: 'Invoice #1234',
      transactionRef:  'INV1234',
      url:         'https://acme.example.com/order/1234',
      currency:    'INR'   // defaults to INR
    });

    console.log('UPI Intent URL:', intent);
    // For example, save `qr` (data URI) to a file or send to frontend
  } catch (err) {
    console.error('Error generating UPI QR:', err);
  }
}

createUPIPayment();
```

### React Example

```jsx
import React from 'react';
import { generateUPIQR } from '@sk-py/upi-qr';
import UPIQRComponent from '@sk-py/upi-qr/react';

function App() {
  const [qrData, setQrData] = React.useState({ qr: '', intent: '' });

  React.useEffect(() => {
    generateUPIQR({
      payeeVPA:  'merchant@bank',
      payeeName: 'Acme Corp',
      amount:    '250.00',
      transactionNote: 'Order #5678'
    }).then(setQrData);
  }, []);

  return (
    <div>
      {qrData.qr
        ? <UPIQRComponent
            qr={qrData.qr}
            intent={qrData.intent}
            size="180px"
            alt="Pay Acme via UPI"
          />
        : <p>Loading QR code…</p>
      }
    </div>
  );
}

export default App;
```

---


## API Reference: `generateUPIQR()`

| Method                  | Description                                 | Parameters                                                                                                                                          | Returns                          |
| ----------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `generateUPIQR(options)`| Generate UPI QR & intent string asynchronously | **options** (object)<br>• `payeeVPA` **(string)** – Payee’s Virtual Payment Address (required)<br>• `payeeName` **(string)** – Display name (required)<br>• `amount` **(string)** – UPI amount<br>• `transactionNote` **(string)** – Note/memo<br>• `transactionRef` **(string)** – Reference ID<br>• `url` **(string)** – Callback URL<br>• `currency` **(string)** – Currency code (default: `"INR"`) | `Promise<{ qr: string; intent: string }>` |

---


## Component Props: `UPIQRComponent`

| Prop     | Type     | Required | Default    | Description                                       |
| -------- | -------- | -------- | ---------- | ------------------------------------------------- |
| `qr`     | `string` | ✓        | –          | Base64-encoded data URI of the QR code image      |
| `intent` | `string` | ✓        | –          | UPI deep-link URL (e.g., `upi://pay?…`)           |
| `alt`    | `string` | ✗        | `"UPI QR Code"` | Alt text for the `<img>`                        |
| `size`   | `string` | ✗        | `"200px"`  | Width & height of the QR code (e.g., `"150px"`)   |

```jsx
<UPIQRComponent
  qr={qrData.qr}
  intent={qrData.intent}
  alt="Pay Acme"
  size="250px"
/>
```

---


## Production Tips

- **Caching:** Generate the QR once per invoice/order and cache the result to avoid repeated CPU work.  
- **CDN Delivery:** You can serve the Base64 string as an `<img>` src or convert it to a binary PNG and host on a CDN.  
- **Security:** Never expose your merchant secrets in the client—only pass public UPI data.  
- **Deep Linking:** On mobile devices, clicking the intent link should open the UPI app automatically.

![Sample UPI QR Code](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOEAAADhCAIAAAC...)  
*(Replace above with your generated QR code in production.)*

---


## Author & License

**Author:** sk-py  
**License:** ISC

---


## Publishing Scope

This package is published under the [@sk-py](https://www.npmjs.com/~sk-py) scope on npm:

```bash
npm install @sk-py/upi-qr
```

---


## Contributing

1. Fork the repository: `https://github.com/sk-py/upi-qr`  
2. Create a feature branch: `git checkout -b feature/my-feature`  
3. Commit your changes & tests: `git commit -m "Add my feature"`  
4. Push to your branch: `git push origin feature/my-feature`  
5. Open a Pull Request  

Feel free to file issues and suggest improvements!  
Happy coding! 🚀