beckn · ravi-prakash-v · Aug 22, 2022 · Dec 26, 2021 · Dec 26, 2021 · Jan 20, 2022
diff --git a/core/v0/api/core.yaml b/core/v0/api/core.yaml
diff --git a/docs/images/rating handshake.png b/docs/images/rating handshake.png
diff --git a/docs/images/sample.png b/docs/images/sample.png
diff --git a/docs/proposals/BECKN-RFC-Rating and Reputation on Beckn Protocol.md b/docs/proposals/BECKN-RFC-Rating and Reputation on Beckn Protocol.md
@@ -0,0 +1,171 @@
+# Rating and Reputation on Beckn Protocol
+
+*Draft 01*
+
+Author:
+=======
+
+Ravi Prakash ([email protected])
+
+Scope
+=====
+
+This document is intended for anyone wishing to design a Rating and Reputation system for beckn protocol enabled Open Networks. This specification is agnostic of any implementation technology but contains examples of run-time JSON objects for the sake of clarity. 
+
+Context
+=======
+
+Customers expect quality in any products and services they have bought. To ensure such quality is maintained, providers usually expect their customers to rate their services and products based on how satisfied they are with the product consumed or service rendered. Most e-commerce systems nowadays implement an online rating system that allows their users to rate the products and services bought on that platform.
+
+Platforms selling physical products usually allow their users to rate the quality of their products and sometimes, the delivery. Business aggregators allow their users to also rate businesses as a whole. Businesses allow their customers to rate the customer support they received. There are many more such entities that can be rated based on the customer's level of satisfaction.
+
+Typically, a rating system allows the consumer to provide a rating value from 1 to 5 where 1 represents lowest quality of service and 5 represents the highest quality of service. In some cases, fractional ratings are also used for further granularity; and in other cases non-numeric values like "Good" or "Bad''; and Ratings from 1 to 10 are also used. The rating value of a particular product or service is typically made visible to the public. A rating system is expected to be fair and transparent to its users, both customers and providers.
+
+In the case of beckn protocol, many such platforms connect to each other via beckn and thus present a new challenge of managing rating and reputation on a decentralized network. (Talk about the challenge presented) due to open commerce networks and the purpose of this document.
+
+For platforms connected to each other in an open commerce network, an interoperable and shared rating and reputation system must be implemented that allows users to rate various entities on the network. The rating system must adhere to the following design principles
+
+1.  Non-repudiability
+
+2.  Privacy protected
+
+3.  Cross-platform compatibility
+
+Abstract
+========
+
+This document defines design specifications to create an interoperable, secure and non-repudiable system for managing Rating and Reputation of various physical and virtual entities on beckn-enabled Open Commerce Networks. It describes the various roles involved in the system and their respective functions. It also describes the format in which rating must be transmitted and stored on the network. There are multiple approaches to design a system, each approach has its advantages and limitations.
+
+Terminology
+===========
+
+1.  **Rating Category**: For example: Agent, Fulfillment, Provider
+
+2.  **Rateable Object**: The runtime object of a Rating Category that can be rated
+
+3.  **Rating Sender**: The actor that rates a Rateable Object
+
+4.  **Rating Receiver**: The actor that receives the rating for a Rateable Object
+
+Problem
+=======
+
+How to ensure that the customers receive quality services rendered from different providers on an open network?
+
+Forces
+======
+
+1.  Same Rateable Objects may exist on more than one BPP under different names
+
+Expected Outcomes after reading this document
+=============================================
+
+After reading this document, the reader should be able to
+
+1.  Understand how ratings work on Open Commerce Networks enabled by beckn protocol
+
+2.  Understand how to connect their platforms to the Rating and Reputation system on open commerce networks. 
+
+Rating using Beckn Protocol
+===========================
+
+In beckn, **rating** is done via the rating action. This action allows any NP to rate a Rateable Object of another NP according to the rating policy of the NP. The rating policy of an NP defines,
+
+1.  What can be rated
+
+2.  How to rate
+
+Communication Protocol for Rating
+---------------------------------
+
+### Rating Policy Handshake
+
+Before a NP rates another NP's service, an agreement must be reached between both NPs regarding the rating policy. The agreement is done via the Rating Policy agreement handshake. The sequence of messages to be exchanged in this handshake is shown below.
+
+1.  The Rating Sender should call the **get_rating_categories** action on the Rating Receiver's protocol API.
+
+2.  The Rating receiver must immediately respond with an ACK. 
+
+3.  The Rating Receiver should then send back a list of Rating Categories by calling the **rating_categories** callback action on the Rating Sender's protocol API. The **rating_categories** message should contain the following information
+
+    1.  Name of the Rateable Category. This name should be the same as the name of the Schema from Core Specification. For example, "Agent", or "Provider"
+
+    2.  The equivalent real-world name of the Schema. For example,
+    `{ "Agent" : "Delivery Rider" }`
+
+    3.  The rating conditions that must be fulfilled before rating that object. Meaning, the message must contain attributes that must be set and what their expected values must be before rating that Object. The attributes must be in the form of a runtime schema path.  For example,
+    `{ "conditions" : [ { "order.id" : "true", "fulfillment.status" : "COMPLETE"}, { x : y}  ] }`
+
+    4.  The rating conditions must be an array where a single element of that array represents all the conditions that must be fulfilled simultaneously. (AND function). 
+
+    5.  The OR conditions are expressed as the separation between individual elements of the array. Example needed. 
+
+    6.  Post-rating effects such as links to feedback forms
+
+        1.  Feedback_form_url
+
+        2.  Callbacks
+
+        3.  ...
+
+    7.  Rating level type 
+
+4.  The Rating sender must respond with an ACK.
+
+The Rating Sender must design their business logic to accept rating from the user only when the Rating Receiver's rating conditions are matched during a transaction.
+
+### Rating Call
+
+Once the rating handshake is complete, the Rating should happen via the following process.
+
+1.  The Rating Sender should call the rating action on the Rating Receiver's API. The rating message should contain the following information as key/value pairs
+
+1.  The name of the Rating Category: "rating_category" : "Agent"
+
+2.  The UUID of the Rateable Object: "id" : "2324-35454-2324"
+
+3.  The rating value: "value" : "4"
+
+4.  Additional data collected via the feedback form (if required)* 
+
+3.  The Rating Receiver must send an ACK
+
+4.  The Rating Receiver must call the on_rating action on the Rating Sender's API. the message must contain any additional information that may be required after the rating is complete. (Requires further elaboration)
+
+
+### Communication Sequence
+
+
+<figure>
+<img align="center" src="https://github.com/beckn/protocol-specifications/blob/draft/docs/images/rating%20handshake.png">
+</figure>
+
+Rating Ledger Architecture
+==========================
+
+The Rating Ledger is a table containing records with the following fields. This table can be implemented on a centralized database or a decentralized database like a blockchain.
+
+|Attribute|Description|Example|
+|---------|-----------|-------|
+|id|Primary key |`<Some UUID>`|
+|rateable_object_id|This is a UUID generated by the BPP that is mapped against a unique ID.||
+|total_rating_value|Total Rating Value|4350|
+|total_rating_count|Total number of ratings|1000|
+
+This table can be accessed by implementing the same rating action on its API. It is capable of receiving bulk rating information and publishing the information for all network participants to view without revealing confidential information regarding a rateable entity.
+
+When a Rating Sender wants to rate a Rateable Object, it must first call the rating action on the Rating Receiver's API.
+
+At the end of a periodic cycle, say at the end of every day, the Rating Sender must send all the ratings done for the day in bulk.
+
+The Rating Ledger should compute the cumulative rating value of the Rateable Object by adding the sent value to the last calculated value and updating the record of that rateable object.
+
+When a Rating Sender wants to verify the rating of a Rateable Entity, it should call the lookup action on the Rating Ledger's API by sending the id of the Rateable Entity. This requires the Rateable Entity's ID and it's average rating to be sent in the catalog during the on_search action.
+
+To verify the rating of a Rateable Object in the catalog, the Rating Sender must calculate the average rating by dividing the total_rating_value with the total_rating_count.
+
+`Average Rating Value = total_rating_value / total_rating_count`
+
+If this value matches the rating value sent in the catalog, then the rating is accurate. A margin of error may be introduced in the Network Rating Policy  specifying the number of significant digits to be used while comparing the average rating with the received rating.
+
+If the rating value does not match or is not within the margin of error, then the Rating Sender should report the error to the Network Facilitator.
diff --git a/docs/proposals/Sample-proposal.md b/docs/proposals/Sample-proposal.md
@@ -0,0 +1,42 @@
+# Enter Proposal Title Here
+
+## Status:
+Proposal
+
+## Affected Protocol Versions (Active release versions ONLY, REQUIRED)
+* 0.9.3
+* 0.9.2
+* ALL
+
+## Authors:
+
+#### John Doe 
+* _Email address_ : [email protected]
+* _Github username_ : [john.doe](https://github.com/john.doe)
+
+#### Jane Doe 
+* _Email address_ : [email protected]
+* _Github username_ : [jane.doe](https://github.com/jane.doe)
+
+# Abstract (150 words max, REQUIRED)
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis a feugiat odio. Pellentesque in vehicula leo. Integer commodo dapibus tortor, sed vehicula enim condimentum ut. Phasellus in ornare nunc. Fusce convallis eros sed neque elementum aliquam. Fusce mauris purus, aliquam in turpis non, egestas eleifend augue. Aliquam sem libero, aliquam sit amet congue sed, faucibus ut arcu. Nam elit felis, vehicula vel ornare et, ultrices id tellus. Phasellus accumsan eleifend ante, ac fringilla erat pharetra tincidunt. Sed pharetra, magna sed feugiat rutrum, orci nulla volutpat mi, non tempor sem ligula tristique dolor. Nullam id justo efficitur, ornare enim id, lobortis sem.
+
+# Heading (REQUIRED)
+
+Pellentesque consequat purus ac urna lobortis condimentum. Nullam dignissim justo id turpis gravida tincidunt. Aenean a malesuada augue, nec consectetur lacus. In dapibus eu lectus eget imperdiet. Aenean ut nisl fermentum, interdum est quis, pharetra tellus. Nullam gravida augue ac diam auctor, laoreet viverra enim interdum. Donec eget leo eu lectus sodales fermentum. Duis quis dui pharetra, viverra justo at, dapibus arcu.
+
+## Subheading
+Fusce in luctus mi. Ut sagittis, lectus at varius sollicitudin, est tellus tincidunt nisi, vel vestibulum nisi libero a enim. Duis leo neque, accumsan sed suscipit sed, tempus sed dolor. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nunc sit amet odio semper leo mollis pretium quis ac ante.
+
+![Sample Image](https://github.com/beckn/protocol-specifications/blob/core-0.9.4-draft/docs/images/sample.png)
+
+
+### Sub-subheading
+Aenean tincidunt sollicitudin sem a sodales. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Maecenas a eros lacus. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Vestibulum nisi sapien, varius ut luctus sit amet, venenatis vitae nisi. Etiam ut magna vitae tortor scelerisque finibus. Duis arcu libero, facilisis non ultrices at, molestie ut ipsum.
+
+
+# References (REQUIRED)
+
+1. [Name of reference 1](https://URL/to/reference)
+2. [Name of reference 2](https://URL/to/reference)
diff --git a/...C-001-Layering-Network-Policy-Draft-01.md → ...N-001-Layering-Network-Policy-Draft-01.md b/...C-001-Layering-Network-Policy-Draft-01.md → ...N-001-Layering-Network-Policy-Draft-01.md
diff --git a/...002-Payments-On-Beckn-Enabled-Networks.md → ...002-Payments-On-Beckn-Enabled-Networks.md b/...002-Payments-On-Beckn-Enabled-Networks.md → ...002-Payments-On-Beckn-Enabled-Networks.md
@@ -133,7 +133,7 @@ Payment Collection by a BAP and settled at the end of the month to a bank accoun
 {
     "collected_by": "bap",
     "uri": "payto://bank/98273982749428?amount=$currency:$value&ifsc=$ifsc&message=hello",
-    "method": "PAYTO",
+    "tl_method": "PAYTO",
     "type": "POST_FULFILLMENT",
     "status": "NOT-PAID",
     "params": {
@@ -155,7 +155,7 @@ Immediate payment on order placement to a UPI Endpoint
 ```
 {
     "uri": "payto://upi/example@upi?amount=$currency:$value&message=hello",
-    "method": "PAYTO",
+    "tl_method": "PAYTO",
     "type": "ON-ORDER",
     "status": "NOT-PAID",
     "params": {
@@ -171,7 +171,7 @@ Transfer to a Payment Gateway Endpoint
 ```
 {
     "uri": "https://pay.example.com?amount=$value&cur=$currency",
-    "method": "PAYTO",
+    "tl_method": "HTTP/POST",
     "type": "ON-ORDER",
     "status": "NOT-PAID",
     "params": {
@@ -181,7 +181,27 @@ Transfer to a Payment Gateway Endpoint
 }
 ```
 
+## Example 4
+Payment Collection by a BAP and settled at the end of the month using UPI before 15th of February 2022
 
+```
+{
+    "collected_by": "bap",
+    "uri": "upi://pay?pa=UPIID@oksbi&amp;pn=NAME&amp;&tr=123456789&amp;cu=INR&amp;am=200",
+    "tl_method": "UPI",
+    "type": "POST_FULFILLMENT",
+    "status": "NOT-PAID",
+    "params": {
+        "value": "200",
+        "currency": "INR"
+    },
+    "time": {
+        "range": {
+            "end": "2022-02-15 00:00:00"
+        }
+    }
+}
+```
 
 
 

diff --git a/...-Beckn-Protocol-Communication-Draft-01.md → ...-Beckn-Protocol-Communication-Draft-01.md b/...-Beckn-Protocol-Communication-Draft-01.md → ...-Beckn-Protocol-Communication-Draft-01.md
diff --git a/...ministration-On-Beckn-Enabled-Networks.md → ...ministration-On-Beckn-Enabled-Networks.md b/...ministration-On-Beckn-Enabled-Networks.md → ...ministration-On-Beckn-Enabled-Networks.md
diff --git a/docs/protocol-drafts/BECKN-RFC-005-Error-Codes-Draft-01.md b/docs/protocol-drafts/BECKN-RFC-005-Error-Codes-Draft-01.md
@@ -0,0 +1,76 @@
+# Error Codes for BPP
+
+## ID: 
+BECKN-RFC-034
+
+## Draft ID
+Draft-01
+
+## Title:
+Error Codes
+
+## Category:
+Network Policy
+
+## Status:
+Protocol Draft
+
+## Published on:
+January 21, 2022
+
+## Expires on:
+January 20, 2023 or Date of publication of next draft which ever is earlier
+
+## License:
+CC-BY-ND
+
+## Authors:
+1. Ravi Prakash : [email protected]
+
+## Reviewers:
+1. Sujith Nair : [email protected]
+2. Pramod Varma : [email protected]
+
+## Introduction
+  This document outlines the error codes which must be returned by a BPP. 
+
+  ## Error Codes
+  |**Code**|**Message**|**Description**|
+  |---|---|---|
+  |30000|Invalid request error|Generic invalid request error|
+  |30001|Provider not found|When BPP is unable to find the provider id sent by the BAP|
+  |30002|Provider location not found|When BPP is unable to find the provider location id sent by the BAP|
+  |30003|Provider category not found|When BPP is unable to find the provider category id sent by the BAP|
+  |30004|Item not found|When BPP is unable to find the item id sent by the BAP|
+  |30005|Category not found|When BPP is unable to find the category id sent by the BAP|
+  |30006|Offer not found|When BPP is unable to find the offer id sent by the BAP|
+  |30007|Add on not found|When the BPP is unable to find the add on id sent by the BAP|
+  |30008|Fulfillment unavailable|When BPP is unable to find the fulfillment id sent by the BAP|
+  |30009|Fulfilment provider unavailable|When the BPP is unable to find fulfilment provider id sent by the BAP|
+  |30010|Order not found|When the BPP is unable to find the order id sent by the BAP|
+  |30011|Invalid cancellation reason|When the BPP is unable to find the cancellation reason in cancellation_reason_id|
+  |30012|Invalid update_target|When the BPP is unable to find the update_target in the order object|
+  |30013|Update inconsistency|When the BPP finds changes in the order object other than the update_target|
+  |30014|Entity to rate not found|When the BPP is unable to find the entity to rate in id|
+  |30015|Invalid rating value|When the BPP receives an invalid value as the rating value in value|
+  |40000|Business Error|Generic business error|
+  |40001|Action not applicable|When an API endpoint is not implemented by the BPP as it is not required for their use cases and a BAP calls one of these endpoints|
+  |40002|Item quantity unavailable|When the BPP is unable to select the specified number in order.items[].quantity|
+  |40003|Quote unavailable|When the quote sent by the BAP is no longer available from the BPP|
+  |40004|Payment not supported|When the payment object sent by the BAP is not supported by the BPP|
+  |40005|Tracking not supported|When the BPP does not support tracking for the order in order_id|
+  |40006|Fulfilment agent unavailable|When an agent for fulfilment is not available|
+  |50000|Policy Error|Generic Policy Error|
+  |50001|Cancellation not possible|When the BPP is unable to cancel the order due to it's cancellation policy|
+  |50002|Updation not possible|When the BPP is unable to update the order due to it's updation policy|
+  |50003|Unsupported rating category|When the BPP receives an entity to rate which is not supported|
+  |50004|Support unavailable|When the BPP receives an object if for which it does not provide support|
+
+  ## Acknowledgements
+  The author would like to thank the following individuals for their contributions in creating the first draft of this document (in alphabetical order):
+
+1. Pramod Varma, Beckn Foundation
+2. Sujith Nair, Beckn Foundation
+3. Supriyo Ghosh, ONDC
+
+*Copyright (c) 2022 Beckn Foundation. All rights reserved.*