POS Gateway - Usage Examples
Last Updated: 2026-07-09
Terminal Authentication
POS terminals authenticate with a PIN rather than a username/password. The login endpoint is public (no prior token required).
Authenticate a terminal
curl -s -X POST https://api.djanity.com/pos/auth/terminal-login/ \
-H "Content-Type: application/json" \
-d '{
"employee_id": "employee-sanity-id-abc123",
"pin_code": "1234",
"store_id": "store-sanity-id-xyz789",
"terminal_id": "MAIN-POS-01"
}'
Response (200 OK):
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"session_id": "sess-uuid-here",
"expires_at": "2026-02-27T22:00:00Z",
"user": {
"id": "employee-sanity-id-abc123",
"name": "Jane Smith",
"employee_number": "EMP001",
"role": "cashier"
},
"store": {
"id": "store-sanity-id-xyz789",
"name": "Main Street Store"
}
}
Use the returned token as the Bearer token for all subsequent POS requests.
Log out a terminal
curl -s -X POST https://api.djanity.com/pos/auth/terminal-logout/ \
-H "Authorization: Bearer <token>"
Response:
{"success": true, "message": "Logged out successfully"}
POS Transactions
Create a sale transaction
curl -s -X POST https://api.djanity.com/pos/transactions/create/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"store_id": "store-sanity-id-xyz789",
"employee_id": "employee-sanity-id-abc123",
"line_items": [
{
"product_variant_id": "variant-uuid-001",
"sku": "SKU-CLASSIC-TEE-M-BLK",
"quantity": 2,
"unit_price": "19.99",
"subtotal": "39.98"
}
],
"subtotal": "39.98",
"tax_amount": "3.20",
"total_amount": "43.18"
}'
Response (201 Created):
{
"success": true,
"transaction": {
"transaction_id": "saleTransaction_abc123xyz",
"status": "pending",
"total_amount": "43.18",
"created_at": "2026-02-27T14:30:00Z"
}
}
Process payment for a transaction
curl -s -X POST \
"https://api.djanity.com/pos/transactions/saleTransaction_abc123xyz/payment/" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"payment_method_id": "paymentMethod_cash",
"tendered_amount": "50.00"
}'
Response (202 Accepted):
{
"success": true,
"transaction": {
"transaction_id": "saleTransaction_abc123xyz",
"status": "completed",
"total_amount": "43.18",
"total_paid": "50.00",
"change_due": "6.82",
"completed_at": "2026-02-27T14:31:00Z"
}
}
Cash Drawer
Open the cash drawer
curl -s -X POST https://api.djanity.com/pos/cash-drawer/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"operation": "open", "reason": "sale"}'
Response (200 OK):
{
"success": true,
"drawer_operation": {
"operation_id": "drawer-op-uuid",
"reason": "sale",
"timestamp": "2026-02-27T14:31:05Z"
}
}
Manager Approval
Request manager approval for a discount
curl -s -X POST https://api.djanity.com/pos/approvals/request/ \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"request_type": "discount",
"amount": "10.00",
"reason": "Loyalty customer, 25% off",
"details": {"original_price": "43.18", "discount_percent": 25}
}'
Response (201 Created):
{
"success": true,
"request_id": "approval-uuid-here",
"expires_at": "2026-02-27T14:41:00Z"
}
Check approval status
curl -s "https://api.djanity.com/pos/approvals/status/approval-uuid-here/" \
-H "Authorization: Bearer <token>"
Response (approved):
{
"request_id": "approval-uuid-here",
"status": "approved",
"approved_by": "manager-user-id",
"approved_at": "2026-02-27T14:32:00Z"
}
Health Check
curl -s https://api.djanity.com/pos/health/
Response:
{
"status": "healthy",
"timestamp": "2026-02-27T14:00:00Z",
"version": "1.0.0-gateway",
"service_name": "POS Gateway",
"services": {
"database": true,
"cache": true
}
}