Skip to content

Commit 8266419

Browse files
PayManiRazorPayManiRazor
authored
Merge pull request #311 from razorpay/feature/add-pos-documentation
docs: add Device Activity and POS Gateway integration documentation
2 parents 489ef61 + c933ba4 commit 8266419

File tree

3 files changed

+1132
-1
lines changed

3 files changed

+1132
-1
lines changed

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Razorpay Python Client
22

3-
[![PyPI Version](https://img.shields.io/pypi/v/razorpay.svg)](https://pypi.python.org/pypi/razorpay) [![Coverage Status](https://coveralls.io/repos/github/razorpay/razorpay-python/badge.svg?branch=master)](https://coveralls.io/github/razorpay/razorpay-python?branch=master) [![PyPI](https://img.shields.io/badge/python-3%20%7C%203.4%20%7C%203.5%20%7C%203.6-blue.svg)]() [![License](https://img.shields.io/:license-mit-blue.svg)](https://opensource.org/licenses/MIT)
3+
[![PyPI Version](https://img.shields.io/pypi/v/razorpay.svg)](https://pypi.python.org/pypi/razorpay) [![Coverage Status](https://coveralls.io/repos/github/razorpay/razorpay-python/badge.svg?branch=master)](https://coveralls.io/github/razorpay/razorpay-python?branch=master) [![PyPI](https://img.shields.io/badge/python-3.5%2B-blue.svg)]() [![License](https://img.shields.io/:license-mit-blue.svg)](https://opensource.org/licenses/MIT)
44

55
Python bindings for interacting with the Razorpay API
66

@@ -43,6 +43,10 @@ that both app title and version are strings.
4343

4444
- [Customer](documents/customer.md)
4545

46+
- [Device Activity](documents/deviceActivity.md)
47+
48+
- [POS Gateway Integration](documents/posGateway.md)
49+
4650
- [Token](documents/token.md)
4751

4852
- [Fund](documents/fund.md)

‎documents/deviceActivity.md‎

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
## Device Activity
2+
3+
### Create device activity
4+
5+
```py
6+
client.device_activity.create({
7+
"device_id": "2841158834", # Required for device_mode="wireless", optional for device_mode="wired"
8+
"action": "initiate_checkout", # Required: Action type
9+
"notes": { # Optional: Additional notes
10+
"key1": "value1",
11+
"key2": "value2"
12+
},
13+
"initiate_checkout": { # Required for initiate_checkout
14+
"name": "Acme Corp", # Optional: Business name
15+
"amount": 19900, # Required: Amount in paise (₹199.00)
16+
"currency": "INR", # Required: Currency code
17+
"description": "POS Transaction", # Required: Transaction description
18+
"type": "in_person", # Optional: Transaction type
19+
"order_id": "order_R7vqkfqG3Iw02m", # Required: Order reference
20+
"prefill": { # Optional: Customer prefill data
21+
"name": "Gaurav Kumar",
22+
"email": "gaurav.kumar@example.com",
23+
"contact": "9000090000",
24+
"method": "upi" # Optional: "upi"|"card"
25+
}
26+
}
27+
}, device_mode="wired")
28+
```
29+
30+
**Parameters:**
31+
32+
| Name | Type | Description |
33+
|---------------|--------|--------------------------------------------------------------------------------|
34+
| device_id | string | Device identifier. Required for wireless mode, optional for wired mode |
35+
| action* | string | Action type. Possible values: `initiate_checkout`, `close_checkout` |
36+
| notes | object | A key-value pair for additional information |
37+
| initiate_checkout* | object | Required when action is `initiate_checkout`. Contains checkout details |
38+
| device_mode* | string | Device communication mode. Possible values: `wired`, `wireless` |
39+
40+
**initiate_checkout Object Parameters:**
41+
42+
| Name | Type | Description |
43+
|---------------|--------|--------------------------------------------------------------------------------|
44+
| name* | string | Business name |
45+
| amount* | integer| Amount in paise (₹199.00 = 19900) |
46+
| currency* | string | Currency code (e.g., "INR") |
47+
| description* | string | Transaction description |
48+
| type | string | Optional transaction type (e.g., "in_person") |
49+
| order_id* | string | Order reference ID |
50+
| prefill | object | Optional customer prefill data (name, email, contact, method) |
51+
52+
**prefill Object Parameters:**
53+
54+
| Name | Type | Description |
55+
|---------------|--------|--------------------------------------------------------------------------------|
56+
| name | string | Optional customer name |
57+
| email | string | Optional customer email |
58+
| contact | string | Optional customer contact number |
59+
| method | string | Optional payment method: "upi", "card"
60+
61+
**Success Response:**
62+
63+
```json
64+
{
65+
"id": "pda_NVTKa9PL0yessI",
66+
"entity": "device.activity",
67+
"device_id": "2841158834",
68+
"action": "initiate_checkout",
69+
"initiate_checkout": {
70+
"name": "Acme Corp",
71+
"amount": 19900,
72+
"currency": "INR",
73+
"description": "POS Transaction",
74+
"order_id": "order_R7vqkfqG3Iw02m",
75+
"prefill": {
76+
"name": "Gaurav Kumar",
77+
"email": "gaurav.kumar@example.com",
78+
"contact": "9000090000",
79+
"method": "upi"
80+
}
81+
},
82+
"status": "processing",
83+
"error": null
84+
}
85+
```
86+
87+
**Failure Response:**
88+
89+
```json
90+
{
91+
"id": "pda_NVTKa9PL0yessI",
92+
"entity": "device.activity",
93+
"device_id": "2841158834",
94+
"action": "initiate_checkout",
95+
"initiate_checkout": {
96+
"name": "Acme Corp",
97+
"amount": 19900,
98+
"currency": "INR",
99+
"description": "POS Transaction",
100+
"order_id": "order_R7vqkfqG3Iw02m",
101+
"prefill": {
102+
"name": "Gaurav Kumar",
103+
"email": "gaurav.kumar@example.com",
104+
"contact": "9000090000",
105+
"method": "upi"
106+
}
107+
},
108+
"status": "failed",
109+
"error": {
110+
"code": "BAD_REQUEST_ERROR",
111+
"reason": "device_not_connected"
112+
}
113+
}
114+
```
115+
116+
**Status Values:**
117+
- `"processing"` - Checkout is being processed
118+
- `"completed"` - Checkout completed successfully
119+
- `"failed"` - Checkout failed with error details
120+
121+
---
122+
123+
### Create device activity (Close Checkout)
124+
125+
```py
126+
client.device_activity.create({
127+
"device_id": "2841158834",
128+
"action": "close_checkout"
129+
}, device_mode="wireless")
130+
```
131+
132+
**Parameters:**
133+
134+
| Name | Type | Description |
135+
|---------------|--------|--------------------------------------------------------------------------------|
136+
| device_id | string | Device identifier. Required for wireless mode, optional for wired mode |
137+
| action* | string | Action type: `close_checkout` |
138+
| device_mode* | string | Device communication mode. Possible values: `wired`, `wireless` |
139+
140+
**Success Response:**
141+
142+
```json
143+
{
144+
"id": "pda_NVTKa9PL0yessJ",
145+
"entity": "device.activity",
146+
"device_id": "2841158834",
147+
"action": "close_checkout",
148+
"status": "completed",
149+
"error": null
150+
}
151+
```
152+
153+
**Failure Response:**
154+
155+
```json
156+
{
157+
"id": "pda_NVTKa9PL0yessJ",
158+
"entity": "device.activity",
159+
"device_id": "2841158834",
160+
"action": "close_checkout",
161+
"status": "failed",
162+
"error": {
163+
"code": "BAD_REQUEST_ERROR",
164+
"reason": "checkout_not_found"
165+
}
166+
}
167+
```
168+
---
169+
170+
## Device Modes
171+
172+
### Wired Mode
173+
- **device_mode**: `"wired"`
174+
- **device_id**: Optional
175+
- Direct device connection
176+
177+
### Wireless Mode
178+
- **device_mode**: `"wireless"`
179+
- **device_id**: Required
180+
- Wireless device communication
181+
182+
---
183+
184+
## Error Handling
185+
186+
```py
187+
from razorpay.errors import BadRequestError
188+
189+
try:
190+
response = client.device_activity.create({
191+
"device_id": "2841158834",
192+
"action": "initiate_checkout"
193+
}, device_mode="invalid_mode")
194+
except BadRequestError as e:
195+
print(f"Error: {e}")
196+
# Output: Invalid device mode. Allowed values are 'wired' and 'wireless'.
197+
```
198+
199+
**Common Errors:**
200+
201+
| Error | Description | Solution |
202+
|-------|-------------|----------|
203+
| `BadRequestError` | Invalid device_mode parameter | Use only `"wired"` or `"wireless"` |
204+
| `BadRequestError` | Missing activity_id | Provide valid activity ID for get_status |
205+
| `BadRequestError` | Missing device_id in wireless mode | Include device_id when using wireless mode |
206+
207+
**API Error Responses:**
208+
209+
| Error Code | Reason | Description | Solution |
210+
|------------|--------|-------------|----------|
211+
| `BAD_REQUEST_ERROR` | `device_not_connected` | Device is not connected | Check device connection and try again |
212+
| `BAD_REQUEST_ERROR` | `checkout_not_found` | Checkout session not found | Verify checkout was initiated before closing |
213+
214+
---
215+
216+
## Example Usage
217+
218+
```py
219+
import razorpay
220+
221+
# Initialize client
222+
client = razorpay.Client(auth=('key_id', 'key_secret'), base_url='http://localhost:PORT')
223+
224+
try:
225+
# Step 1: Initiate checkout
226+
activity = client.device_activity.create({
227+
"device_id": "2841158834",
228+
"action": "initiate_checkout",
229+
"notes": {"merchant_id": "12345"},
230+
"initiate_checkout": {
231+
"name": "Acme Corp",
232+
"amount": 19900,
233+
"currency": "INR",
234+
"description": "POS Transaction",
235+
"type": "in_person", # Optional
236+
"order_id": "order_R7vqkfqG3Iw02m",
237+
"prefill": {
238+
"name": "Gaurav Kumar",
239+
"email": "gaurav.kumar@example.com",
240+
"contact": "9000090000",
241+
"method": "upi"
242+
}
243+
}
244+
}, device_mode="wired")
245+
246+
activity_id = activity['id']
247+
print(f"Checkout initiated: {activity_id}")
248+
249+
# Step 2: Check status
250+
status = client.device_activity.get_status(activity_id, device_mode="wired")
251+
print(f"Current status: {status['status']}")
252+
253+
# Step 3: Close checkout when done
254+
close_response = client.device_activity.create({
255+
"device_id": "2841158834",
256+
"action": "close_checkout"
257+
}, device_mode="wired")
258+
259+
print("Checkout closed successfully")
260+
261+
except Exception as e:
262+
print(f"Error: {e}")
263+
```
264+
265+
---
266+
267+
## Integration with Order APIs
268+
269+
Device Activity APIs work seamlessly with Order APIs for complete POS integration:
270+
271+
```py
272+
# Create order with device_mode
273+
order = client.order.create({
274+
"amount": 50000,
275+
"currency": "INR",
276+
"receipt": "order_001"
277+
}, device_mode="wired")
278+
279+
# Initiate device checkout
280+
checkout = client.device_activity.create({
281+
"device_id": "2841158834",
282+
"action": "initiate_checkout",
283+
"notes": {"order_id": order['id']},
284+
"initiate_checkout": {
285+
"name": "Acme Corp",
286+
"amount": order['amount'],
287+
"currency": order['currency'],
288+
"description": "POS Transaction",
289+
"type": "in_person",
290+
"order_id": order['id'],
291+
"prefill": {
292+
"method": "upi"
293+
}
294+
}
295+
}, device_mode="wired")
296+
297+
# Monitor checkout status
298+
status = client.device_activity.get_status(checkout['id'], device_mode="wired")
299+
```

0 commit comments

Comments
 (0)