Integration Guide

Overview

UPI Scanner is a dynamic QR code generation service that allows you to accept UPI payments directly into your bank account with 0% transaction fees. This documentation will guide you through the integration process.

Getting Started

Prerequisites

• A registered UPI Scanner merchant account
• Your API token (available in the Developers section)
• A webhook URL to receive payment notifications
• Basic knowledge of REST APIs

Step 1: Register Your Account

1. Visit Register Page
2. Complete the registration form with your business details
3. Verify your email address
4. Wait for account approval

Step 2: Get Your API Credentials

1. Login to your Dashboard
2. Navigate to Developers section
3. Generate your API token
4. Configure your webhook URL

Authentication

All API requests require authentication using your unique API token. Include your user_token in every API request.

{
  "user_token": "your_api_token_here"
}

Create Order API

Create a new payment order and receive a payment URL with a dynamic QR code.

Endpoint

https://upiscanner.com/api/create-order

Request Parameters

Request Example

{
  "customer_mobile": "9876543210",
  "user_token": "your_api_token_here",
  "amount": "500",
  "order_id": "ORDER123456789",
  "redirect_url": "https://yourwebsite.com/payment-success",
  "remark1": "Product Purchase",
  "remark2": "Customer ID: 12345"
}

Success Response

{
  "status": true,
  "message": "Order Created Successfully",
  "result": {
    "orderId": "ORDER123456789",
    "payment_url": "https://upiscanner.com/payment/pay.php?data=encoded_data"
  }
}

Error Response

{
  "status": false,
  "message": "order_id already exists"
}

Check Order Status API

Check the current status of a payment order using the order ID.

Endpoint

https://upiscanner.com/api/check-order-status

Request Parameters

Request Example

{
  "user_token": "your_api_token_here",
  "order_id": "ORDER123456789"
}

Success Response

{
  "status": "COMPLETED",
  "message": "Transaction Successfully",
  "result": {
    "txnStatus": "COMPLETED",
    "resultInfo": "Transaction Success",
    "orderId": "ORDER123456789",
    "status": "SUCCESS",
    "amount": "500",
    "date": "2024-01-12 13:22:08",
    "utr": "454525454245"
  }
}

Possible Status Values

• PENDING - Payment is pending
• COMPLETED - Payment successful
• FAILED - Payment failed or expired

Webhook Integration

Webhooks allow you to receive real-time payment notifications. Configure your webhook URL in the Developers section.

Webhook Payload

When a payment is completed, we'll send a POST request to your webhook URL with the following data:

{
  "order_id": "ORDER123456789",
  "status": "SUCCESS",
  "amount": "500",
  "utr": "454525454245",
  "customer_mobile": "9876543210",
  "date": "2024-01-12 13:22:08",
  "remark1": "Product Purchase",
  "remark2": "Customer ID: 12345"
}

Webhook Best Practices

• Always verify the order_id exists in your system
• Check if the order hasn't been processed already
• Validate the amount matches your records
• Respond with HTTP 200 status to acknowledge receipt
• Process the webhook asynchronously if possible

Payment Flow

Understanding the complete payment flow:

1. Create Order: Your server calls the Create Order API
2. Redirect Customer: Redirect customer to the payment_url
3. Customer Pays: Customer scans QR code and completes payment
4. Webhook Notification: We send payment notification to your webhook
5. Verify Status: (Optional) Call Check Order Status API
6. Complete Order: Process the order in your system

Code Examples

PHP Example

<?php
// Create Order
$url = 'https://upiscanner.com/api/create-order';
$data = [
    'user_token' => 'your_api_token_here',
    'customer_mobile' => '9876543210',
    'amount' => '500',
    'order_id' => 'ORDER' . time(),
    'redirect_url' => 'https://yourwebsite.com/success',
    'remark1' => 'Product Purchase',
    'remark2' => 'Customer ID: 12345'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['status']) {
    // Redirect to payment URL
    header('Location: ' . $result['result']['payment_url']);
    exit;
} else {
    echo 'Error: ' . $result['message'];
}
?>

Node.js Example

const axios = require('axios');
const querystring = require('querystring');

async function createOrder() {
  const data = {
    user_token: 'your_api_token_here',
    customer_mobile: '9876543210',
    amount: '500',
    order_id: 'ORDER' + Date.now(),
    redirect_url: 'https://yourwebsite.com/success',
    remark1: 'Product Purchase',
    remark2: 'Customer ID: 12345'
  };

  try {
    const response = await axios.post(
      'https://upiscanner.com/api/create-order',
      querystring.stringify(data),
      {
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        }
      }
    );

    if (response.data.status) {
      console.log('Payment URL:', response.data.result.payment_url);
      // Redirect user to payment URL
    } else {
      console.error('Error:', response.data.message);
    }
  } catch (error) {
    console.error('Request failed:', error);
  }
}

createOrder();

Python Example

import requests
import time

def create_order():
    url = 'https://upiscanner.com/api/create-order'
    data = {
        'user_token': 'your_api_token_here',
        'customer_mobile': '9876543210',
        'amount': '500',
        'order_id': f'ORDER{int(time.time())}',
        'redirect_url': 'https://yourwebsite.com/success',
        'remark1': 'Product Purchase',
        'remark2': 'Customer ID: 12345'
    }
    
    response = requests.post(url, data=data)
    result = response.json()
    
    if result['status']:
        print('Payment URL:', result['result']['payment_url'])
        # Redirect user to payment URL
    else:
        print('Error:', result['message'])

create_order()

Webhook Handler Example (PHP)

<?php
// Webhook handler
$webhook_data = $_POST;

// Verify required fields
if (isset($webhook_data['order_id']) && isset($webhook_data['status'])) {
    $order_id = $webhook_data['order_id'];
    $status = $webhook_data['status'];
    $amount = $webhook_data['amount'];
    $utr = $webhook_data['utr'];
    
    // Verify order exists in your database
    // Check if order hasn't been processed already
    
    if ($status === 'SUCCESS') {
        // Update order status in your database
        // Send confirmation email to customer
        // Process the order
        
        // Log the transaction
        error_log("Payment successful for order: $order_id, UTR: $utr");
        
        // Respond with 200 OK
        http_response_code(200);
        echo json_encode(['status' => 'received']);
    } else {
        // Handle failed payment
        error_log("Payment failed for order: $order_id");
        http_response_code(200);
        echo json_encode(['status' => 'received']);
    }
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid webhook data']);
}
?>

Testing

Before going live, thoroughly test your integration in a development environment.

Testing Checklist

• ✓ Create order with valid parameters
• ✓ Handle duplicate order_id errors
• ✓ Test webhook reception and processing
• ✓ Verify order status checking
• ✓ Test payment timeout (30 minutes)
• ✓ Handle network failures gracefully
• ✓ Test with different payment amounts
• ✓ Verify redirect_url functionality

Security Best Practices

API Token Security

• Never expose your API token in client-side code
• Store API tokens securely (environment variables)
• Regenerate tokens if compromised
• Use HTTPS for all API communications

Webhook Security

• Always verify order_id exists in your system
• Check for duplicate webhook deliveries
• Validate amount matches your records
• Use the Check Order Status API for verification
• Implement rate limiting on webhook endpoint

Data Validation

• Validate all input parameters before API calls
• Sanitize user inputs to prevent injection attacks
• Use prepared statements for database queries
• Implement proper error handling

Troubleshooting

Common Issues

Order Creation Fails

• Verify your API token is correct and active
• Check that order_id is unique
• Ensure all required parameters are provided
• Verify redirect_url is a valid URL

Webhook Not Received

• Check webhook URL is publicly accessible
• Verify webhook URL is configured correctly
• Check server logs for incoming requests
• Ensure webhook endpoint returns HTTP 200

Payment Status Not Updating

• Wait for webhook notification (may take a few seconds)
• Use Check Order Status API to verify
• Check if order has expired (30-minute timeout)

Need Help?

If you're still experiencing issues, please contact our support team:

• Email: support@upiscanner.com
• Support Portal: Submit a ticket
• WhatsApp: Available 24/7

Quick Start Summary