# UnelmaPay Merchant Integration Guide

## 🚀 Overview

UnelmaPay provides a simple, secure payment gateway similar to eSewa, allowing merchants to easily integrate online payments into their applications. This guide will walk you through the integration process step by step.

## 🔑 Getting Started

### 1. Get Your Credentials

**For Testing:**
- **Merchant ID:** `TEST_MERCHANT_001`
- **Secret Key:** `test_secret_key_unelmapay_2024`
- **Test User ID:** `9800000001`
- **Test Password:** `Test@123`
- **Test PIN:** `1234`

**For Production:**
Contact our support team at `developer@unelmapay.com.np` to get your production credentials.

### 2. API Endpoints

| Environment | Payment API | Verification API |
|-------------|-------------|------------------|
| **Sandbox** | `https://sandbox.unelmapay.com/api/v1/payment` | `https://sandbox.unelmapay.com/api/v1/verify` |
| **Production** | `https://api.unelmapay.com/v1/payment` | `https://api.unelmapay.com/v1/verify` |

## 💳 Integration Methods

### Method 1: Form-Based Integration (Recommended for Simple Sites)

This method is similar to eSewa's integration - just create an HTML form and redirect users to UnelmaPay.

```html
<form action="https://sandbox.unelmapay.com/api/v1/payment" method="POST">
    <input type="hidden" name="merchant_id" value="YOUR_MERCHANT_ID">
    <input type="hidden" name="amount" value="1000">
    <input type="hidden" name="currency" value="NPR">
    <input type="hidden" name="product_name" value="Your Product">
    <input type="hidden" name="order_id" value="ORDER_123">
    <input type="hidden" name="success_url" value="https://yoursite.com/success">
    <input type="hidden" name="fail_url" value="https://yoursite.com/fail">
    <input type="hidden" name="signature" value="GENERATED_SIGNATURE">
    <button type="submit">Pay with UnelmaPay</button>
</form>
```

### Method 2: JavaScript SDK Integration (Recommended for Modern Apps)

Include our JavaScript SDK for a more integrated experience:

```html
<!-- Include required libraries -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script>
<script src="https://developer.unelmapay.com.np/js/unelmapay-sdk-v2.js"></script>

<script>
// Initialize SDK
UnelmaPay.init({
    merchantId: 'YOUR_MERCHANT_ID',
    secretKey: 'YOUR_SECRET_KEY',
    environment: 'production' // or 'sandbox'
});

// Create payment
UnelmaPay.createPayment({
    amount: 1000,
    currency: 'NPR',
    productName: 'Your Product',
    orderId: 'ORDER_123',
    successUrl: 'https://yoursite.com/success',
    failUrl: 'https://yoursite.com/fail'
});
</script>
```

### Method 3: Direct API Integration

For custom implementations, use our REST API directly:

```javascript
// Payment Request
fetch('https://sandbox.unelmapay.com/api/v1/payment', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        merchant_id: 'YOUR_MERCHANT_ID',
        amount: 1000,
        currency: 'NPR',
        product_name: 'Your Product',
        order_id: 'ORDER_123',
        success_url: 'https://yoursite.com/success',
        fail_url: 'https://yoursite.com/fail',
        signature: 'GENERATED_SIGNATURE',
        api_request: true
    })
})
.then(response => response.json())
.then(data => {
    if (data.status === 'success') {
        window.location.href = data.payment_url;
    }
});
```

## 🔐 Signature Generation (Security)

UnelmaPay uses HMAC-SHA256 signatures for security, similar to eSewa's approach.

### Signature Algorithm

1. Create signature string: `merchant_id,amount,currency,order_id,product_name`
2. Generate HMAC-SHA256 hash using your secret key
3. Encode result in Base64

### Implementation Examples

**JavaScript:**
```javascript
// Using crypto-js library
const signatureString = merchantId + ',' + amount + ',' + currency + ',' + orderId + ',' + productName;
const hash = CryptoJS.HmacSHA256(signatureString, secretKey);
const signature = CryptoJS.enc.Base64.stringify(hash);
```

**PHP:**
```php
$signatureString = $merchantId . ',' . $amount . ',' . $currency . ',' . $orderId . ',' . $productName;
$signature = base64_encode(hash_hmac('sha256', $signatureString, $secretKey, true));
```

**Python:**
```python
import hmac
import hashlib
import base64

signature_string = f"{merchant_id},{amount},{currency},{order_id},{product_name}"
signature = base64.b64encode(
    hmac.new(secret_key.encode(), signature_string.encode(), hashlib.sha256).digest()
).decode()
```

**Node.js:**
```javascript
const crypto = require('crypto');

const signatureString = `${merchantId},${amount},${currency},${orderId},${productName}`;
const signature = crypto
    .createHmac('sha256', secretKey)
    .update(signatureString)
    .digest('base64');
```

## ✅ Transaction Verification

After a successful payment, verify the transaction to prevent fraud:

### Using JavaScript SDK:
```javascript
UnelmaPay.verifyTransaction('PAYMENT_REF', function(result) {
    if (result.status === 'success') {
        console.log('Payment verified:', result.transaction_details);
        // Process successful payment
    } else {
        console.log('Verification failed:', result.message);
        // Handle failed verification
    }
});
```

### Using Direct API:
```javascript
fetch('https://sandbox.unelmapay.com/api/v1/verify', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        merchant_id: 'YOUR_MERCHANT_ID',
        payment_ref: 'PAYMENT_REFERENCE',
        signature: 'VERIFICATION_SIGNATURE'
    })
})
.then(response => response.json())
.then(data => {
    if (data.status === 'success') {
        // Payment verified successfully
        console.log(data.transaction_details);
    }
});
```

### Verification Signature

For verification, create signature string: `merchant_id,payment_ref,amount`

## 🔄 Payment Flow

1. **Customer initiates payment** on your website
2. **Your site creates payment request** with signature
3. **Customer redirected** to UnelmaPay payment page
4. **Customer logs in** with UnelmaPay credentials
5. **Customer confirms payment** and completes transaction
6. **Customer redirected back** to your success/fail URL
7. **Your site verifies transaction** using verification API
8. **You process the order** based on verification result

## 📋 Required Parameters

### Payment Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `merchant_id` | string | Yes | Your merchant ID |
| `amount` | decimal | Yes | Payment amount |
| `currency` | string | Yes | Currency code (NPR) |
| `product_name` | string | Yes | Product/service name |
| `order_id` | string | Yes | Your unique order ID |
| `success_url` | string | Yes | Success redirect URL |
| `fail_url` | string | Yes | Failure redirect URL |
| `signature` | string | Recommended | HMAC-SHA256 signature |

### Verification Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `merchant_id` | string | Yes | Your merchant ID |
| `payment_ref` | string | Yes | Payment reference from UnelmaPay |
| `signature` | string | Recommended | Verification signature |

## 🛠️ Testing

### Test Scenarios

1. **Successful Payment:**
   - Use test credentials
   - Complete payment flow
   - Verify transaction status

2. **Failed Payment:**
   - Cancel payment on payment page
   - Check failure handling

3. **Signature Verification:**
   - Test with correct signature
   - Test with incorrect signature
   - Verify security measures

### Test URLs

- **Payment Page:** Use sandbox environment
- **Success URL:** `https://yoursite.com/success?payment_ref=UP123456789`
- **Fail URL:** `https://yoursite.com/fail?error=payment_cancelled`

## 🚨 Error Handling

### Common Error Responses

```json
{
    "status": "error",
    "code": 400,
    "message": "Invalid signature"
}
```

### Error Codes

| Code | Description |
|------|-------------|
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid merchant ID |
| 403 | Forbidden - Invalid signature |
| 404 | Not Found - Transaction not found |
| 500 | Internal Server Error |

## 🔧 Advanced Features

### Webhooks (Coming Soon)

Set up webhooks to receive real-time payment notifications:

```json
{
    "event": "payment.completed",
    "payment_ref": "UP123456789",
    "merchant_id": "YOUR_MERCHANT_ID",
    "amount": 1000,
    "currency": "NPR",
    "order_id": "ORDER_123",
    "timestamp": "2024-01-01T12:00:00Z"
}
```

### Custom Styling

Customize the payment page appearance by providing CSS parameters in your payment request.

## 📞 Support

- **Email:** developer@unelmapay.com.np
- **Documentation:** https://developer.unelmapay.com.np
- **Examples:** https://developer.unelmapay.com.np/examples
- **Status Page:** https://status.unelmapay.com.np

## 📚 Additional Resources

- [API Reference](./api-reference.md)
- [SDK Documentation](./sdk-documentation.md)
- [Security Best Practices](./security-guide.md)
- [Migration from Other Gateways](./migration-guide.md)

---

**Need help?** Contact our developer support team at developer@unelmapay.com.np