Razorpay Python Client

The POS Gateway supports two communication modes, which dictate how you interact with the hardware and which parameters are required.

Device Activity operations are categorized by two communication modes:

1. Wired Mode (device_mode="wired"):

   • device_id is optional.
   • Used for direct device connections.

2. Wireless Mode (device_mode="wireless"):

   • device_id is required.
   • Used for wireless device communication.

For a complete POS workflow, create a Razorpay Order first, then use that order_id to initiate the device activity. This ensures the transaction is linked to a valid order in the Razorpay dashboard.

# Create order with device_mode
order = client.order.create({
    "amount": 50000,
    "currency": "INR",
    "receipt": "order_001"
}, device_mode="wired")

# Initiate device checkout using the created order ID
checkout = client.device_activity.create({
    "device_id": "2841158834",
    "action": "initiate_checkout",
    "notes": {"order_id": order['id']},
    "initiate_checkout": {
        "name": "Acme Corp",
        "amount": order['amount'],
        "currency": order['currency'],
        "description": "POS Transaction",
        "type": "in_person",
        "order_id": order['id'],
        "prefill": {
            "method": "upi"
        }
    }
}, device_mode="wired")

For transient errors like DEVICE_BUSY, DEVICE_TIMEOUT, or DEVICE_DISCONNECTED, it is recommended to implement an exponential backoff retry strategy to improve reliability.

import time

def retry_device_operation(operation_func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return operation_func()
        except Exception as e:
            error_code = getattr(e, 'code', None)
            
            # Retry for transient errors
            if error_code in ['DEVICE_BUSY', 'DEVICE_TIMEOUT', 'DEVICE_DISCONNECTED']:
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)  # Exponential backoff
                    continue
            raise e

To integrate with the POS Gateway, initialize the razorpay.Client using your key_id and key_secret.

For production, the default base_url is https://api.razorpay.com. For local development or testing with a POS Gateway simulator, you must specify the base_url pointing to your local host.

import razorpay

# Production initialization
client = razorpay.Client(auth=('your_key_id', 'your_key_secret'))

# Local development/testing initialization
client = razorpay.Client(
    auth=('your_key_id', 'your_key_secret'),
    base_url='http://localhost:PORT'
)

To use the client, import razorpay and initialize the razorpay.Client using your API Key and API Secret. You can find these credentials in your Razorpay Dashboard at https://dashboard.razorpay.com/#/app/keys.

You can also enable the retry mechanism for failed API calls using client.enable_retry(True).

import razorpay
client = razorpay.Client(auth=("<YOUR_API_KEY>", "<YOUR_API_SECRET>"))

client.enable_retry(True)  # Enable retry mechanism for failed API calls

Install the razorpay package using pip to begin interacting with the Razorpay API programmatically.

$ pip install razorpay

After initiating a checkout via the Device Activity API, you should check the status field in the response to determine the next steps for your application flow.

Possible statuses:

• processing: Checkout has been initiated; wait for completion.
• completed: Checkout was successful.
• failed: Checkout failed. You should inspect the error object for the code and reason to understand why.

# Check status in response
if response['status'] == 'processing':
    print("Checkout initiated, waiting for completion...")
elif response['status'] == 'completed':
    print("Checkout completed successfully!")
elif response['status'] == 'failed':
    error_code = response['error']['code']
    error_reason = response['error']['reason']
    print(f"Checkout failed: {error_code} - {error_reason}")

For card authentication, follow the OTP lifecycle:

1. Generate OTP: Call client.payment.otpGenerate(paymentId) to get the required actions (e.g., otp_submit, otp_resend).
2. Submit OTP: Call client.payment.otpSubmit(paymentId, {"otp": "..."}) with the customer's OTP to complete the transaction.

# 1. Generate
client.payment.otpGenerate(paymentId)

# 2. Submit
client.payment.otpSubmit(paymentId, {
 	"otp": "12345"
 })

When interacting with Device Activity APIs, you may encounter BadRequestError or specific API error codes in the response.

Common Client-Side Errors:

• BadRequestError: Occurs if device_mode is invalid (must be wired or wireless) or if device_id is missing while in wireless mode.

API Error Codes (returned in response):

• BAD_REQUEST_ERROR with reason device_not_connected: The device is not currently connected. Check connection and retry.
• BAD_REQUEST_ERROR with reason checkout_not_found: The session was not found. Ensure a checkout was successfully initiated before attempting to close it.

from razorpay.errors import BadRequestError

try:
    response = client.device_activity.create({
        "device_id": "2841158834",
        "action": "initiate_checkout"
    }, device_mode="invalid_mode")
except BadRequestError as e:
    print(f"Error: {e}")