💳 Payment Service

The Payment Service handles the full payment lifecycle—from order creation and customer details to payment capture and verification. It supports multiple payment flows, tracks authorization, and integrates refund and settlement URLs.

---

🧾 Order Structure

Order

Field	Type	Description
id	string/ObjectID	Internal unique identifier
order_id	string	Public-facing order ID
order_amount	float64	Total amount for the order
order_currency	string	Currency (e.g., INR, USD)
customer_details	CustomerDetails	Customer info (name, email, phone, ID)
order_meta	OrderMeta	Return/notify URLs and payment method metadata
order_expiry_time	timestamp	When the order becomes invalid
order_note	string	Optional notes for order
order_status	string	Status of the order (e.g., created, paid, failed)
order_tags	OrderTags	Optional categorization tags
order_created	timestamp	When the order was created
payment_session_id	string	Unique ID used for initiating payment
payments	Payments	URL reference to payment resource
refunds	Refunds	URL reference to refund resource
settlements	Settlements	URL reference to settlement resource

---

👤 CustomerDetails

Field	Type	Description
customer_id	uint32	Customer ID in the system
org_id	uint32	Associated organization ID
customer_name	string	Full name
customer_email	string	Email address
customer_phone	string	Mobile number

---

🌐 OrderMeta

Field	Type	Description
return_url	string	Redirect after payment
notify_url	string	Backend webhook for payment status
payment_methods	string	Allowed methods (e.g., upi, card)

---

🧾 OrderTags

Used for analytics or classification.

Field	Type	Example
name	string	"Retail"
age	string	"New"

---

💰 Payment Structure

Field	Type	Description
id	string/ObjectID	Internal unique payment ID
order_id	string	Associated order
entity	string	Payment gateway/provider (e.g., Razorpay)
payment_currency	string	Currency
error_details	map[string]string[]	Error key-value data
order_amount	float64	Amount from order
is_captured	bool	Has the payment been captured
payment_group	string	Internal categorization or batch ID
authorization	Authorization	Auth and capture details
payment_method	list[map[string]interface]	Dynamic key-value method data
payment_amount	float64	Final amount paid
payment_time	timestamp	Initiated time
payment_completion_time	timestamp	Time of completion
payment_status	string	Paid, failed, pending, etc.
payment_message	string	Gateway message or user-facing message
bank_reference	string	Bank/gateway reference ID
auth_id	string	Authorization ID

---

🔐 Authorization

Field	Type	Description
action	string	e.g., "capture"
status	string	e.g., "success", "failed"
captured_amount	float64	Amount successfully captured
start_time	timestamp	Auth start
end_time	timestamp	Auth end
approve_by	timestamp	Deadline for approval
action_reference	string	Transaction ID or internal ref
action_time	timestamp	Actual time of action

---

🧪 RPC Services

PaymentService

RPC	Request Type	Response Type	Description
CreateOrder	CreateOrderRequest	CreateOrderResponse	Initiates a new order with basic details
VerifyPayment	VerifyPaymentRequest	VerifyPaymentResponse	Checks payment status of an order

---

🎯 Requests & Responses

CreateOrderRequest

{
  "customer_name": "Alice",
  "customer_email": "alice@example.com",
  "customer_phone": "9999999999",
  "order_amount": 299.99
}

CreateOrderResponse

{
  "payment_session_id": "sess_abc123",
  "return_url": "https://return.url",
  "order_id": "order_xyz789"
}

---

VerifyPaymentRequest

{
  "order_id": "order_xyz789"
}

VerifyPaymentResponse

{
  "message": "Payment successful",
  "code": "200",
  "status": "success"
}