diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..6f71afd --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +.DS_Store +node_modules +package-lock.json diff --git a/docs/.gitmodules b/docs/.gitmodules new file mode 100644 index 0000000..8f574f9 --- /dev/null +++ b/docs/.gitmodules @@ -0,0 +1,8 @@ +[submodule "mobility-core"] + path = mobility-core + url = https://github.com/beckn/mobility.git + branch = main +[submodule "beckn-core"] + path = beckn-core + url = https://github.com/beckn/protocol-specifications.git + branch = master diff --git a/docs/Committee.md b/docs/Committee.md new file mode 100644 index 0000000..b5a97b1 --- /dev/null +++ b/docs/Committee.md @@ -0,0 +1,9 @@ +# ONDC Mobility Committee + +* [Sujith Nair](#TODO) +* [Ravi Prakash](#TODO) +* [Abhishek Singh](#TODO) +* [Neeraj Jain](#TODO) +* [Nitin Nair](#TODO) +* [Shreyansh Shah](#TODO) +* [Rupal Singla](#TODO) diff --git a/docs/Error-codes.xlsx b/docs/Error-codes.xlsx new file mode 100644 index 0000000..8976021 Binary files /dev/null and b/docs/Error-codes.xlsx differ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b106ff0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,72 @@ +# ONDC Mobility Specification + +These specifications are to enable ONDC Network Participants to expose or consume mobility services on ONDC. + +ONDC mobility specification is an adaptation of [beckn mobility specifications](https://github.com/beckn/mobility). + +These specifications will be released in multiple phases enabling different use case and enhancements. + +ONDC mobility specification swagger [link](https://ondc-official.github.io/mobility-specification/) + +## Latest Version + +[v2.0.0](https://github.com/ONDC-Official/mobility-specification/releases/tag/v1.0.0) + +## Earlier Versions + +| Version | Release Date | beckn Version | Comments | +| ------- | ------------ | ---------------------------------- | ------------------------------------------------------------------ | +| v1.0.0 | 14 Jun 2023 | core - 0.9.4
mobility - 0.8.2 | Initial mobility specification for on-demand ride hailing use case | +| v2.0.0 | 19 Feb 2024 | core - 1.2.0 | Base version of mobility for ride hailing is completed | + +## Introduction + +Open Network for Digital Commerce (ONDC) is a network based on beckn open protocol and will enable local commerce across segments, such as mobility, retail etc, to be discovered and engaged by any network-enabled application. + +ONDC mobility & travel aims to build a nationwide multi-modal network that provides seamless experiences, supports growth & innovation by, + +* bringing together a diverse set of mobility, travel & transportation players who can engage with the open network on their own terms +* fostering collaboration, sharing & new models +* facilitating responsive policy by bringing onboard decision making authorities + +In the mobility space, the intent is to enable seamless and truly multimodal transit options by bringing in diverse inventory onboard at scale that will serve the country’s population. + +This would be possible in the mobility domain by making sure all mobility apps in the network are built in such a way as to enable them to communicate with each other in the same language. + +## Enabled/Supported use cases on network + +* On-demand Ride hailing with fix pick-up and drop locations for transport modes : Car, Autorickshaw, Motorcycle +* Auto assignment of driver on on_confirm. +* Auto assignment of driver post on_confirm. +* Soft/Hard cancellation of ride. + +## Evolution + +The evolution of ONDC mobility specification driven by 2 factors: + +1. The beckn mobility and/or core specification evolution. +2. ONDC Network Participants recommendation and requirement for enhancing and expanding the network use cases & experience. + +To know more about how the specification evolves, visit the Network GOVERNANCE document. + +To follow discussions related to the mobility specification please visit the [Discussions Forum](https://github.com/ONDC-Official/mobility-specification/discussions) on GitHub + +Each major release of ONDC mobility specification will be approved by ONDC mobility working group members for which are listed [here](./Committee.md) + +For minor releases for bug fix and cosmetic changes ONDC would make a minor release based on internal approval process and update the committee in the next scheduled discussion. + +## Contribution + +### Contribution to specifications + +Anyone can contribute to the specification. Please refer beckn contribution guidelines. + +### Contribution to network + +Anyone can contribute to the network enhancements. Contributors must follow the contribution guidelines. + +Each contribution will be peer-reviewed by the ONDC mobility committee members. If approved, this contribution will be merged with the applicable versions of the specification. + +#### What is Contribution to network + +Addition/Modification of examples, enum, policies which are very specific to the networks scope and purview. diff --git a/docs/Usage.md b/docs/Usage.md new file mode 100644 index 0000000..a46b8b6 --- /dev/null +++ b/docs/Usage.md @@ -0,0 +1,79 @@ +# API Contract + +The API Contract document is part of the repository as a static index.html. Once the repo is checked out any user can go ahead and open this index.html into their repo and visualise the information of the repo in a Visual API contract format. Alternate to this user can also look into github pages here to visualise the current master specification. + +# Repository Structure + +**Note:** All folders mentioned here are relative to the root folder `protocol-specs` + +The full specification can be found at `api/build/build.yaml` + +This is an autogenerated file created by compiling multiple sets of components namely, + +1. Enum: found at `api/components/enum/` + * These are all the enums used in specification while creating the artifact +2. Tags: found at `api/components/tags/` + * These are all the tags/taggroups used in specification while creating the artifact +3. Examples: found at `api/components/examples/` + * These are the examples created Illustrative use of the specification and embeeded in the yaml + * Structure `api/components/examples/{module/feature/use case}/{API_Folder}/example_{#}.yaml` +4. Unresolved YAML: found at `api/components/beck_yaml.yaml` + +## Diagaram + +``` + +/ (root directory) +| +|--beckn-core (git submodule to specific beckn inheritated release) +|--api (contains all the api specific details) +| |--build +| | |--build.yaml (Built Single YAML with api specification) +| |--components (contains all components of the specification) +| | |--enum (contains all enums used in module) +| | | |--index.yaml (index yaml) +| | | |--{schema}.yaml (dictionary yaml) +| | |--examples (conatins examples of the APIs) +| | | |--(theme/usecase/base/behaviour) +| | | | |--search (search request examples yaml) +| | | | | |--example_0.yaml (example_0 yaml) +| | |--tags (contains Tags all tags used in module) +| | | |--tag-group.yaml (Tag Group Yaml) +| | | |--tag.yaml (tag yaml) +| | | |--index.yaml (tag index yaml) +| | |--flows (contains illustrative flows module) +| | | |--(theme/usecase/base/behaviour) +| | | | |--index.yaml (specific flow yaml) +| | | |--index.yaml (flows index yaml) +| | |--beck_yaml.yaml (unresolved yaml to build final yaml) +| | |--docs (documents associated with specification) +| | | |--attribute.md (Attribute to business terminology mapping)description) +``` + +# Setup steps + +## Pre-requisite + +### Install swagger CLI + +- Install the swagger command line tool using ``npm`` (Note: you may need to use root privileges if installing it globally) + +``` +sudo npm install -g swagger-cli +``` + +## Generate the resolved OpenAPI illustration viewer file + +- Run the following command + +``` +cd ./api/components +node app +``` + +- If the command runs successfully, you should see an output like this, + +``` +Created temp.yaml from ./beckn_yaml.yaml +Temporary file deleted +``` diff --git a/docs/api/build/build.yaml b/docs/api/build/build.yaml new file mode 100644 index 0000000..d11ee91 --- /dev/null +++ b/docs/api/build/build.yaml @@ -0,0 +1,14286 @@ +openapi: 3.0.0 +info: + title: ONDC Specification + description: ONDC Specification + version: 2.0.0 +security: + - SubscriberAuth: [] +paths: + /search: + post: + tags: + - Provider Platform + - Gateway + description: >- + Consumer Platform declares the customer's intent to buy/avail products + or services + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - properties: + action: + enum: + - search + message: + type: object + additionalProperties: false + properties: + intent: + $ref: '#/components/schemas/Intent' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /select: + post: + tags: + - Provider Platform + description: >- + Consumer Platform declares the customer's cart (or equivalent) created + by selecting objects from the catalog + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - select + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /init: + post: + tags: + - Provider Platform + description: Initialize an order by providing billing and/or shipping details + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - init + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + default: + description: >- + Acknowledgement of message received after successful validation of + schema and signature + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + allOf: + - $ref: '#/components/schemas/Ack' + - type: object + - properties: + status: + enum: + - ACK + - NACK + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /confirm: + post: + tags: + - Provider Platform + description: Initialize an order by providing billing and/or shipping details + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - confirm + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /status: + post: + tags: + - Provider Platform + description: Fetch the latest order object + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - status + required: + - action + message: + type: object + additionalProperties: false + properties: + ref_id: + $ref: '#/components/schemas/Order/properties/id' + order_id: + $ref: '#/components/schemas/Order/properties/id' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /track: + post: + tags: + - Provider Platform + description: Track an active order + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - track + required: + - action + message: + type: object + additionalProperties: false + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + callback_url: + type: string + format: uri + required: + - order_id + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /cancel: + post: + tags: + - Provider Platform + description: Cancel an order + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - cancel + required: + - action + message: + type: object + additionalProperties: false + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + cancellation_reason_id: + $ref: '#/components/schemas/Option/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + required: + - order_id + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /update: + post: + tags: + - Provider Platform + description: Remove object + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - update + required: + - action + message: + type: object + additionalProperties: false + properties: + update_target: + description: >- + Comma separated values of order objects being updated. + For example: + ```"update_target":"item,billing,fulfillment"``` + type: string + order: + description: Updated order object + allOf: + - $ref: '#/components/schemas/Order' + required: + - update_target + - order + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /rating: + post: + tags: + - Provider Platform + description: Provide feedback on a service + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - rating + required: + - action + message: + type: object + properties: + ratings: + type: array + items: + $ref: '#/components/schemas/Rating' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /support: + post: + tags: + - Provider Platform + description: Contact support + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - support + required: + - action + message: + type: object + properties: + support: + $ref: '#/components/schemas/Support' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_search: + post: + tags: + - Consumer Platform + description: Provider Platform sends its catalog in response to a search request. + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_search + required: + - action + message: + type: object + additionalProperties: false + properties: + catalog: + $ref: '#/components/schemas/Catalog' + required: + - catalog + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_select: + post: + tags: + - Consumer Platform + description: Send draft order object with quoted price for selected items + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_select + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_init: + post: + tags: + - Consumer Platform + description: Send order object with payment details updated + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_init + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_confirm: + post: + tags: + - Consumer Platform + description: Send active order object + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_confirm + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_track: + post: + tags: + - Consumer Platform + description: Send tracking details of an active order + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_track + required: + - action + message: + type: object + additionalProperties: false + properties: + tracking: + $ref: '#/components/schemas/Tracking' + required: + - tracking + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_cancel: + post: + tags: + - Consumer Platform + description: >- + Send cancellation request_id with reasons list in case of cancellation + request. Else send cancelled order object + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_cancel + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_update: + post: + tags: + - Consumer Platform + description: Returns updated service with updated runtime object + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_update + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_status: + post: + tags: + - Consumer Platform + description: Fetch the status of a Service + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_status + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_rating: + post: + tags: + - Consumer Platform + description: Provide feedback on a service + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_rating + required: + - action + message: + type: object + properties: + feedback_form: + description: >- + A feedback form to allow the user to provide additional + information on the rating provided + allOf: + - $ref: '#/components/schemas/XInput' + error: + $ref: '#/components/schemas/Error' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_support: + post: + tags: + - Consumer Platform + description: Contact Support + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_support + required: + - action + message: + type: object + properties: + support: + $ref: '#/components/schemas/Support' + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: >- + Signature of message body using Consumer Platform or Provider Platform + subscriber's signing public key. +

Format:

Authorization : Signature + keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) + (expires) digest",signature="Base64(signing string)" + schemas: + Ack: + description: >- + Describes the acknowledgement sent in response to an API call. If the + implementation uses HTTP/S, then Ack must be returned in the same + session. Every API call to a BPP must be responded to with an Ack + whether the BPP intends to respond with a callback or not. This has one + property called `status` that indicates the status of the + Acknowledgement. + type: object + additionalProperties: false + properties: + status: + type: string + description: >- + The status of the acknowledgement. If the request passes the + validation criteria of the BPP, then this is set to ACK. If a BPP + responds with status = `ACK` to a request, it is required to respond + with a callback. If the request fails the validation criteria, then + this is set to NACK. Additionally, if a BPP does not intend to + respond with a callback even after the request meets the validation + criteria, it should set this value to `NACK`. + enum: + - ACK + - NACK + tags: + description: >- + A list of tags containing any additional information sent along with + the Acknowledgement. + type: array + items: + $ref: '#/components/schemas/TagGroup' + AddOn: + description: >- + Describes an additional item offered as a value-addition to a product or + service. This does not exist independently in a catalog and is always + associated with an item. + type: object + additionalProperties: false + properties: + id: + description: Provider-defined ID of the add-on + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + price: + $ref: '#/components/schemas/Price' + quantity: + $ref: '#/components/schemas/ItemQuantity' + Address: + description: Describes a postal address. + type: string + Agent: + description: >- + Describes the direct performer, driver or executor that fulfills an + order. It is usually a person. But in some rare cases, it could be a + non-living entity like a drone, or a bot. Some examples of agents are + Doctor in the healthcare sector, a driver in the mobility sector, or a + delivery person in the logistics sector. This object can be set at any + stage of the order lifecycle. This can be set at the discovery stage + when the BPP wants to provide details on the agent fulfilling the order, + like in healthcare, where the doctor's name appears during search. This + object can also used to search for a particular person that the customer + wants fulfilling an order. Sometimes, this object gets instantiated + after the order is confirmed, like in the case of on-demand taxis, where + the driver is assigned after the user confirms the ride. + type: object + additionalProperties: false + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + organization: + $ref: '#/components/schemas/Organization' + rating: + $ref: '#/components/schemas/Rating/properties/value' + Authorization: + description: >- + Describes an authorization mechanism used to start or end the + fulfillment of an order. For example, in the mobility sector, the driver + may require a one-time password to initiate the ride. In the healthcare + sector, a patient may need to provide a password to open a video + conference link during a teleconsultation. + type: object + additionalProperties: false + properties: + type: + description: >- + Type of authorization mechanism used. The allowed values for this + field can be published as part of the network policy. + type: string + token: + description: >- + Token used for authorization. This is typically generated at the + BPP. The BAP can send this value to the user via any channel that it + uses to authenticate the user like SMS, Email, Push notification, or + in-app rendering. + type: string + valid_from: + description: Timestamp in RFC3339 format from which token is valid + type: string + format: date-time + valid_to: + description: Timestamp in RFC3339 format until which token is valid + type: string + format: date-time + status: + description: Status of the token + type: string + Billing: + description: >- + Describes the billing details of an entity.
This has properties like + name,organization,address,email,phone,time,tax_number, + created_at,updated_at + type: object + additionalProperties: false + properties: + name: + description: Name of the billable entity + type: string + organization: + description: Details of the organization being billed. + allOf: + - $ref: '#/components/schemas/Organization' + address: + description: The address of the billable entity + allOf: + - $ref: '#/components/schemas/Address' + state: + description: >- + The state where the billable entity resides. This is important for + state-level tax calculation + allOf: + - $ref: '#/components/schemas/State' + city: + description: The city where the billable entity resides. + allOf: + - $ref: '#/components/schemas/City' + email: + description: Email address where the bill is sent to + type: string + format: email + phone: + description: Phone number of the billable entity + type: string + time: + description: Details regarding the billing period + allOf: + - $ref: '#/components/schemas/Time' + tax_id: + description: ID of the billable entity as recognized by the taxation authority + type: string + Cancellation: + description: Describes a cancellation event + type: object + additionalProperties: false + properties: + time: + description: Date-time when the order was cancelled by the buyer + type: string + format: date-time + cancelled_by: + type: string + enum: + - CONSUMER + - PROVIDER + reason: + description: The reason for cancellation + allOf: + - $ref: '#/components/schemas/Option' + additional_description: + description: Any additional information regarding the nature of cancellation + allOf: + - $ref: '#/components/schemas/Descriptor' + CancellationTerm: + description: >- + Describes the cancellation terms of an item or an order. This can be + referenced at an item or order level. Item-level cancellation terms can + override the terms at the order level. + type: object + additionalProperties: false + properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: '#/components/schemas/FulfillmentState' + reason_required: + description: Indicates whether a reason is required to cancel the order + type: boolean + cancel_by: + description: Information related to the time of cancellation. + allOf: + - $ref: '#/components/schemas/Time' + cancellation_fee: + $ref: '#/components/schemas/Fee' + xinput: + $ref: '#/components/schemas/XInput' + external_ref: + $ref: '#/components/schemas/MediaFile' + Catalog: + description: >- + Describes the products or services offered by a BPP. This is typically + sent as the response to a search intent from a BAP. The payment terms, + offers and terms of fulfillment supported by the BPP can also be + included here. The BPP can show hierarchical nature of products/services + in its catalog using the parent_category_id in categories. The BPP can + also send a ttl (time to live) in the context which is the duration for + which a BAP can cache the catalog and use the cached catalog.
This + has properties like + bbp/descriptor,bbp/categories,bbp/fulfillments,bbp/payments,bbp/offers,bbp/providers + and exp
This is used in the following situations.
+ type: object + additionalProperties: false + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + fulfillments: + description: >- + Fulfillment modes offered at the BPP level. This is used when a BPP + itself offers fulfillments on behalf of the providers it has + onboarded. + type: array + items: + $ref: '#/components/schemas/Fulfillment' + payments: + description: >- + Payment terms offered by the BPP for all transactions. This can be + overriden at the provider level. + type: array + items: + $ref: '#/components/schemas/Payment' + offers: + description: >- + Offers at the BPP-level. This is common across all providers + onboarded by the BPP. + type: array + items: + $ref: '#/components/schemas/Offer' + providers: + type: array + items: + $ref: '#/components/schemas/Provider' + exp: + description: Timestamp after which catalog will expire + type: string + format: date-time + ttl: + description: Duration in seconds after which this catalog will expire + type: string + Category: + description: A label under which a collection of items can be grouped. + type: object + additionalProperties: false + properties: + id: + description: ID of the category + type: string + parent_category_id: + $ref: '#/components/schemas/Category/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + time: + $ref: '#/components/schemas/Time' + ttl: + description: Time to live for an instance of this schema + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Circle: + description: >- + Describes a circular region of a specified radius centered at a + specified GPS coordinate. + type: object + additionalProperties: false + properties: + gps: + $ref: '#/components/schemas/Gps' + radius: + $ref: '#/components/schemas/Scalar' + City: + description: Describes a city + type: object + additionalProperties: false + properties: + name: + description: Name of the city + type: string + code: + description: City code + type: string + Contact: + description: Describes the contact information of an entity + type: object + additionalProperties: false + properties: + phone: + type: string + email: + type: string + jcard: + type: object + additionalProperties: false + description: A Jcard object as per draft-ietf-jcardcal-jcard-03 specification + Context: + description: >- + Every API call in beckn protocol has a context. It provides a high-level + overview to the receiver about the nature of the intended transaction. + Typically, it is the BAP that sets the transaction context based on the + consumer's location and action on their UI. But sometimes, during + unsolicited callbacks, the BPP also sets the transaction context but it + is usually the same as the context of a previous full-cycle, + request-callback interaction between the BAP and the BPP. The context + object contains four types of fields.
  1. Demographic information + about the transaction using fields like `domain`, `country`, and + `region`.
  2. Addressing details like the sending and receiving + platform's ID and API URL.
  3. Interoperability information like the + protocol version that implemented by the sender and,
  4. Transaction + details like the method being called at the receiver's endpoint, the + transaction_id that represents an end-to-end user session at the BAP, a + message ID to pair requests with callbacks, a timestamp to capture + sending times, a ttl to specifiy the validity of the request, and a key + to encrypt information if necessary.
This object must be + passed in every interaction between a BAP and a BPP. In HTTP/S + implementations, it is not necessary to send the context during the + synchronous response. However, in asynchronous protocols, the context + must be sent during all interactions, + type: object + additionalProperties: false + properties: + domain: + description: Domain code that is relevant to this transaction context + allOf: + - $ref: '#/components/schemas/Domain/properties/code' + type: string + location: + description: The location where the transaction is intended to be fulfilled. + allOf: + - $ref: '#/components/schemas/Location' + action: + description: >- + The Beckn protocol method being called by the sender and executed at + the receiver. + type: string + version: + type: string + description: Version of transaction protocol being used by the sender. + bap_id: + description: Subscriber ID of the BAP + allOf: + - description: >- + A globally unique identifier of the platform, Typically it is + the fully qualified domain name (FQDN) of the platform. + type: string + bap_uri: + description: Subscriber URL of the BAP for accepting callbacks from BPPs. + allOf: + - description: >- + The callback URL of the Subscriber. This should necessarily + contain the same domain name as set in `subscriber_id``. + type: string + format: uri + bpp_id: + description: Subscriber ID of the BPP + allOf: + - $ref: '#/components/schemas/Context/properties/bap_id/allOf/0' + bpp_uri: + description: Subscriber URL of the BPP for accepting calls from BAPs. + allOf: + - $ref: '#/components/schemas/Context/properties/bap_uri/allOf/0' + transaction_id: + description: >- + This is a unique value which persists across all API calls from + `search` through `confirm`. This is done to indicate an active user + session across multiple requests. The BPPs can use this value to + push personalized recommendations, and dynamic offerings related to + an ongoing transaction despite being unaware of the user active on + the BAP. + type: string + format: uuid + message_id: + description: >- + This is a unique value which persists during a request / callback + cycle. Since beckn protocol APIs are asynchronous, BAPs need a + common value to match an incoming callback from a BPP to an earlier + call. This value can also be used to ignore duplicate messages + coming from the BPP. It is recommended to generate a fresh + message_id for every new interaction. When sending unsolicited + callbacks, BPPs must generate a new message_id. + type: string + format: uuid + timestamp: + description: Time of request generation in RFC3339 format + type: string + format: date-time + key: + description: The encryption public key of the sender + type: string + ttl: + description: >- + The duration in ISO8601 format after timestamp for which this + message holds valid + type: string + Country: + description: Describes a country + type: object + additionalProperties: false + properties: + name: + type: string + description: Name of the country + code: + type: string + description: Country code as per ISO 3166-1 and ISO 3166-2 format + Credential: + description: Describes a credential of an entity - Person or Organization + type: object + additionalProperties: false + properties: + id: + type: string + type: + type: string + default: VerifiableCredential + url: + description: URL of the credential + type: string + format: uri + Customer: + description: Describes a customer buying/availing a product or a service + type: object + additionalProperties: false + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + DecimalValue: + description: Describes a numerical value in decimal form + type: string + pattern: '[+-]?([0-9]*[.])?[0-9]+' + Descriptor: + description: Physical description of something. + type: object + additionalProperties: false + properties: + name: + type: string + code: + type: string + short_desc: + type: string + long_desc: + type: string + additional_desc: + type: object + additionalProperties: false + properties: + url: + type: string + content_type: + type: string + enum: + - text/plain + - text/html + - application/json + media: + type: array + items: + $ref: '#/components/schemas/MediaFile' + images: + type: array + items: + $ref: '#/components/schemas/Image' + Domain: + description: >- + Described the industry sector or sub-sector. The network policy should + contain codes for all the industry sectors supported by the network. + Domains can be created in varying levels of granularity. The granularity + of a domain can be decided by the participants of the network. Too broad + domains will result in irrelevant search broadcast calls to BPPs that + don't have services supporting the domain. Too narrow domains will + result in a large number of registry entries for each BPP. It is + recommended that network facilitators actively collaborate with various + working groups and network participants to carefully choose domain codes + keeping in mind relevance, performance, and opportunity cost. It is + recommended that networks choose broad domains like mobility, logistics, + healthcare etc, and progressively granularize them as and when the + number of network participants for each domain grows large. + type: object + additionalProperties: false + properties: + name: + description: Name of the domain + type: string + code: + description: >- + Standard code representing the domain. The standard is usually + published as part of the network policy. Furthermore, the network + facilitator should also provide a mechanism to provide the supported + domains of a network. + additional_info: + description: A url that contains addtional information about that domain. + allOf: + - $ref: '#/components/schemas/MediaFile' + Duration: + description: Describes duration as per ISO8601 format + type: string + Error: + description: >- + Describes an error object that is returned by a BAP, BPP or BG as a + response or callback to an action by another network participant. This + object is sent when any request received by a network participant is + unacceptable. This object can be sent either during Ack or with the + callback. + type: object + additionalProperties: false + properties: + code: + type: string + description: >- + Standard error code. For full list of error codes, refer to + docs/protocol-drafts/BECKN-005-ERROR-CODES-DRAFT-01.md of this repo" + paths: + type: string + description: >- + Path to json schema generating the error. Used only during json + schema validation errors + message: + type: string + description: >- + Human readable message describing the error. Used mainly for + logging. Not recommended to be shown to the user. + Fee: + description: A fee applied on a particular entity + type: object + additionalProperties: false + properties: + percentage: + description: Percentage of a value + allOf: + - $ref: '#/components/schemas/DecimalValue' + amount: + description: A fixed value + allOf: + - $ref: '#/components/schemas/Price' + Form: + description: Describes a form + type: object + additionalProperties: false + properties: + id: + description: The form identifier. + type: string + url: + description: >- + The URL from where the form can be fetched. The content fetched from + the url must be processed as per the mime_type specified in this + object. Once fetched, the rendering platform can choosed to render + the form as-is as an embeddable element; or process it further to + blend with the theme of the application. In case the interface is + non-visual, the the render can process the form data and reproduce + it as per the standard specified in the form. + type: string + format: uri + data: + description: The form submission data + type: object + additionalProperties: + type: string + mime_type: + description: >- + This field indicates the nature and format of the form received by + querying the url. MIME types are defined and standardized in IETF's + RFC 6838. + type: string + enum: + - text/html + - application/html + - application/xml + resubmit: + type: boolean + multiple_sumbissions: + type: boolean + Fulfillment: + description: Describes how a an order will be rendered/fulfilled to the end-customer + type: object + additionalProperties: false + properties: + id: + description: Unique reference ID to the fulfillment of an order + type: string + type: + description: >- + A code that describes the mode of fulfillment. This is typically set + when there are multiple ways an order can be fulfilled. For example, + a retail order can be fulfilled either via store pickup or a home + delivery. Similarly, a medical consultation can be provided either + in-person or via tele-consultation. The network policy must publish + standard fulfillment type codes for the different modes of + fulfillment. + type: string + rateable: + description: Whether the fulfillment can be rated or not + type: boolean + rating: + description: The rating value of the fulfullment service. + allOf: + - $ref: '#/components/schemas/Rating/properties/value' + state: + description: >- + The current state of fulfillment. The BPP must set this value + whenever the state of the order fulfillment changes and fire an + unsolicited `on_status` call. + allOf: + - $ref: '#/components/schemas/FulfillmentState' + tracking: + type: boolean + description: Indicates whether the fulfillment allows tracking + default: false + customer: + description: The person that will ultimately receive the order + allOf: + - $ref: '#/components/schemas/Customer' + agent: + description: The agent that is currently handling the fulfillment of the order + allOf: + - $ref: '#/components/schemas/Agent' + contact: + $ref: '#/components/schemas/Contact' + vehicle: + $ref: '#/components/schemas/Vehicle' + stops: + description: >- + The list of logical stops encountered during the fulfillment of an + order. + type: array + items: + $ref: '#/components/schemas/Stop' + path: + description: >- + The physical path taken by the agent that can be rendered on a map. + The allowed format of this property can be set by the network. + type: string + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + FulfillmentState: + description: Describes the state of fulfillment + type: object + additionalProperties: false + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + updated_at: + type: string + format: date-time + updated_by: + type: string + description: ID of entity which changed the state + Gps: + description: Describes a GPS coordinate + type: string + pattern: >- + ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ + Image: + description: Describes an image + type: object + additionalProperties: false + properties: + url: + description: URL to the image. This can be a data url or an remote url + type: string + format: uri + size_type: + description: >- + The size of the image. The network policy can define the default + dimensions of each type + type: string + enum: + - xs + - sm + - md + - lg + - xl + - custom + width: + description: Width of the image in pixels + type: string + height: + description: Height of the image in pixels + type: string + Intent: + description: >- + The intent to buy or avail a product or a service. The BAP can declare + the intent of the consumer containing
This has properties like + descriptor,provider,fulfillment,payment,category,offer,item,tags
This + is typically used by the BAP to send the purpose of the user's search to + the BPP. This will be used by the BPP to find products or services it + offers that may match the user's intent.
For example, in Mobility, + the mobility consumer declares a mobility intent. In this case, the + mobility consumer declares information that describes various aspects of + their journey like,
For example, in health domain, a + consumer declares the intent for a lab booking the describes various + aspects of their booking like, + type: object + additionalProperties: false + properties: + descriptor: + description: >- + A raw description of the search intent. Free text search strings, + raw audio, etc can be sent in this object. + allOf: + - $ref: '#/components/schemas/Descriptor' + provider: + description: >- + The provider from which the customer wants to place to the order + from + allOf: + - $ref: '#/components/schemas/Provider' + fulfillment: + description: Details on how the customer wants their order fulfilled + allOf: + - $ref: '#/components/schemas/Fulfillment' + payment: + description: Details on how the customer wants to pay for the order + allOf: + - $ref: '#/components/schemas/Payment' + category: + description: Details on the item category + allOf: + - $ref: '#/components/schemas/Category' + offer: + description: details on the offer the customer wants to avail + allOf: + - $ref: '#/components/schemas/Offer' + item: + description: Details of the item that the consumer wants to order + allOf: + - $ref: '#/components/schemas/Item' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + ItemQuantity: + description: Describes the count or amount of an item + type: object + additionalProperties: false + properties: + allocated: + description: >- + This represents the exact quantity allocated for purchase of the + item. + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + available: + description: >- + This represents the exact quantity available for purchase of the + item. The buyer can only purchase multiples of this + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + maximum: + description: >- + This represents the maximum quantity allowed for purchase of the + item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 1 + measure: + $ref: '#/components/schemas/Scalar' + minimum: + description: >- + This represents the minimum quantity allowed for purchase of the + item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + selected: + description: This represents the quantity selected for purchase of the item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + unitized: + description: This represents the quantity available in a single unit of the item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 1 + maximum: 1 + measure: + $ref: '#/components/schemas/Scalar' + Item: + description: >- + Describes a product or a service offered to the end consumer by the + provider. In the mobility sector, it can represent a fare product like + one way journey. In the logistics sector, it can represent the delivery + service offering. In the retail domain it can represent a product like a + grocery item. + type: object + additionalProperties: false + properties: + id: + description: ID of the item. + type: string + parent_item_id: + description: ID of the item, this item is a variant of + allOf: + - $ref: '#/components/schemas/Item/properties/id' + parent_item_quantity: + description: The number of units of the parent item this item is a multiple of + allOf: + - $ref: '#/components/schemas/ItemQuantity' + descriptor: + description: Physical description of the item + allOf: + - $ref: '#/components/schemas/Descriptor' + creator: + description: The creator of this item + allOf: + - $ref: '#/components/schemas/Organization' + price: + description: The price of this item, if it has intrinsic value + allOf: + - $ref: '#/components/schemas/Price' + quantity: + description: The selling quantity of the item + allOf: + - $ref: '#/components/schemas/ItemQuantity' + category_ids: + description: Categories this item can be listed under + type: array + items: + allOf: + - $ref: '#/components/schemas/Category/properties/id' + fulfillment_ids: + description: Modes through which this item can be fulfilled + type: array + items: + allOf: + - $ref: '#/components/schemas/Fulfillment/properties/id' + location_ids: + description: Provider Locations this item is available in + type: array + items: + allOf: + - $ref: '#/components/schemas/Location/properties/id' + payment_ids: + description: Payment modalities through which this item can be ordered + type: array + items: + allOf: + - $ref: '#/components/schemas/Payment/properties/id' + add_ons: + type: array + items: + $ref: '#/components/schemas/AddOn' + cancellation_terms: + description: Cancellation terms of this item + type: array + items: + $ref: '#/components/schemas/CancellationTerm' + refund_terms: + description: Refund terms of this item + type: array + items: + description: Refund term of an item or an order + type: object + additionalProperties: false + properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: '#/components/schemas/State' + refund_eligible: + description: Indicates if cancellation will result in a refund + type: boolean + refund_within: + description: >- + Time within which refund will be processed after successful + cancellation. + allOf: + - $ref: '#/components/schemas/Time' + refund_amount: + $ref: '#/components/schemas/Price' + replacement_terms: + description: Terms that are applicable be met when this item is replaced + type: array + items: + $ref: '#/components/schemas/ReplacementTerm' + return_terms: + description: Terms that are applicable when this item is returned + type: array + items: + $ref: '#/components/schemas/ReturnTerm' + xinput: + description: >- + Additional input required from the customer to purchase / avail this + item + allOf: + - $ref: '#/components/schemas/XInput' + time: + description: >- + Temporal attributes of this item. This property is used when the + item exists on the catalog only for a limited period of time. + allOf: + - $ref: '#/components/schemas/Time' + rateable: + description: Whether this item can be rated + type: boolean + rating: + description: The rating of the item + allOf: + - $ref: '#/components/schemas/Rating/properties/value' + matched: + description: Whether this item is an exact match of the request + type: boolean + related: + description: Whether this item is a related item to the exactly matched item + type: boolean + recommended: + description: Whether this item is a recommended item to a response + type: boolean + ttl: + description: Time to live in seconds for an instance of this schema + type: string + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Location: + description: The physical location of something + type: object + additionalProperties: false + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + map_url: + description: >- + The url to the map of the location. This can be a globally + recognized map url or the one specified by the network policy. + type: string + format: uri + gps: + description: The GPS co-ordinates of this location. + allOf: + - $ref: '#/components/schemas/Gps' + updated_at: + type: string + format: date-time + address: + description: The address of this location. + allOf: + - $ref: '#/components/schemas/Address' + city: + description: The city this location is, or is located within + allOf: + - $ref: '#/components/schemas/City' + district: + description: The state this location is, or is located within + type: string + state: + description: The state this location is, or is located within + allOf: + - $ref: '#/components/schemas/State' + country: + description: The country this location is, or is located within + allOf: + - $ref: '#/components/schemas/Country' + area_code: + type: string + circle: + $ref: '#/components/schemas/Circle' + polygon: + description: The boundary polygon of this location + type: string + 3dspace: + description: The three dimensional region describing this location + type: string + rating: + description: The rating of this location + allOf: + - $ref: '#/components/schemas/Rating/properties/value' + MediaFile: + description: This object contains a url to a media file. + type: object + additionalProperties: false + properties: + mimetype: + description: >- + indicates the nature and format of the document, file, or assortment + of bytes. MIME types are defined and standardized in IETF's RFC 6838 + type: string + url: + description: The URL of the file + type: string + format: uri + signature: + description: The digital signature of the file signed by the sender + type: string + dsa: + description: The signing algorithm used by the sender + type: string + Offer: + description: >- + An offer associated with a catalog. This is typically used to promote a + particular product and enable more purchases. + type: object + additionalProperties: false + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + location_ids: + type: array + items: + $ref: '#/components/schemas/Location/properties/id' + category_ids: + type: array + items: + $ref: '#/components/schemas/Category/properties/id' + item_ids: + type: array + items: + $ref: '#/components/schemas/Item/properties/id' + time: + $ref: '#/components/schemas/Time' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Option: + description: Describes a selectable option + type: object + additionalProperties: false + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + Order: + description: >- + Describes a legal purchase order. It contains the complete details of + the legal contract created between the buyer and the seller. + type: object + additionalProperties: false + properties: + id: + type: string + description: >- + Human-readable ID of the order. This is generated at the BPP layer. + The BPP can either generate order id within its system or forward + the order ID created at the provider level. + ref_order_ids: + description: A list of order IDs to link this order to previous orders. + type: array + items: + type: string + description: ID of a previous order + status: + description: >- + Status of the order. Allowed values can be defined by the network + policy + type: string + type: + description: >- + This is used to indicate the type of order being created to BPPs. + Sometimes orders can be linked to previous orders, like a + replacement order in a retail domain. A follow-up consultation in + healthcare domain. A single order part of a subscription order. The + list of order types can be standardized at the network level. + type: string + default: DEFAULT + enum: + - DRAFT + - DEFAULT + provider: + description: Details of the provider whose catalog items have been selected. + allOf: + - $ref: '#/components/schemas/Provider' + items: + description: The items purchased / availed in this order + type: array + items: + $ref: '#/components/schemas/Item' + add_ons: + description: The add-ons purchased / availed in this order + type: array + items: + $ref: '#/components/schemas/AddOn' + offers: + description: The offers applied in this order + type: array + items: + $ref: '#/components/schemas/Offer' + billing: + description: The billing details of this order + allOf: + - $ref: '#/components/schemas/Billing' + fulfillments: + description: The fulfillments involved in completing this order + type: array + items: + $ref: '#/components/schemas/Fulfillment' + cancellation: + description: The cancellation details of this order + allOf: + - $ref: '#/components/schemas/Cancellation' + cancellation_terms: + description: Cancellation terms of this item + type: array + items: + $ref: '#/components/schemas/CancellationTerm' + documents: + type: array + items: + description: Documnents associated to the order + type: object + additionalProperties: false + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + mime_type: + description: >- + This field indicates the nature and format of the form + received by querying the url. MIME types are defined and + standardized in IETF's RFC 6838. + type: string + enum: + - text/html + - application/html + - application/xml + - application/pdf + url: + description: >- + The URL from where the form can be fetched. The content + fetched from the url must be processed as per the mime_type + specified in this object. + type: string + format: uri + refund_terms: + description: Refund terms of this item + type: array + items: + $ref: '#/components/schemas/Item/properties/refund_terms/items' + replacement_terms: + description: Replacement terms of this item + type: array + items: + $ref: '#/components/schemas/ReplacementTerm' + return_terms: + description: Return terms of this item + type: array + items: + $ref: '#/components/schemas/ReturnTerm' + quote: + description: The mutually agreed upon quotation for this order. + allOf: + - $ref: '#/components/schemas/Quotation' + payments: + description: The terms of settlement for this order + type: array + items: + $ref: '#/components/schemas/Payment' + created_at: + description: The date-time of creation of this order + type: string + format: date-time + updated_at: + description: The date-time of updated of this order + type: string + format: date-time + xinput: + description: Additional input required from the customer to confirm this order + allOf: + - $ref: '#/components/schemas/XInput' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Organization: + description: An organization. Usually a recognized business entity. + type: object + additionalProperties: false + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + address: + description: The postal address of the organization + allOf: + - $ref: '#/components/schemas/Address' + state: + description: The state where the organization's address is registered + allOf: + - $ref: '#/components/schemas/State' + city: + description: The city where the the organization's address is registered + allOf: + - $ref: '#/components/schemas/City' + contact: + $ref: '#/components/schemas/Contact' + Payment: + description: >- + Describes the terms of settlement between the BAP and the BPP for a + single transaction. When instantiated, this object contains
  1. the + amount that has to be settled,
  2. The payment destination + destination details
  3. When the settlement should happen, + and
  4. A transaction reference ID
. During a transaction, + the BPP reserves the right to decide the terms of payment. However, the + BAP can send its terms to the BPP first. If the BPP does not agree to + those terms, it must overwrite the terms and return them to the BAP. If + overridden, the BAP must either agree to the terms sent by the BPP in + order to preserve the provider's autonomy, or abort the transaction. In + case of such disagreements, the BAP and the BPP can perform offline + negotiations on the payment terms. Once an agreement is reached, the BAP + and BPP can resume transactions. + type: object + additionalProperties: false + properties: + id: + description: >- + ID of the payment term that can be referred at an item or an order + level in a catalog + type: string + collected_by: + description: >- + This field indicates who is the collector of payment. The BAP can + set this value to 'bap' if it wants to collect the payment first + and settle it to the BPP. If the BPP agrees to those terms, the BPP + should not send the payment url. Alternatively, the BPP can set this + field with the value 'bpp' if it wants the payment to be made + directly. + type: string + url: + type: string + description: >- + A payment url to be called by the BAP. If empty, then the payment is + to be done offline. The details of payment should be present in the + params object. If tl_method = http/get, then the payment details + will be sent as url params. Two url param values, + ```$transaction_id``` and ```$amount``` are mandatory. + format: uri + tl_method: + type: string + params: + type: object + additionalProperties: false + properties: + transaction_id: + type: string + description: The reference transaction ID associated with a payment activity + amount: + type: string + currency: + type: string + bank_code: + type: string + bank_account_number: + type: string + virtual_payment_address: + type: string + source_bank_code: + type: string + source_bank_account_number: + type: string + source_virtual_payment_address: + type: string + type: + type: string + enum: + - PRE-ORDER + - PRE-FULFILLMENT + - ON-FULFILLMENT + - POST-FULFILLMENT + - ON-ORDER + - PART-PAYMENT + status: + type: string + enum: + - PAID + - NOT-PAID + time: + $ref: '#/components/schemas/Time' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Person: + description: Describes a person as any individual + type: object + additionalProperties: false + properties: + id: + type: string + description: Describes the identity of the person + url: + description: Profile url of the person + type: string + format: uri + name: + description: the name of the person + type: string + image: + $ref: '#/components/schemas/Image' + age: + description: Age of the person + allOf: + - $ref: '#/components/schemas/Duration' + dob: + description: Date of birth of the person + type: string + format: date + gender: + type: string + description: >- + Gender of something, typically a Person, but possibly also fictional + characters, animals, etc. While Male and Female may be used, text + strings are also acceptable for people who do not identify as a + binary gender.Allowed values for this field can be published in the + network policy + creds: + type: array + items: + $ref: '#/components/schemas/Credential' + languages: + type: array + items: + description: Describes a language known to the person. + type: object + additionalProperties: false + properties: + code: + type: string + name: + type: string + skills: + type: array + items: + description: Describes a skill of the person. + type: object + additionalProperties: false + properties: + code: + type: string + name: + type: string + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Price: + description: Describes the price of a product or service + type: object + additionalProperties: false + properties: + currency: + type: string + value: + $ref: '#/components/schemas/DecimalValue' + estimated_value: + $ref: '#/components/schemas/DecimalValue' + computed_value: + $ref: '#/components/schemas/DecimalValue' + listed_value: + $ref: '#/components/schemas/DecimalValue' + offered_value: + $ref: '#/components/schemas/DecimalValue' + minimum_value: + $ref: '#/components/schemas/DecimalValue' + maximum_value: + $ref: '#/components/schemas/DecimalValue' + Provider: + description: Describes the catalog of a business. + type: object + additionalProperties: false + properties: + id: + type: string + description: Id of the provider + descriptor: + $ref: '#/components/schemas/Descriptor' + category_id: + type: string + description: Category Id of the provider at the BPP-level catalog + rating: + $ref: '#/components/schemas/Rating/properties/value' + time: + $ref: '#/components/schemas/Time' + categories: + type: array + items: + $ref: '#/components/schemas/Category' + fulfillments: + type: array + items: + $ref: '#/components/schemas/Fulfillment' + payments: + type: array + items: + $ref: '#/components/schemas/Payment' + locations: + type: array + items: + $ref: '#/components/schemas/Location' + offers: + type: array + items: + $ref: '#/components/schemas/Offer' + items: + type: array + items: + $ref: '#/components/schemas/Item' + exp: + type: string + description: Time after which catalog has to be refreshed + format: date-time + rateable: + description: Whether this provider can be rated or not + type: boolean + ttl: + description: >- + The time-to-live in seconds, for this object. This can be overriden + at deeper levels. A value of -1 indicates that this object is not + cacheable. + type: string + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Quotation: + description: >- + Describes a quote. It is the estimated price of products or services + from the BPP.
This has properties like price, breakup, ttl + type: object + additionalProperties: false + properties: + id: + description: ID of the quote. + type: string + format: uuid + price: + description: The total quoted price + allOf: + - $ref: '#/components/schemas/Price' + breakup: + description: the breakup of the total quoted price + type: array + items: + type: object + additionalProperties: false + properties: + item: + $ref: '#/components/schemas/Item' + title: + type: string + price: + $ref: '#/components/schemas/Price' + ttl: + $ref: '#/components/schemas/Duration' + Rating: + description: Describes the rating of an entity + type: object + additionalProperties: false + properties: + rating_category: + description: Category of the entity being rated + type: string + enum: + - Item + - Order + - Fulfillment + - Provider + - Agent + - Support + id: + description: Id of the object being rated + type: string + value: + description: >- + Rating value given to the object. This can be a single value or can + also contain an inequality operator like gt, gte, lt, lte. This can + also contain an inequality expression containing logical operators + like && and ||. + type: string + Region: + description: >- + Describes an arbitrary region of space. The network policy should + contain a published list of supported regions by the network. + type: object + additionalProperties: false + properties: + dimensions: + description: >- + The number of dimensions that are used to describe any point inside + that region. The most common dimensionality of a region is 2, that + represents an area on a map. There are regions on the map that can + be approximated to one-dimensional regions like roads, railway + lines, or shipping lines. 3 dimensional regions are rarer, but are + gaining popularity as flying drones are being adopted for various + fulfillment services. + type: string + enum: + - '1' + - '2' + - '3' + type: + description: >- + The type of region. This is used to specify the granularity of the + region represented by this object. Various examples of + two-dimensional region types are city, country, state, district, and + so on. The network policy should contain a list of all possible + region types supported by the network. + type: string + name: + type: string + description: Name of the region as specified on the map where that region exists. + code: + type: string + description: >- + A standard code representing the region. This should be interpreted + in the same way by all network participants. + boundary: + type: string + description: >- + A string representing the boundary of the region. One-dimensional + regions are represented by polylines. Two-dimensional regions are + represented by polygons, and three-dimensional regions can + represented by polyhedra. + map_url: + type: string + description: >- + The url to the map of the region. This can be a globally recognized + map or the one specified by the network policy. + ReplacementTerm: + description: The replacement policy of an item or an order + type: object + additionalProperties: false + properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: '#/components/schemas/State' + replace_within: + description: >- + Applicable only for buyer managed returns where the buyer has to + replace the item before a certain date-time, failing which they will + not be eligible for replacement + allOf: + - $ref: '#/components/schemas/Time' + external_ref: + $ref: '#/components/schemas/MediaFile' + ReturnTerm: + description: Describes the return policy of an item or an order + type: object + additionalProperties: false + properties: + fulfillment_state: + description: The state of fulfillment during which this term IETF''s applicable. + allOf: + - $ref: '#/components/schemas/State' + return_eligible: + description: Indicates whether the item is eligible for return + type: boolean + return_time: + description: >- + Applicable only for buyer managed returns where the buyer has to + return the item to the origin before a certain date-time, failing + which they will not be eligible for refund. + allOf: + - $ref: '#/components/schemas/Time' + return_location: + description: The location where the item or order must / will be returned to + allOf: + - $ref: '#/components/schemas/Location' + fulfillment_managed_by: + description: The entity that will perform the return + type: string + enum: + - CONSUMER + - PROVIDER + Scalar: + description: Describes a scalar + type: object + additionalProperties: false + properties: + type: + type: string + enum: + - CONSTANT + - VARIABLE + value: + $ref: '#/components/schemas/DecimalValue' + estimated_value: + $ref: '#/components/schemas/DecimalValue' + computed_value: + $ref: '#/components/schemas/DecimalValue' + range: + type: object + additionalProperties: false + properties: + min: + $ref: '#/components/schemas/DecimalValue' + max: + $ref: '#/components/schemas/DecimalValue' + unit: + type: string + Schedule: + description: >- + Describes schedule as a repeating time period used to describe a + regularly recurring event. At a minimum a schedule will specify + frequency which describes the interval between occurrences of the event. + Additional information can be provided to specify the schedule more + precisely. This includes identifying the timestamps(s) of when the event + will take place. Schedules may also have holidays to exclude a specific + day from the schedule.
This has properties like frequency, holidays, + times + type: object + additionalProperties: false + properties: + frequency: + $ref: '#/components/schemas/Duration' + holidays: + type: array + items: + type: string + format: date-time + times: + type: array + items: + type: string + format: date-time + State: + description: A bounded geopolitical region of governance inside a country. + type: object + additionalProperties: false + properties: + name: + type: string + description: Name of the state + code: + type: string + description: State code as per country or international standards + Stop: + description: A logical point in space and time during the fulfillment of an order. + type: object + additionalProperties: false + properties: + id: + type: string + parent_stop_id: + type: string + location: + description: Location of the stop + allOf: + - $ref: '#/components/schemas/Location' + type: + description: >- + The type of stop. Allowed values of this property can be defined by + the network policy. + type: string + time: + description: Timings applicable at the stop. + allOf: + - $ref: '#/components/schemas/Time' + instructions: + description: Instructions that need to be followed at the stop + allOf: + - $ref: '#/components/schemas/Descriptor' + contact: + description: Contact details of the stop + allOf: + - $ref: '#/components/schemas/Contact' + person: + description: The details of the person present at the stop + allOf: + - $ref: '#/components/schemas/Person' + authorization: + $ref: '#/components/schemas/Authorization' + Support: + description: Details of customer support + type: object + additionalProperties: false + properties: + ref_id: + type: string + callback_phone: + type: string + format: phone + phone: + type: string + format: phone + email: + type: string + format: email + url: + type: string + format: uri + Tag: + description: >- + Describes a tag. This is used to contain extended metadata. This object + can be added as a property to any schema to describe extended + attributes. For BAPs, tags can be sent during search to optimize and + filter search results. BPPs can use tags to index their catalog to allow + better search functionality. Tags are sent by the BPP as part of the + catalog response in the `on_search` callback. Tags are also meant for + display purposes. Upon receiving a tag, BAPs are meant to render them as + name-value pairs. This is particularly useful when rendering tabular + information about a product or service. + type: object + additionalProperties: false + properties: + descriptor: + description: Description of the Tag, can be used to store detailed information. + allOf: + - $ref: '#/components/schemas/Descriptor' + value: + description: >- + The value of the tag. This set by the BPP and rendered as-is by the + BAP. + type: string + display: + description: >- + This value indicates if the tag is intended for display purposes. If + set to `true`, then this tag must be displayed. If it is set to + `false`, it should not be displayed. This value can override the + group display value. + type: boolean + TagGroup: + description: >- + A collection of tag objects with group level attributes. For detailed + documentation on the Tags and Tag Groups schema go to + https://github.com/beckn/protocol-specifications/discussions/316 + type: object + additionalProperties: false + properties: + display: + description: >- + Indicates the display properties of the tag group. If display is set + to false, then the group will not be displayed. If it is set to + true, it should be displayed. However, group-level display + properties can be overriden by individual tag-level display + property. As this schema is purely for catalog display purposes, it + is not recommended to send this value during search. + type: boolean + default: true + descriptor: + description: >- + Description of the TagGroup, can be used to store detailed + information. + allOf: + - $ref: '#/components/schemas/Descriptor' + list: + description: >- + An array of Tag objects listed under this group. This property can + be set by BAPs during search to narrow the `search` and achieve more + relevant results. When received during `on_search`, BAPs must render + this list under the heading described by the `name` property of this + schema. + type: array + items: + $ref: '#/components/schemas/Tag' + Time: + description: >- + Describes time in its various forms. It can be a single point in time; + duration; or a structured timetable of operations
This has properties + like label, time stamp,duration,range, days, schedule + type: object + additionalProperties: false + properties: + label: + type: string + timestamp: + type: string + format: date-time + duration: + $ref: '#/components/schemas/Duration' + range: + type: object + additionalProperties: false + properties: + start: + type: string + format: date-time + end: + type: string + format: date-time + days: + type: string + description: comma separated values representing days of the week + schedule: + $ref: '#/components/schemas/Schedule' + Tracking: + description: >- + Contains tracking information that can be used by the BAP to track the + fulfillment of an order in real-time. which is useful for knowing the + location of time sensitive deliveries. + type: object + additionalProperties: false + properties: + id: + description: A unique tracking reference number + type: string + url: + description: >- + A URL to the tracking endpoint. This can be a link to a tracking + webpage, a webhook URL created by the BAP where BPP can push the + tracking data, or a GET url creaed by the BPP which the BAP can poll + to get the tracking data. It can also be a websocket URL where the + BPP can push real-time tracking data. + type: string + format: uri + location: + description: >- + In case there is no real-time tracking endpoint available, this + field will contain the latest location of the entity being tracked. + The BPP will update this value everytime the BAP calls the track + API. + allOf: + - $ref: '#/components/schemas/Location' + status: + description: >- + This value indicates if the tracking is currently active or not. If + this value is `active`, then the BAP can begin tracking the order. + If this value is `inactive`, the tracking URL is considered to be + expired and the BAP should stop tracking the order. + type: string + enum: + - active + - inactive + Vehicle: + description: >- + Describes a vehicle is a device that is designed or used to transport + people or cargo over land, water, air, or through space.
This has + properties like category, capacity, make, model, + size,variant,color,energy_type,registration + type: object + additionalProperties: false + properties: + category: + type: string + capacity: + type: integer + make: + type: string + model: + type: string + size: + type: string + variant: + type: string + color: + type: string + energy_type: + type: string + registration: + type: string + wheels_count: + type: string + cargo_volumne: + type: string + wheelchair_access: + type: string + code: + type: string + emission_standard: + type: string + XInput: + description: >- + Contains any additional or extended inputs required to confirm an order. + This is typically a Form Input. Sometimes, selection of catalog elements + is not enough for the BPP to confirm an order. For example, to confirm a + flight ticket, the airline requires details of the passengers along with + information on baggage, identity, in addition to the class of ticket. + Similarly, a logistics company may require details on the nature of + shipment in order to confirm the shipping. A recruiting firm may require + additional details on the applicant in order to confirm a job + application. For all such purposes, the BPP can choose to send this + object attached to any object in the catalog that is required to be sent + while placing the order. This object can typically be sent at an item + level or at the order level. The item level XInput will override the + Order level XInput as it indicates a special requirement of information + for that particular item. Hence the BAP must render a separate form for + the Item and another form at the Order level before confirmation. + type: object + additionalProperties: false + properties: + head: + description: Provides the header information for the xinput. + type: object + additionalProperties: false + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + index: + type: object + additionalProperties: false + properties: + min: + type: integer + cur: + type: integer + max: + type: integer + headings: + type: array + items: + type: string + description: The heading names of the forms + form: + $ref: '#/components/schemas/Form' + form_response: + description: Describes the response to a form submission + type: object + additionalProperties: false + properties: + status: + description: Contains the status of form submission. + type: string + signature: + type: string + submission_id: + type: string + errors: + type: array + items: + $ref: '#/components/schemas/Error' + required: + description: >- + Indicates whether the form data is mandatorily required by the BPP + to confirm the order. + type: boolean +x-enum: + search: + context: + action: + - code: search + description: Buyer app indicates the search intent + reference: + location: &ref_0 + country: + code: + - code: IND + description: Represents the country + reference: + city: + code: + - code: std:080 + description: Bangalore + reference: + domain: &ref_1 + - code: ONDC:TRV10 + description: mobility domain Ride + reference: + message: + intent: + fulfillment: &ref_2 + vehicle: + category: + - code: AUTO_RICKSHAW + description: Describes the vehicle category as Auto Rickshaw + reference: - + Describes OTP as an authorization mechanism used to start or + end the fulfillment of an order. + reference: - + Describes QR as an authorization mechanism used to start or + end the fulfillment of an order. + reference: - + Describes the state when the rider has arrived at the pickup + location. + reference: - + NOT-PAID indicates a payment status where the payment process + has not been completed. + reference: - + PAID indicates a payment status where the payment process has + been successfully completed. + reference: + location: *ref_0 + domain: *ref_1 + message: + catalog: + providers: + items: &ref_4 + descriptor: + code: + - code: RIDE + description: Describes the type of ride. + reference: + location: *ref_0 + domain: *ref_1 + message: + order: &ref_6 + items: *ref_4 + fulfillments: *ref_2 + payments: *ref_3 + status: &ref_5 + - code: SOFT-CANCEL + description: >- + Describes a soft-cancel request initiated by the buyer app, a step + preceding cancellation. + reference: - + Describes a confirm-cancel request initiated by the buyer app, + confirming the order cancellation + reference: - + Seller app provides serviceability info, quotes, and O2D TAT for + selected items. + reference: + location: *ref_0 + domain: *ref_1 + message: + order: &ref_10 + items: *ref_4 + fulfillments: *ref_2 + payments: *ref_3 + status: *ref_5 + quote: &ref_8 + breakup: + title: + - code: BASE_FARE + description: Describes the base fare for a specific ride. + reference: - + Buyer and seller apps confirm terms & conditions before placing + orders. + reference: + location: *ref_0 + domain: *ref_1 + message: + order: *ref_6 + on_init: + context: + action: + - code: on_init + description: >- + Buyer and seller apps agree to terms & conditions before placing + orders. + reference: + location: *ref_0 + domain: *ref_1 + message: + order: &ref_9 + items: *ref_4 + fulfillments: *ref_2 + payments: *ref_3 + cancellation_terms: + fulfillment_state: *ref_7 + quote: *ref_8 + confirm: + context: + action: + - code: confirm + description: Buyer app submits orders on behalf of the buyer. + reference: + location: *ref_0 + domain: *ref_1 + message: + order: *ref_6 + on_confirm: + context: + action: + - code: on_confirm + description: >- + Seller app responds to the order with auto-acceptance, deferred + acceptance, or rejection. + reference: + location: *ref_0 + domain: *ref_1 + message: + order: *ref_9 + status: + context: + action: + - code: status + description: Buyer app request for status of the order + reference: + location: *ref_0 + domain: *ref_1 + on_status: + context: + action: + - code: on_status + description: Seller app return order with status , Driver pickup - driver drop + reference: + location: *ref_0 + domain: *ref_1 + message: + order: *ref_9 + cancel: + context: + action: + - code: cancel + description: Buyer app requests order cancellation." + reference: + location: *ref_0 + domain: *ref_1 + message: + cancellation_reason_id: + - code: '001' + description: Driver not moving + reference: + location: *ref_0 + domain: *ref_1 + message: + order: + items: *ref_4 + fulfillments: *ref_2 + payments: *ref_3 + cancellation: + reason: + descriptor: + code: + - code: '011' + description: >- + Seller app cannot confirm the ride as no drivers are + available + reference: + location: *ref_0 + domain: *ref_1 + message: + order: *ref_10 + on_update: + context: + action: + - code: on_cancel + description: Seller app specifies the update status. + reference: + location: *ref_0 + domain: *ref_1 + message: + order: *ref_10 +x-tags: + search: + message: + intent: + payment: &ref_11 + tags: + - code: BUYER_FINDER_FEES + description: Describes the finder fees for buyer + reference: + list: + - code: BUYER_FINDER_FEES_TYPE + description: Buyer finder fee type + reference: + - code: BUYER_FINDER_FEES_PERCENTAGE + description: Buyer finder fee in percentage + reference: + - code: BUYER_FINDER_FEES_AMOUNT + description: Buyer finder fee in amount + reference: + - code: SETTLEMENT_TERMS + description: Describes the settlement terms + reference: + list: + - code: SETTLEMENT_WINDOW + description: Time window to complete settlement + reference: + - code: SETTLEMENT_BASIS + description: Basis required to complete settlement + reference: + - code: SETTLEMENT_TYPE + description: Payment method to complete settlement + reference: + - code: MANDATORY_ARBITRATION + description: >- + Flag to denote if dispute can be resolved through + arbitration + reference: + - code: COURT_JURISDICTION + description: Denotes court that will have jurisdiction for the case + reference: + - code: DELAY_INTEREST + description: Denotes interest to be paid as a delay charge + reference: + - code: STATIC_TERMS + description: Terms for settlement + reference: + - code: SETTLEMENT_AMOUNT + description: Denotes settlement amount + reference: + on_search: + message: + catalog: + providers: + items: &ref_12 + tags: + - code: FARE_POLICY + description: Details about fare for the ride + reference: + list: + - code: MIN_FARE + description: Describes the minimum fare + reference: + - code: MIN_FARE_DISTANCE_KM + description: Describes the minimum fare per KM + reference: + - code: PER_KM_CHARGE + description: Describes the per km charge + reference: + - code: PICKUP_CHARGE + description: Describes the pickup charge + reference: + - code: WAITING_CHARGE_PER_MIN + description: Describes the waiting charge per minute + reference: + - code: NIGHT_CHARGE_MULTIPLIER + description: Describes the times need to multiply for night charge + reference: + - code: NIGHT_SHIFT_START_TIME + description: Describes the time when night shift starts + reference: + - code: NIGHT_SHIFT_END_TIME + description: Describes the time when night shift ends + reference: + - code: INFO + description: Describes the general info about the ride + reference: + list: + - code: DISTANCE_TO_NEAREST_DRIVER_METER + description: Describes the distance to nearest driver. + reference: + - code: ETA_TO_NEAREST_DRIVER_MIN + description: Describes the ETA to nearest driver. + reference: + payments: *ref_11 + on_select: + message: + order: + items: *ref_12 + fulfillments: &ref_13 + tags: + - code: ROUTE_INFO + description: Describes the route information. + reference: + list: + - code: ENCODED_POLYLINE + description: Describes the encoded polyline value. + reference: + - code: WAYPOINTS + description: Describes the waypoints value. + reference: + init: + message: + order: + payments: *ref_11 + on_init: &ref_14 + message: + order: + items: *ref_12 + payments: *ref_11 + fulfillments: *ref_13 + confirm: *ref_14 + on_confirm: *ref_14 + on_status: *ref_14 + on_cancel: *ref_14 + on_update: *ref_14 +x-flows: + - summary: On-Demand - Assign driver on on-confirm + details: + - description: >- + The illustraive flow to perform a transaction of the nature where in a + buyer would like to book a mobility service form location + A(gps-cordinates) to localtion B(gps-cordinates) + mermaid: |- + sequenceDiagram + title On-Demand Discovery + Buyer Platform (BAP)->>Gateway (BG): search + Gateway (BG) ->> Buyer Platform (BAP): ACK + Gateway (BG)->>Registry: Lookup Seller Platforms (lookup) + Registry->>Gateway (BG): List of Seller Platforms (200 OK) + Gateway (BG)->>Seller Platform (BPP): search + Seller Platform (BPP)->>Gateway (BG) : ACK + Seller Platform (BPP)->>Buyer Platform (BAP): Publish Catalog of Seller 1 (on_search) + Buyer Platform (BAP)->>Seller Platform (BPP): ACK + - description: Ordering + mermaid: |- + sequenceDiagram + title Selection + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): select + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_select + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Initializing the order + mermaid: |- + sequenceDiagram + title Initializing Order + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Order Confirmation + mermaid: |- + sequenceDiagram + title Order Confirmation + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Fulfillment + mermaid: |- + sequenceDiagram + title Order Fulfillment + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): status-Request application status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_status - Provide application status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + steps: + - summary: Buyer app search for available ride providers + api: search + details: + - description: >- + Buyer app explore ride providers to avail a mobility service from + Location A to Location B (GPS) over the network. + mermaid: |- + sequenceDiagram + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Gateway (BG): search + Gateway (BG) ->> Buyer Platform (BAP): ACK + Gateway (BG)->>Registry: Lookup Seller Platforms (lookup) + Registry->>Gateway (BG): List of Seller Platforms (200 OK) + Gateway (BG)->>Seller Platform (BPP): search + Seller Platform (BPP)->>Gateway (BG) : ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP): Publish Catalog of Seller 1 (on_search) + Buyer Platform (BAP)->>Seller Platform (BPP): ACK + reference: if any + example: &ref_15 + summary: >- + Search for mobility services by pickup and drop location[Seller + Collecting] + value: + context: + action: search + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 40963dc1-e402-4f4d-ae70-7c5864ca682c + timestamp: '2023-12-09T13:39:56.645Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + intent: + fulfillment: + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + payment: + collected_by: BPP + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bap.com/static-terms.txt + - summary: Get a list of all services from ride providers + api: on_search + details: + - description: >- + Ride providers which is a mobility provider platform sends the + catalog of all services that can be used for transit from A to B + along with estimated fare. + mermaid: |- + sequenceDiagram + Buyer Platform (BAP)->>Gateway (BG): search + Gateway (BG) ->> Buyer Platform (BAP): ACK + Gateway (BG)->>Registry: Lookup Seller Platforms (lookup) + Registry->>Gateway (BG): List of Seller Platforms (200 OK) + Gateway (BG)->>Seller Platform (BPP): search + Seller Platform (BPP)->>Gateway (BG) : ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): Publish Catalog of Seller 1 (on_search) + Buyer Platform (BAP)->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_16 + summary: Return a mobility catalog[Seller Collecting] + value: + context: + action: on_search + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 21e54d3c-9c3b-47c1-aa3b-b0e7b20818ee + timestamp: '2023-12-09T13:41:16.161Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + catalog: + descriptor: + name: Mobility Servies BPP + providers: + - fulfillments: + - id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + - id: F2 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + type: DELIVERY + vehicle: + category: CAB + id: P1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + - descriptor: + code: RIDE + name: CAB Economy Ride + fulfillment_ids: + - F2 + id: I2 + location_ids: + - L2 + - L4 + price: + currency: INR + maximum_value: '236' + minimum_value: '206' + value: '206' + locations: + - gps: 12.916468,77.608998 + id: L1 + - gps: 12.916714,77.609298 + id: L2 + - gps: 12.916573,77.615216 + id: L3 + - gps: 12.906857,77.604456 + id: L4 + payments: + - collected_by: BPP + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - summary: Buyer app selects a specific service for more details + api: select + details: + - description: >- + The buyer app has selected a specific service and would like to + obtain a quotation for that service. Since the max_callbacks is + set to 1, the consumer platform will consider only one on_select + response for the quotation. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): select + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_select + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_17 + summary: Get quote for a specific product from a mobility catalog + value: + context: + action: select + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 432fdfd6-0457-47b6-9fac-80cbe5c0a75b + timestamp: '2023-12-09T13:49:01.460Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: P120S + version: 2.0.0 + message: + order: + items: + - id: I1 + provider: + id: P1 + - summary: Ride provider provides the quote for selected service + api: on_select + details: + - description: >- + Ride provider responds with detailed information and quote for the + specific service that the buyer app would like to avail. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): select + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_select + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_18 + summary: Return a quote offered by a provider + value: + context: + action: on_select + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-09T13:49:26.132Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + fulfillments: + - id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: P200s + - summary: Buyer app initializes the ride request + api: init + details: + - description: >- + Buyer app platform shares the terms of order and initializes the + request. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_19 + summary: >- + Initialize draft order and request for terms of service[Seller + Collecting] + value: + context: + action: init + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-09T14:09:31.307Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + billing: + name: Joe Adams + fulfillments: + - customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + vehicle: + category: AUTO_RICKSHAW + items: + - id: I1 + payments: + - collected_by: BPP + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + type: ON-FULFILLMENT + provider: + id: P1 + - summary: Ride provider accepts/appends the terms of orders + api: on_init + details: + - description: >- + Ride provider accepts the terms of order and appends its own terms + and responds with the final draft. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_20 + summary: Return draft order with payment terms[Seller Collecting] + value: + context: + action: on_init + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-09T14:11:32.859Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - id: F1 + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + - summary: Buyer app confirms the ride + api: confirm + details: + - description: >- + Buyer app confirms the booking and provides all the required + information for confirmation as per the terms of the order. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_21 + summary: Confirm ride booking + value: + context: + action: confirm + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + timestamp: '2023-12-10T04:34:48.031Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + billing: + name: Joe Adams + fulfillments: + - customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + vehicle: + category: AUTO_RICKSHAW + items: + - id: I1 + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bap.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + - summary: Ride provider confirms the ride request + api: on_confirm + details: + - description: >- + Ride provider confirms the ride request and provides the ride + details on confirmation. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_25 + summary: Return confirmed order with latest fulfillment details + value: + context: + action: on_confirm + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-10T08:03:34.294Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ASSIGNED + stops: + - authorization: + token: '234234' + type: OTP + location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + status: ACTIVE + created_at: '2023-12-10T08:03:34.294Z' + updated_at: '2023-12-10T08:03:34.294Z' + - summary: Ride provider provides latest update on the ride (unsolicited call) + api: on_update + details: + - description: >- + Ride provider provides the latest update on ride details to the + buyer app. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): on_update + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_32 + summary: Return updated order with recomputed charges + value: + context: + action: on_update + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-11T03:54:28.832Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ENDED + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + status: COMPLETED + created_at: '2023-12-10T08:03:34.294Z' + updated_at: '2023-12-11T03:54:28.832Z' + - summary: Buyer app requests for tracking status + api: track + details: + - description: >- + Buyer app request the provider platform to provide with latest + tracking status + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): track - Request tracking status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP): on_track - Provide tracking status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_22 + summary: Track an active ride + value: + context: + action: track + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order_id: O1 + - summary: Provider platform provides latest order tracking status + api: on_track + details: + - description: >- + Provider platform provides the updated order tracking status to + the consumer + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): track - Request tracking status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): on_track - Provide tracking status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_23 + summary: Return tracking information for an order + value: + context: + action: on_track + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: ec3dea8c-c64c-4f06-b2a0-ec1f9584d7ba + timestamp: '2023-03-23T05:41:09Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + tracking: + status: active + location: + gps: 28.620976, 77.046732 + updated_at: '2023-03-23T05:41:09Z' + - summary: Buyer app seeks the most recent status update + api: status + details: + - description: >- + Buyer app requests the ride provider to provide the latest order + status + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP): on_update + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_24 + summary: Get latest fulfillment status of a booking + value: + context: + action: status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order_id: O1 + - summary: Ride provider provides latest order status + api: on_status + details: + - description: Ride provider provides the updated order status to the buyer app + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP): on_update + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: + summary: Return order with status - Driver at pickup + value: + context: + action: on_status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:59Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + id: O1 + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ENDED + name: Your ride has ended + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '156' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + transaction_id: f08966dc-4c7d-4152-9a15-1046798cc39c + amount: '146' + status: PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: Delivery + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '2.5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: P200S + status: COMPLETED + created_at: '2023-12-10T08:03:34.294Z' + updated_at: '2023-12-11T03:54:28.832Z' + - summary: On-Demand - Assign driver post on-confirm + details: + - description: >- + The illustraive flow to perform a transaction of the nature where in a + buyer would like to book a mobility service form location + A(gps-cordinates) to localtion B(gps-cordinates) + mermaid: |- + sequenceDiagram + title On-Demand Discovery + Buyer Platform (BAPA)->>Gateway (BG): search + Gateway (BG) ->> Buyer Platform (BAP): ACK + Gateway (BG)->>Registry: Lookup Seller Platforms (lookup) + Registry->>Gateway (BG): List of Seller Platforms (200 OK) + Gateway (BG)->>Seller Platform (BPP): search + Seller Platform (BPP)->>Gateway (BG) : ACK + Seller Platform (BPP)->>Buyer Platform (BAP): Publish Catalog of Seller 1 (on_search) + Buyer Platform (BAP)->>Seller Platform (BPP): ACK + - description: Ordering + mermaid: |- + sequenceDiagram + title Selection + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): select + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_select + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Initializing the order + mermaid: |- + sequenceDiagram + title Initializing Order + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Order Confirmation + mermaid: |- + sequenceDiagram + title Order Confirmation + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Fulfillment + mermaid: |- + sequenceDiagram + title Order Fulfillment + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): status-Request application status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_status - Provide application status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + steps: + - summary: Buyer app search for available ride providers + api: search + details: + - description: >- + Buyer app explore ride providers to avail a mobility service from + Location A to Location B (GPS) over the network. + mermaid: |- + sequenceDiagram + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Gateway (BG): search + Gateway (BG) ->> Buyer Platform (BAP): ACK + Gateway (BG)->>Registry: Lookup Seller Platforms (lookup) + Registry->>Gateway (BG): List of Seller Platforms (200 OK) + Gateway (BG)->>Seller Platform (BPP): search + Seller Platform (BPP)->>Gateway (BG) : ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP): Publish Catalog of Seller 1 (on_search) + Buyer Platform (BAP)->>Seller Platform (BPP): ACK + reference: if any + example: *ref_15 + - summary: Get a list of all services from ride providers + api: on_search + details: + - description: >- + Ride providers which is a mobility provider platform sends the + catalog of all services that can be used for transit from A to B + along with estimated fare. + mermaid: |- + sequenceDiagram + Buyer Platform (BAP)->>Gateway (BG): search + Gateway (BG) ->> Buyer Platform (BAP): ACK + Gateway (BG)->>Registry: Lookup Seller Platforms (lookup) + Registry->>Gateway (BG): List of Seller Platforms (200 OK) + Gateway (BG)->>Seller Platform (BPP): search + Seller Platform (BPP)->>Gateway (BG) : ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): Publish Catalog of Seller 1 (on_search) + Buyer Platform (BAP)->>Seller Platform (BPP): ACK + end + reference: if any + example: *ref_16 + - summary: Buyer app selects a specific service for more details + api: select + details: + - description: >- + The buyer app has selected a specific service and would like to + obtain a quotation for that service. Since the max_callbacks is + set to 1, the consumer platform will consider only one on_select + response for the quotation. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): select + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_select + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: *ref_17 + - summary: Ride provider provides the quote for selected service + api: on_select + details: + - description: >- + Ride provider responds with detailed information and quote for the + specific service that the buyer app would like to avail. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): select + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_select + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: *ref_18 + - summary: Buyer app initializes the ride request + api: init + details: + - description: >- + Buyer app platform shares the terms of order and initializes the + request. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: *ref_19 + - summary: Ride provider accepts/appends the terms of orders + api: on_init + details: + - description: >- + Ride provider accepts the terms of order and appends its own terms + and responds with the final draft. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: *ref_20 + - summary: Buyer app confirms the ride + api: confirm + details: + - description: >- + Buyer app confirms the booking and provides all the required + information for confirmation as per the terms of the order. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: *ref_21 + - summary: Ride provider confirms the ride request + api: on_confirm + details: + - description: >- + Ride provider confirms the ride request and provides the ride + details on confirmation. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_30 + summary: Return confirmed order with latest fulfillment details + value: + context: + action: on_confirm + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:34.53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_CONFIRMED + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + status: ACTIVE + created_at: '2023-03-23T04:48:34.53Z' + updated_at: '2023-03-23T04:48:34.53Z' + - summary: Ride provider provides latest update on the ride (unsolicited call) + api: on_update + details: + - description: >- + Ride provider provides the latest update on ride details to the + buyer app. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): on_update + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_33 + summary: Return updated order with updated agent details + value: + context: + action: on_update + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:49:34.53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ASSIGNED + stops: + - authorization: + token: '234234' + type: OTP + location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + status: ACTIVE + created_at: '2023-03-23T04:48:34.53Z' + updated_at: '2023-03-23T04:49:34.53Z' + - summary: Buyer app requests for tracking status + api: track + details: + - description: >- + Buyer app request the provider platform to provide with latest + tracking status + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): track - Request tracking status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP): on_track - Provide tracking status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: *ref_22 + - summary: Provider platform provides latest order tracking status + api: on_track + details: + - description: >- + Provider platform provides the updated order tracking status to + the consumer + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): track - Request tracking status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): on_track - Provide tracking status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: *ref_23 + - summary: Buyer app seeks the most recent status update + api: status + details: + - description: >- + Buyer app requests the ride provider to provide the latest order + status + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP): on_update + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: *ref_24 + - summary: Ride provider provides latest order status + api: on_status + details: + - description: Ride provider provides the updated order status to the buyer app + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP): on_update + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_31 + summary: Return order with status - Driver at pickup + value: + context: + action: on_status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:59Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + id: O1 + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ENDED + name: Your ride has ended + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '156' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + transaction_id: f08966dc-4c7d-4152-9a15-1046798cc39c + amount: '146' + status: PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: Delivery + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '2.5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: P200S + status: COMPLETED + created_at: '2023-03-23T04:48:34.53Z' + updated_at: '2023-03-23T04:49:34.53Z' + - summary: On-Demand - Ride cancellation by rider + details: + - description: Detailed process of cancelling a ride with soft & confirm status. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + steps: + - summary: Ride provider confirms the ride request + api: on_confirm + details: + - description: >- + Ride provider confirms the ride request and provides the ride + details on confirmation. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + Buyer Platform (BAP)->>Seller Platform (BPP): cancel - with soft_cancel request + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: *ref_25 + - summary: Buyer app cancels the request for ride + api: cancel + details: + - description: Buyer app requests for cancellation of ride. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): cancel - with soft_cancel request + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_27 + summary: Initiates cancelling a ride with soft cancel status + value: + context: + action: cancel + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: >- + api.beckn.juspay.in/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: be6a495a-e941-4fbf-9d59-f1e6166cccc8 + timestamp: '2023-03-23T05:15:08Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + cancellation_reason_id: '7' + descriptor: + code: SOFT_CANCEL + name: Ride Cancellation + order_id: O1 + - summary: Ride provider accepts/appends the terms of cancellation + api: on_cancel + details: + - description: >- + Ride provider accepts the terms of order and appends its own terms + and provides with latest order update. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + Buyer Platform (BAP)->>Seller Platform (BPP): cancel - with soft_cancel request + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_29 + summary: Return current order status after soft-cancel + value: + context: + action: on_cancel + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + version: 2.0.0 + ttl: PT30S + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_CONFIRMED + stops: + - authorization: + token: '234234' + type: OTP + location: + gps: 13.008935, 77.644408 + time: + duration: PT2H + type: START + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: CAB Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '156' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BAP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: Delivery + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '2.5' + - descriptor: + code: STATIC_TERMS + value: >- + https://www.icicibank.com/personal-banking/loans/personal-loan + - descriptor: + code: SETTLEMENT_AMOUNT + value: '85' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + - price: + currency: INR + value: '10' + title: CANCELLATION_CHARGES + price: + currency: INR + value: '156' + ttl: P200S + status: SOFT_CANCEL + - summary: Buyer app confirms the cancel request for ride + api: cancel + details: + - description: Buyer app give the confirmation to cancel the ride. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): cancel - with confirm_cancel request + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: &ref_28 + summary: Initiates cancelling a ride with confirm cancel status + value: + context: + action: cancel + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: >- + api.beckn.juspay.in/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: be6a495a-e941-4fbf-9d59-f1e6166cccc8 + timestamp: '2023-03-23T05:15:08Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + cancellation_reason_id: '7' + descriptor: + code: CONFIRM_CANCEL + name: Ride Cancellation + order_id: O1 + - summary: Ride provider accepts the terms of cancellation + api: on_cancel + details: + - description: >- + Ride provider accepts the terms of order and provides with latest + order update. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): cancel - with confirm_cancel request + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: &ref_26 + summary: Return current order status after confirm-cancel + value: + context: + action: on_cancel + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + version: 2.0.0 + ttl: PT30S + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_CANCELLED + stops: + - authorization: + token: '234234' + type: OTP + location: + gps: 13.008935, 77.644408 + time: + duration: PT2H + type: START + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: CAB Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '156' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BAP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: Delivery + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '2.5' + - descriptor: + code: STATIC_TERMS + value: >- + https://www.icicibank.com/personal-banking/loans/personal-loan + - descriptor: + code: SETTLEMENT_AMOUNT + value: '85' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: P200S + status: CANCELLED + - summary: On-Demand - Ride cancellation by driver + details: + - description: Detailed process of cancelling a ride with soft & confirm status. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel (unsolicited) + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + steps: + - summary: Ride provider confirms the ride request + api: on_confirm + details: + - description: >- + Ride provider confirms the ride request and provides the ride + details on confirmation. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel (unsolicited) + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: *ref_25 + - summary: Ride provider accepts the terms of cancellation + api: on_cancel + details: + - description: >- + Ride provider accepts the terms of order and provides with latest + order update. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_cancel (unsolicited) + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: *ref_26 + - summary: BPP Collecting - Payment Confirmation + details: + - description: >- + The illustrative flow depicts the comprehensive process of payment + confirmation, showcasing the sequential steps and interactions + involved in a payment transaction. + mermaid: |- + sequenceDiagram + title Initializing Order + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Order Confirmation + mermaid: |- + sequenceDiagram + title Order Confirmation + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + - description: Fulfillment + mermaid: |- + sequenceDiagram + title Order Fulfillment + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): status-Request application status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_status - Provide application status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + steps: + - summary: Buyer app initializes the ride request + api: init + details: + - description: >- + Buyer app platform shares the terms of order and initializes the + request. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + Seller Platform (BPP) ->> Buyer Platform (BAP) : form + reference: if any + example: + summary: >- + Initialize draft order and request for terms of service[Buyer + Collecting] + value: + context: + action: init + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + billing: + name: Joe Adams + fulfillments: + - customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + vehicle: + category: AUTO_RICKSHAW + items: + - id: I1 + payments: + - collected_by: BAP + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT1D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_AMOUNT + value: '144.54' + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bap.com/static-terms.txt + type: PRE-ORDER + provider: + id: P1 + - summary: Ride provider accepts/appends the terms of orders + api: on_init + details: + - description: >- + Ride provider accepts the terms of order and appends its own terms + and responds with the final draft. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + Seller Platform (BPP) ->> Buyer Platform (BAP) : form + reference: if any + example: + summary: Return draft order with payment terms[Buyer Collecting] + value: + context: + action: on_init + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-09T14:11:32.859Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - id: F1 + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BAP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '144.54' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + - summary: Buyer app redirects to payment gateway page. + api: form + details: + - description: >- + Buyer app fetches the SIP setup form from the provider using the + link provided in the previous step. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): init + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + Seller Platform (BPP)->>Buyer Platform (BAP):on_init + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + rect rgb(191, 223, 255) + Seller Platform (BPP) ->> Buyer Platform (BAP) : form + end + reference: if any + example: + value: This will redirected to different html page + - summary: Buyer app seeks the most recent status update + api: status + details: + - description: >- + Buyer app requests the ride provider to provide the latest order + status + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: + summary: Get latest fulfillment status of a booking + value: + context: + action: status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: d883e7f9-f6bc-4ddf-b64c-a2bc44e63ae2 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + ref_id: 870782be-6757-43f1-945c-8eeaf9536259 + - summary: Ride provider provides latest order status + api: on_status + details: + - description: Ride provider provides the updated order status to the buyer app + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + Buyer Platform (BAP)->>Seller Platform (BPP): status + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP): on_status + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: + summary: Return draft order with payment terms[Buyer Collecting] + value: + context: + action: on_status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: d883e7f9-f6bc-4ddf-b64c-a2bc44e63ae2 + timestamp: '2023-03-23T04:48:59Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + transaction_id: f08966dc-4c7d-4152-9a15-1046798cc39c + amount: '146' + status: PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '144.54' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + - summary: Buyer app confirms the ride + api: confirm + details: + - description: >- + Buyer app confirms the booking and provides all the required + information for confirmation as per the terms of the order. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + rect rgb(191, 223, 255) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + end + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + reference: if any + example: + summary: Confirm ride booking + value: + context: + action: confirm + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 9a7be37d-f228-432b-9aa9-65144d48da38 + timestamp: '2023-12-10T04:34:49.031Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + billing: + name: Joe Adams + fulfillments: + - customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + vehicle: + category: AUTO_RICKSHAW + items: + - id: I1 + payments: + - collected_by: BPP + id: PA1 + params: + transaction_id: f08966dc-4c7d-4152-9a15-1046798cc39c + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bap.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '144.54' + type: PRE-ORDER + provider: + id: P1 + - summary: Ride provider confirms the ride request + api: on_confirm + details: + - description: >- + Ride provider confirms the ride request and provides the ride + details on confirmation. + mermaid: |- + sequenceDiagram + participant Buyer Platform (BAP) + participant Seller Platform (BPP) + Buyer Platform (BAP)->>Seller Platform (BPP): confirm + Seller Platform (BPP)-->>Buyer Platform (BAP):ACK + rect rgb(191, 223, 255) + Seller Platform (BPP)->>Buyer Platform (BAP):on_confirm + Buyer Platform (BAP)-->>Seller Platform (BPP): ACK + end + reference: if any + example: + summary: Return confirmed order with latest fulfillment details + value: + context: + action: on_confirm + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 9a7be37d-f228-432b-9aa9-65144d48da38 + timestamp: '2023-12-10T04:34:52.031Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ASSIGNED + stops: + - authorization: + token: '234234' + type: OTP + location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + transaction_id: f08966dc-4c7d-4152-9a15-1046798cc39c + amount: '146' + status: PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '144.54' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + status: ACTIVE + created_at: '2023-12-10T04:34:52.031Z' + updated_at: '2023-12-10T04:34:52.031Z' + - summary: Publish - (Genesis) Credit Entry + details: + - description: Detailed process of Market Place publishing the entry + mermaid: |- + sequenceDiagram + participant MARKET PLACE + participant API + participant CORD.JS + participant CONFIDEX + MARKET PLACE->>API: /publish + note over MARKET PLACE,API: Sign and send the rating entry + API->>MARKET PLACE: Ack + API->>CORD.JS: Signed entry + CORD.JS->>CORD.JS: Verify and transform entry + CORD.JS->>API: transformedEntry + API->>CORD.JS:Call Cord.Score.buildFromRatingProperties + note over API, CORD.JS: Input: transformedEntry + CORD.JS->>CONFIDEX: Call register_rating method + CONFIDEX->>CORD.JS: Extrinsic + CORD.JS->>API: Extrinsic + API->>CORD.JS: Cord.Score.dispatchRatingToChain + note over API,CORD.JS: Input: Extrinsic + CORD.JS->>CONFIDEX: Anchors the extrinsic to the chain + CONFIDEX->>CORD.JS: Rating Identifier + CORD.JS->>API: Rating Identifier + API->>MARKET PLACE: (/on_publish)Rating Identifier + MARKET PLACE->>API: ACK + - summary: Revise - Credit Entry + details: + - description: Detailed process of Market Place revising the entry + mermaid: |- + sequenceDiagram + participant MARKET PLACE + participant API + participant CORD.JS + participant CONFIDEX + MARKET PLACE ->> API: /revise + note over MARKET PLACE, API: Sign and send RatingEntry, Revised Entry + API->>MARKET PLACE: Ack + API->>CORD.JS: RatingEntry + CORD.JS->>CORD.JS: verify and transform entry + CORD.JS ->> API: transformedEntry + note over API,CORD.JS: Input: transformedEntry + API->>CORD.JS: Call Cord.Score.buildFromRevokeRatingProperties + CORD.JS->>CONFIDEX: Call revoke_rating method + CONFIDEX->>CORD.JS: Extrinsic + CORD.JS->>API: Extrinsic + API->>CORD.JS: Call Cord.Score.dispatchRevokeRatingToChain + note over API,CORD.JS: Input: Extrinsic + CORD.JS->>CONFIDEX: Anchors the extrinsic to the chain + CONFIDEX->>CORD.JS: Rating Identifier + CORD.JS->>API: Rating Identifier + API->>MARKET PLACE: Rating Identifier + + API->>CORD.JS: revisedEntry + CORD.JS->>CORD.JS: verify and transform entry + CORD.JS ->> API: transformedEntry + + API->>CORD.JS: Call Cord.Score.buildFromRatingProperties + note over API,CORD.JS: Input: transformedEntry + CORD.JS->>CONFIDEX: Call revise_rating method + CONFIDEX->>CORD.JS: Extrinsic + CORD.JS->>API: Extrinsic + API->>CORD.JS: Call Cord.Score.dispatchReviseRatingToChain + note over API,CORD.JS: Input: Extrinsic + CORD.JS->>CONFIDEX: Anchors the extrinsic to the chain + CONFIDEX->>CORD.JS: Rating Identifier + CORD.JS->>API: Rating Identifier + API->>MARKET PLACE: (/on_revise) Rating Identifier + MARKET PLACE->>API: ACK + - summary: Query + details: + - description: Detailed process of Market Place querying the entry + mermaid: |- + sequenceDiagram + participant MARKET PLACE + participant API + participant CORD.JS + participant CONFIDEX + MARKET PLACE->>API:/query + note over MARKET PLACE,API: Input: rating identifier, ScoreRatingTypeOf + API->>CORD.JS: Call Cord.Score.fetchFromChain() + CORD.JS->>CONFIDEX: Call api.query.score.aggregateScore() + CONFIDEX->>CORD.JS: Encoded score + CORD.JS->>CORD.JS: Decode the encoded score + CORD.JS->>API: Decoded Score + API->>MARKET PLACE: (/on_query) Decoded Score + MARKET PLACE->>API: ACK +x-examples: + on-demand: + summary: On Demand Use Case Specification + description: >- + The On-demand use case on the network would enable NPs to perform + on-demand ride hailing related transactions on the network. These APIs are + utilized by consumer and provider platforms enabling every consumer/ + end-user on all consumer platforms to consume the services/ inventory + provided by all provider platforms on the network seamlessly. Consumer + platforms shall use these specifications to perform transaction operations + like discovery, selection, booking, status check and others so as to + purchase services/ inventory on the network eg: autos, cabs etc. Provider + Platform shall use these specifications to expose their services/ + inventory in form of autos or cabs rides. Gateway specifications are used + to broadcast demands originating from a consumer platform to all + applicable provider platforms in a transparent and unbiased manner. + example_set: + search: + examples: + - *ref_15 + - summary: >- + Search for mobility services by pickup and drop location[Buyer + Collecting] + value: + context: + action: search + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 40963dc1-e402-4f4d-ae70-7c5864ca682c + timestamp: '2023-12-09T13:40:21.452Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + intent: + fulfillment: + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + payment: + collected_by: BAP + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT1D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: STATIC_TERMS + value: https://example-test-bap.com/static-terms.txt + select: + examples: + - *ref_17 + cancel: + examples: + - *ref_27 + - *ref_28 + confirm: + examples: + - *ref_21 + init: + examples: + - *ref_19 + on_cancel: + examples: + - *ref_29 + - *ref_26 + on_confirm: + examples: + - *ref_25 + - *ref_30 + - summary: Return confirmed order with latest fulfillment details + value: + context: + action: on_confirm + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-10T08:03:34.294Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ASSIGNED + stops: + - authorization: + token: '234234' + type: OTP + location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BAP + id: PA1 + params: + amount: '146' + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + currency: INR + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + virtual_payment_address: 9988199772@okicic + status: PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '144.54' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + status: ACTIVE + created_at: '2023-12-10T08:03:34.294Z' + updated_at: '2023-12-10T08:03:34.294Z' + on_init: + examples: + - *ref_20 + on_rating: + examples: + - summary: Return acknowledgement of rating and feedback + value: + context: + action: on_rating + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: >- + api.beckn.juspay.in/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 2a17e268-1dc4-4d1a-98a2-17554a50c7d2 + timestamp: '2023-03-23T05:41:15Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + feedback_ack: true + rating_ack: true + on_search: + examples: + - *ref_16 + - summary: Return a mobility catalog[Buyer Collecting] + value: + context: + action: on_search + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 21e54d3c-9c3b-47c1-aa3b-b0e7b20818ee + timestamp: '2023-12-09T13:41:16.161Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + catalog: + descriptor: + name: Mobility Servies BPP + providers: + - fulfillments: + - id: F1 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + - id: F2 + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + type: DELIVERY + vehicle: + category: CAB + id: P1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + - descriptor: + code: RIDE + name: CAB Economy Ride + fulfillment_ids: + - F2 + id: I2 + location_ids: + - L2 + - L4 + price: + currency: INR + maximum_value: '236' + minimum_value: '206' + value: '206' + locations: + - gps: 12.916468,77.608998 + id: L1 + - gps: 12.916714,77.609298 + id: L2 + - gps: 12.916573,77.615216 + id: L3 + - gps: 12.906857,77.604456 + id: L4 + payments: + - collected_by: BAP + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: >- + https://example-test-bpp.com/static-terms.txt + on_select: + examples: + - *ref_18 + on_status: + examples: + - *ref_31 + - summary: >- + Return order with latest fulfillment status - Driver en-route to + pickup + value: + context: + action: on_status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ENROUTE_PICKUP + name: Driver is en-route to your location + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '156' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BAP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: Delivery + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '2.5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '174' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: P200S + - summary: Return order with latest status - Ride started + value: + context: + action: on_status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_STARTED + name: Your ride has started + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '156' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BAP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: Delivery + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '2.5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '174' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: P200S + - summary: Return order with latest status - Ride Ended + value: + context: + action: on_status + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ENDED + name: Your ride has ended + stops: + - location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: CAB + make: Mahindra + model: Compact RE + registration: KA-01-AD-9876 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '156' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BAP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: SETTLEMENT_WINDOW + value: PT60M + - descriptor: + code: SETTLEMENT_BASIS + value: Delivery + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: DELAY_INTEREST + value: '2.5' + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '174' + type: PRE-ORDER + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: P200S + on_support: + examples: + - summary: Return support information related to an order + value: + context: + action: on_support + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: ec3dea8c-c64c-4f06-b2a0-ec1f9584d7ba + timestamp: '2023-03-23T05:41:09Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + support: + email: support@nammayatri.in + phone: '+918068870525' + url: https://support.nammayatri.com/gethelp + on_track: + examples: + - *ref_23 + on_update: + examples: + - *ref_32 + - summary: Return updated order with updated billing details + value: + context: + action: on_update + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-12-10T08:03:34.294Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + order: + billing: + email: jane.doe@example.com + name: Jane Doe + phone: +91-9897867564 + cancellation_terms: + - cancellation_fee: + percentage: '0' + fulfillment_state: + descriptor: + code: RIDE_ASSIGNED + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '30' + fulfillment_state: + descriptor: + code: RIDE_ENROUTE_PICKUP + reason_required: true + - cancellation_fee: + amount: + currency: INR + value: '50' + fulfillment_state: + descriptor: + code: RIDE_ARRIVED_PICKUP + reason_required: true + - cancellation_fee: + percentage: '100' + fulfillment_state: + descriptor: + code: RIDE_STARTED + reason_required: true + fulfillments: + - agent: + contact: + phone: '9856798567' + person: + name: Jason Roy + customer: + contact: + phone: '9876556789' + person: + name: Joe Adams + id: F1 + state: + descriptor: + code: RIDE_ASSIGNED + stops: + - authorization: + token: '234234' + type: OTP + location: + gps: 13.008935, 77.644408 + type: START + - location: + gps: 12.971186, 77.586812 + type: END + tags: + - descriptor: + code: ROUTE_INFO + name: Route Information + display: true + list: + - descriptor: + code: ENCODED_POLYLINE + name: Path + value: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + - descriptor: + code: WAYPOINTS + name: Waypoints + value: >- + [{"gps":"12.909982, + 77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982,77.611822"},{"gps":"12.909982, + 77.611822"}] + type: DELIVERY + vehicle: + category: AUTO_RICKSHAW + make: Bajaj + model: Compact RE + registration: KA-01-AD-9876 + id: O1 + items: + - descriptor: + code: RIDE + name: Auto Ride + fulfillment_ids: + - F1 + id: I1 + location_ids: + - L1 + - L3 + payment_ids: + - PA1 + price: + currency: INR + maximum_value: '176' + minimum_value: '136' + value: '146' + tags: + - descriptor: + code: FARE_POLICY + name: Daytime Charges + display: true + list: + - descriptor: + code: MIN_FARE + value: '30' + - descriptor: + code: MIN_FARE_DISTANCE_KM + value: '2' + - descriptor: + code: PER_KM_CHARGE + value: '15' + - descriptor: + code: PICKUP_CHARGE + value: '10' + - descriptor: + code: WAITING_CHARGE_PER_MIN + value: '2' + - descriptor: + code: NIGHT_CHARGE_MULTIPLIER + value: '1.5' + - descriptor: + code: NIGHT_SHIFT_START_TIME + value: '22:00:00' + - descriptor: + code: NIGHT_SHIFT_END_TIME + value: '05:00:00' + - descriptor: + code: INFO + name: General Information + display: true + list: + - descriptor: + code: DISTANCE_TO_NEAREST_DRIVER_METER + value: '661' + - descriptor: + code: ETA_TO_NEAREST_DRIVER_MIN + value: '3' + payments: + - collected_by: BPP + id: PA1 + params: + bank_account_number: xxxxxxxxxxxxxx + bank_code: XXXXXXXX + virtual_payment_address: 9988199772@okicic + status: NOT-PAID + tags: + - descriptor: + code: BUYER_FINDER_FEES + display: false + list: + - descriptor: + code: BUYER_FINDER_FEES_PERCENTAGE + value: '1' + - descriptor: + code: SETTLEMENT_TERMS + display: false + list: + - descriptor: + code: DELAY_INTEREST + value: '5' + - descriptor: + code: SETTLEMENT_TYPE + value: UPI + - descriptor: + code: SETTLEMENT_WINDOW + value: PT2D + - descriptor: + code: SETTLEMENT_BASIS + value: DELIVERY + - descriptor: + code: MANDATORY_ARBITRATION + value: 'true' + - descriptor: + code: COURT_JURISDICTION + value: New Delhi + - descriptor: + code: STATIC_TERMS + value: https://example-test-bpp.com/static-terms.txt + - descriptor: + code: SETTLEMENT_AMOUNT + value: '1.46' + type: ON-FULFILLMENT + provider: + id: P1 + quote: + breakup: + - price: + currency: INR + value: '30' + title: BASE_FARE + - price: + currency: INR + value: '116' + title: DISTANCE_FARE + price: + currency: INR + value: '146' + ttl: PT30S + status: ACTIVE + created_at: '2023-03-23T04:48:53Z' + updated_at: '2023-03-23T04:48:53Z' + - *ref_33 + rating: + examples: + - summary: Provide a rating + value: + context: + action: rating + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: b462a835-97d6-4479-bec8-9660a0f8513e + timestamp: '2023-03-23T04:46:45Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + id: b0462745-f6c9-4100-bbe7-4fa3648b6b40 + rating_category: DRIVER + value: 4 + - summary: Provide a rating with feedback form data + value: + context: + action: rating + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 849db48a-34c0-454b-86cb-60864482941b + timestamp: '2023-03-23T04:46:45Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + feedback_form: + - answer: >- + Driver took me on a route not shown by Google Maps and we + reached 10 minutes before time + id: '1' + id: b0462745-f6c9-4100-bbe7-4fa3648b6b40 + rating_category: DRIVER + value: 4 + status: + examples: + - *ref_24 + support: + examples: + - summary: Fetch support information related to a particular order + value: + context: + action: support + bap_id: example-bap.com + bap_uri: https://example-bap.com/prod/trv10 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/prod/seller + domain: ONDC:TRV10 + location: + city: + code: std:080 + country: + code: IND + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + timestamp: '2023-03-23T04:48:53Z' + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + ttl: PT30S + version: 2.0.0 + message: + ref_id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + track: + examples: + - *ref_22 +x-attributes: + on-demand: + attribute_set: + search: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: search + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + message: + intent: + fulfillment: + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + Describes the type of the stops during the fulfillment of + order + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 12.923608, 77.614629 + description: Describes the GPS co-ordinates of this location. + _description: + required: mandatory + type: object + owner: BAP + usage: '--' + description: Describe the location of the stop + _description: + required: mandatory + type: object + owner: BAP + usage: '--' + description: >- + The list of logical stops encountered during the fulfillment + of an order. + vehicle: + category: + required: optional + type: string + owner: BAP + usage: CAB + description: Describes the vehicle category. + _description: + required: optional + type: object + owner: BAP + usage: '--' + description: >- + Describes a vehicle is a device that is designed or used to + transport people or cargo over land, water, air, or through + space.
This has properties like category, capacity, make, + model, size,variant,color,energy_type,registration + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + payment: + collected_by: + required: mandatory + type: string + owner: BAP + usage: BPP + description: >- + This field indicates the payment collector. If set to 'bap,' + BAP collects first and settles with BPP. If BPP agrees, no + payment link is sent. If set to 'bpp,' BPP collects payment + directly. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: The terms of settlement for this order + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This helps the system to find out the purpose of the user behind + choosing any product or service. By using this intent the system + can align relevant options from available products or service. + on_search: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_search + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + catalog: + descriptor: + name: + required: mandatory + type: string + owner: BPP + usage: Mobility Servies BPP + description: Describes the catalog name. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the catalog's descriptor. + providers: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Describes the unique Id of the provider. + locations: + id: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: Indicates provider locations where this item is available. + gps: + required: optional + type: string + owner: BPP + usage: 28.707358, 77.180910 + description: Describes the GPS co-ordinates of this location. + _description: + required: optional + type: object + owner: BPP + usage: '--' + description: Describes the provider's locations. + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: >- + Describes the unique reference ID to the fulfillment of an + order + type: + required: mandatory + type: string + owner: BPP + usage: DELIVERY + description: >- + A code that describes the mode of fulfillment. This is + typically set when there are multiple ways an order can be + fulfilled. + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + Describes the type of the stops during the fulfillment of + order + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.707358, 77.180910 + description: Describes the GPS co-ordinates of this location. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BAP + usage: CAB + description: Describes the vehicle category. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the vehicle type. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: Describes the unique Id of the item. + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: CAB Economy Ride + description: Describes the unique code value of the item + name: + required: mandatory + type: string + owner: BPP + usage: RIDE + description: Describes the name value of the item + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the items description. + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency type of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + maximum_value: + required: optional + type: string + owner: BPP + usage: 176 + description: Describes a maximum value of price in decimal form + minimum_value: + required: optional + type: string + owner: BPP + usage: 50 + description: Describes a minimum value price in decimal form + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of an item. + location_ids: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: >- + Indicates the locations where this item is available from + providers. + fulfillment_ids: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Describes the Unique reference ID for order fulfillment. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + Describes a product or a service offered to the end consumer + by the provider. In the mobility sector, it can represent a + fare product like one way journey. In the logistics sector, + it can represent the delivery service offering. In the + retail domain it can represent a product like a grocery + item. + payments: + collected_by: + required: mandatory + type: string + owner: BAP + usage: BPP + description: 'This field indicates who is the collector of payment. ' + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes the terms of settlement between the BAP and the + BPP for a single transaction + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the provider's description. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the catalog's description. + select: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: select + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: Describes the unique Id of the item. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This decription refers to the comprehensive list of the + products or services selected and obtained within the + specified order. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Describes the unique Id of the provider. + _description: + required: mandatory + type: object + owner: BPP + usage: '--' + description: >- + This describes the complete formulated description of the loan + provider whose catalog items have been selected. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This refers to the complete description of the legal contract + created between the buyer and the seller. + on_select: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_select + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: Describes the unique Id of the item. + descriptor: + name: + required: mandatory + type: string + owner: BPP + usage: Auto Ride + description: Describes the item name. + code: + required: mandatory + type: string + owner: BPP + usage: RIDE + description: Describes the unique code value of the item + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the items description. + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency type of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + maximum_value: + required: optional + type: string + owner: BPP + usage: 176 + description: Describes a maximum value of price in decimal form + minimum_value: + required: optional + type: string + owner: BPP + usage: 50 + description: Describes a minimum value of price in decimal form + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of an item. + location_ids: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: Provider Locations this item is available in + fulfillment_ids: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + Describes a product or a service offered to the end consumer + by the provider. In the mobility sector, it can represent a + fare product like one way journey. In the logistics sector, it + can represent the delivery service offering. In the retail + domain it can represent a product like a grocery item. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Describes the unique Id of the provider. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the provider's description. + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + type: + required: optional + type: string + owner: BPP + usage: DELIVERY + description: >- + A code that describes the mode of fulfillment. This is + typically set when there are multiple ways an order can be + fulfilled. + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + Describes the type of the stops during the fulfillment of + order + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.686576, 77.441632 + description: Describes the GPS co-ordinates of this location. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BAP + usage: CAB + description: Describes the vehicle category. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the vehicle type. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + quote: + price: + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: This refers to the value of used currency of quoted price. + breakup: + title: + required: mandatory + type: string + owner: BPP + usage: Base Fare + description: Breakup title of the total quoted price + price: + value: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the price of a product or service + currency: + required: mandatory + type: string + owner: BPP + usage: 120 + description: >- + Describes the currency to be paid in of a product or + service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the breakup price + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This attribute describes the breakup of the total quoted + price. + ttl: + required: optional + type: string + owner: BPP + usage: P200s + description: Time to live in seconds for an instance of this schema + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This refers to the complete description of the mutually agreed + upon quotation for this order. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the order description. + init: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: init + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: Describes the unique Id of the item. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This decription refers to the comprehensive list of the + products or services selected and obtained within the + specified order. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Id of the provider + _description: + required: mandatory + type: object + owner: BPP + usage: '--' + description: >- + This describes the complete formulated description of the loan + provider whose catalog items have been selected. + billing: + name: + required: mandatory + type: string + owner: BAP + usage: John Doe + description: Name of the billable entity + _description: + required: mandatory + type: object + owner: BAP + usage: '--' + description: The billing details of this order + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + customer: + person: + name: + required: mandatory + type: string + owner: BAP + usage: Jason Roy + description: Name of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes contact of end-customer + contact: + phone: + required: mandatory + type: string + owner: BAP + usage: 9898657512 + description: Contact number of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes contact of end-customer + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + The type of stop. Allowed values of this property can be + defined by the network policy. + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.707358, 77.180910 + description: The GPS co-ordinates of this location. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BAP + usage: CAB + description: Describes vehicle category + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the vehicle type. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + payments: + collected_by: + required: mandatory + type: string + owner: BAP + usage: BAP + description: 'This field indicates who is the collector of payment. ' + status: + required: mandatory + type: string + owner: BAP + usage: NOT-PAID + description: Payment status + type: + required: mandatory + type: string + owner: BAP + usage: PRE-ORDER + description: Payment Type + params: + bank_code: + required: optional + type: string + owner: BAP + usage: XXXXXXXX + description: Bank code associated with payment activity + bank_account_number: + required: optional + type: string + owner: BAP + usage: xxxxxxxxxxxxxx + description: Bank account number associated with payment activity + virtual_payment_address: + required: optional + type: string + owner: BAP + usage: 9988199772@okicic + description: Virtual payment address associated with payment activity + _description: + required: mandatory + type: object + owner: BAP + usage: '--' + description: This attribute defines the payment params for this order. + _description: + required: mandatory + type: object + owner: BAP/BPP + usage: '--' + description: The terms of settlement for this order + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + This refers to the complete description of the legal contract + created between the buyer and the seller. + on_init: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_init + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145-4ea3-45fe-ab3d-7bcf6b9f456b + description: Describes the unique Id of the item. + descriptor: + name: + required: mandatory + type: string + owner: BPP + usage: Auto Ride + description: Describes the item name. + code: + required: mandatory + type: string + owner: BPP + usage: RIDE + description: Describes the unique code value of the item + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the items description. + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the price of selected item. + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + maximum_value: + required: optional + type: string + owner: BPP + usage: 176 + description: Describes a maximum value of price in decimal form + minimum_value: + required: optional + type: string + owner: BPP + usage: 50 + description: Describes a minimum value of price in decimal form + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of an item. + location_ids: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: >- + Indicates the locations where this item is available from + providers. + fulfillment_ids: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + payment_ids: + required: mandatory + type: string + owner: BPP + usage: bc08edb1 + description: Unique reference ID to the payment of an order + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + Describes a product or a service offered to the end consumer + by the provider. In the mobility sector, it can represent a + fare product like one way journey. In the logistics sector, it + can represent the delivery service offering. In the retail + domain it can represent a product like a grocery item. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Describes the unqiue Id of the provider + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the provider's description. + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + type: + required: mandatory + type: string + owner: BPP + usage: DELIVERY + description: A code that describes the mode of fulfillment. + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + The type of stop. Allowed values of this property can be + defined by the network policy. + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.686576, 77.441632 + description: Describes the GPS co-ordinates of this location. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BAP + usage: CAB + description: Describes the vehicle category. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the vehicle type. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + customer: + person: + name: + required: mandatory + type: string + owner: BAP + usage: Jason Roy + description: Describes the name of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer details. + contact: + phone: + required: mandatory + type: string + owner: BAP + usage: 9898657512 + description: Describes the contact number of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer contact details. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer. + quote: + price: + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: This refers to the value of used currency of quoted price. + breakup: + title: + required: mandatory + type: string + owner: BPP + usage: Base Fare + description: Breakup title of the total quoted price + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: >- + Describes the currency to be paid in of a product or + service + value: + required: mandatory + type: string + owner: BPP + usage: 120 + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the breakup price + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This attribute describes the breakup of the total quoted + price. + ttl: + required: optional + type: string + owner: BPP + usage: P200s + description: Time to live in seconds for an instance of this schema + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This refers to the complete description of the mutually agreed + upon quotation for this order. + payments: + id: + required: mandatory + type: string + owner: BPP + usage: bc08edb1 + description: >- + Describes the ID of the payment term that can be referred at + an item or an order level in a catalog + collected_by: + required: mandatory + type: string + owner: BAP + usage: BAP + description: 'This field indicates who is the collector of payment. ' + status: + required: mandatory + type: string + owner: BAP + usage: NOT-PAID + description: Describe the payment Status for particular order + type: + required: mandatory + type: string + owner: BAP + usage: PRE-ORDER + description: Describe the payment type for particular order + params: + bank_code: + required: mandatory + type: string + owner: BPP + usage: XXXXXXXX + description: Bank code associated with payment activity + bank_account_number: + required: mandatory + type: string + owner: BPP + usage: xxxxxxxxxxxxxx + description: Bank account number associated with payment activity + virtual_payment_address: + required: mandatory + type: string + owner: BPP + usage: 9988199772@okicic + description: Virtual payment address associated with payment activity + _description: + required: mandatory + type: object + owner: BAP + usage: '--' + description: This attribute defines the payment params for this order. + _description: + required: mandatory + type: object + owner: BAP/BPP + usage: '--' + description: The terms of settlement for this order + cancellation_terms: + fulfillment_state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: RIDE_ENROUTE_PICKUP + description: Describes the unique code for the cancellation terms + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + reason_required: + required: mandatory + type: string + owner: BPP + usage: true + description: Indicates whether a reason is required to cancel the order + cancellation_fee: + percentage: + required: optional + type: string + owner: BPP + usage: 2 + description: Describes the percentage value for cancellation fee + amount: + currency: + required: optional + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + value: + required: optional + type: string + owner: BPP + usage: 30 + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the unique code for the cancellation terms + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the order description. + id: + required: optional + type: string + owner: BPP + usage: ec08edb2 + description: Describes the unqiue order ID. + confirm: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: confirm + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: Describes the unique Id of the item. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This decription refers to the comprehensive list of the + products or services selected and obtained within the + specified order. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Describes the uique Id of the provider. + _description: + required: mandatory + type: object + owner: BPP + usage: '--' + description: >- + This describes the complete formulated description of the loan + provider whose catalog items have been selected. + billing: + name: + required: mandatory + type: string + owner: BAP + usage: John Doe + description: Describes the Name of the billable entity + _description: + required: mandatory + type: object + owner: BAP + usage: '--' + description: The billing details of this order + payments: + id: + required: mandatory + type: string + owner: BAP + usage: bc08edb1 + description: >- + ID of the payment term that can be referred at an item or an + order level in a catalog + collected_by: + required: mandatory + type: string + owner: BAP + usage: BAP + description: 'This field indicates who is the collector of payment. ' + status: + required: mandatory + type: string + owner: BAP + usage: NOT-PAID + description: Describe the payment Status for particular order + type: + required: mandatory + type: string + owner: BAP + usage: PRE-ORDER + description: Describe the payment type for particular order + params: + bank_code: + required: mandatory + type: string + owner: BPP + usage: XXXXXXXX + description: Bank code associated with payment activity + bank_account_number: + required: mandatory + type: string + owner: BPP + usage: xxxxxxxxxxxxxx + description: Bank account number associated with payment activity + virtual_payment_address: + required: mandatory + type: string + owner: BPP + usage: 9988199772@okicic + description: Virtual payment address associated with payment activity + transaction_id: + required: optional + type: string + owner: BPP + usage: cda41144 + description: Describes transaction ID associated with payment activity + _description: + required: mandatory + type: object + owner: BAP + usage: '--' + description: This attribute defines the payment params for this order. + _description: + required: mandatory + type: object + owner: BAP/BPP + usage: '--' + description: The terms of settlement for this order + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + customer: + person: + name: + required: mandatory + type: string + owner: BAP + usage: Jason Roy + description: Describe the name of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes contact of end-customer + contact: + phone: + required: mandatory + type: string + owner: BAP + usage: 9898657512 + description: Describe the contact number of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes contact of end-customer + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + Describes the type of the stops during the fulfillment of + order + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.686576, 77.441632 + description: The GPS co-ordinates of this location. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BAP + usage: CAB + description: Describes vehicle category + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the vehicle type. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + This refers to the complete description of the legal contract + created between the buyer and the seller. + id: + required: optional + type: string + owner: BPP + usage: ec08edb2 + description: Describes the unqiue order ID. + on_confirm: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_confirm + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: Describes the unique Id of the item. + descriptor: + name: + required: mandatory + type: string + owner: BPP + usage: Single Journey Ticket + description: Describes the item name. + code: + required: mandatory + type: string + owner: BPP + usage: SJT + description: Describes the unique code value of the item + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the items description. + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: >- + Describes the currency type to be paid in of a product or + service + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + maximum_value: + required: optional + type: string + owner: BPP + usage: 176 + description: Describes a maximum value in decimal form + minimum_value: + required: optional + type: string + owner: BPP + usage: 50 + description: Describes a minimum value in decimal form + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of an item. + location_ids: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: >- + Indicates the locations where this item is available from + providers. + fulfillment_ids: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + payment_ids: + required: mandatory + type: string + owner: BPP + usage: P1 + description: Unique reference ID to the payment of an order + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + Describes a product or a service offered to the end consumer + by the provider. In the mobility sector, it can represent a + fare product like one way journey. In the logistics sector, it + can represent the delivery service offering. In the retail + domain it can represent a product like a grocery item. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Unique reference ID to the payment of an order + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the provider's description. + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + type: + required: mandatory + type: string + owner: BPP + usage: P1 + description: Unique reference ID to the payment of an order + customer: + person: + name: + required: mandatory + type: string + owner: BAP + usage: Jason Roy + description: Describes the name of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer details. + contact: + phone: + required: mandatory + type: string + owner: BAP + usage: 9898657512 + description: Describes the contact number of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer contact details. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer. + agent: + person: + name: + required: optional + type: string + owner: BPP + usage: John Doe + description: Describes the name of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent details. + contact: + phone: + required: optional + type: string + owner: BPP + usage: 7845981268 + description: Describes the contact number of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent contact details. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent. + state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: RIDE_ASSIGNED + description: Describes the state's code for fulfillment. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the fulfillments description. + stops: + type: + required: mandatory + type: string + owner: BAP + usage: INTERMEDIATE_STOP + description: >- + The type of stop. Allowed values of this property can be + defined by the network policy. + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.707358, 77.180910 + description: The GPS co-ordinates of this location. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + authorization: + type: + required: optional + type: string + owner: BPP + usage: OTP + description: >- + Type of authorization mechanism used. The allowed values + for this field can be published as part of the network + policy. + token: + required: optional + type: string + owner: BPP + usage: 232312 + description: >- + Token used for authorization. This is typically generated + at the BPP. The BAP can send this value to the user via + any channel that it uses to authenticate the user like + SMS, Email, Push notification, or in-app rendering. + _description: + required: optional + type: object + owner: BPP + usage: '--' + description: Describes the authorization for a fulfillments stop. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BAP + usage: AUTO_RICKSHAW + description: Describes vehicle category + make: + required: mandatory + type: string + owner: BPP + usage: Bajaj + description: Describes vehicle manufacturer + model: + required: mandatory + type: string + owner: BPP + usage: compact-re + description: Describes vehicle model + registration: + required: mandatory + type: string + owner: BPP + usage: HR-20AS-4578 + description: Describes vehicle registration details + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the vehicle type. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + quote: + price: + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: This refers to the value of used currency of quoted price. + breakup: + title: + required: mandatory + type: string + owner: BPP + usage: Base Fare + description: Breakup title of the total quoted price + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the price of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 120 + description: >- + Describes the currency to be paid in of a product or + service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the breakup price + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This attribute describes the breakup of the total quoted + price. + ttl: + required: optional + type: string + owner: BPP + usage: P200s + description: Time to live in seconds for an instance of this schema + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This refers to the complete description of the mutually agreed + upon quotation for this order. + payments: + id: + required: mandatory + type: string + owner: BPP + usage: bc08edb1 + description: >- + Describes the ID of the payment term that can be referred at + an item or an order level in a catalog + collected_by: + required: mandatory + type: string + owner: BAP + usage: BAP + description: 'This field indicates who is the collector of payment. ' + status: + required: mandatory + type: string + owner: BAP + usage: NOT-PAID + description: Describe the Payment Status + type: + required: mandatory + type: string + owner: BAP + usage: PRE-ORDER + description: Describe the Payment type + params: + bank_code: + required: mandatory + type: string + owner: BPP + usage: XXXXXXXX + description: Bank code associated with payment activity + bank_account_number: + required: mandatory + type: string + owner: BPP + usage: xxxxxxxxxxxxxx + description: Bank account number associated with payment activity + virtual_payment_address: + required: mandatory + type: string + owner: BPP + usage: 9988199772@okicic + description: Virtual payment address associated with payment activity + amount: + required: optional + type: string + owner: BPP + usage: 146 + description: Describes the amount associated with the payment transaction + currency: + required: optional + type: string + owner: BPP + usage: INR + description: >- + Describes the currency associated with the payment + transaction + transaction_id: + required: optional + type: string + owner: BPP + usage: cda41144 + description: Describes transaction ID associated with payment activity + cancellation_terms: + fulfillment_state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: RIDE_ENROUTE_PICKUP + description: Describes the unique code for the cancellation terms. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + reason_required: + required: mandatory + type: string + owner: BPP + usage: true + description: Indicates whether a reason is required to cancel the order + cancellation_fee: + percentage: + required: optional + type: string + owner: BPP + usage: 2 + description: Describes the percentage value for cancellation fee + amount: + currency: + required: optional + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + value: + required: optional + type: string + owner: BPP + usage: 30 + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the unique code for the cancellation terms + status: + required: mandatory + type: string + owner: BPP + usage: ACTIVE + description: Describes the order status. + created_at: + required: mandatory + type: string + owner: BPP + usage: '2023-12-10T08:03:34.294Z' + description: Describes the date-time of creation of this order + updated_at: + required: mandatory + type: string + owner: BPP + usage: '2023-12-10T08:03:34.294Z' + description: Describes The date-time of updated of this order + id: + required: mandatory + type: string + owner: BPP + usage: ec08edb2 + description: Describes the unqiue order ID. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the order description. + cancel: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: cancel + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order_id: + required: mandatory + type: string + owner: BPP + usage: 60253df1 + description: 'Describes the unique ID of the order. ' + cancellation_reason_id: + required: mandatory + type: string + owner: BAP + usage: 45dd6fd3 + description: Describes the reason Id for cancellation + descriptor: + short_desc: + required: optional + type: string + owner: BAP + usage: Accidantaly book the ride + description: Describes the Short description for cancellaion + name: + required: optional + type: string + owner: BAP + usage: Ride Cancellation + description: Describes the name for cancellaion + code: + required: mandatory + type: string + owner: BAP + usage: SOFT_CANCEL + description: Describes the code for cancellaion + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This include the details about the distinctive features, + benefits, or unique aspects of the products or service that has + been offered to the end customer. + on_cancel: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_cancel + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: 'Describes the unique ID of the order. ' + descriptor: + name: + required: mandatory + type: string + owner: BPP + usage: Auto Ride + description: Describes the item name. + code: + required: mandatory + type: string + owner: BPP + usage: RIDE + description: Describes the unique code value of the item + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the items description. + fulfillment_ids: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: >- + Describes the unique reference ID to the fulfillment of an + order + payment_ids: + required: mandatory + type: string + owner: BPP + usage: bc08edb1 + description: Describes the unique reference ID to the payment of an order + location_ids: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: Provider Locations this item is available in + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: >- + Describes the currency type to be paid in of a product or + service + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + maximum_value: + required: optional + type: string + owner: BPP + usage: 176 + description: Describes a maximum value in decimal form + minimum_value: + required: optional + type: string + owner: BPP + usage: 50 + description: Describes a minimum value in decimal form + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of an item. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + Describes a product or a service offered to the end consumer + by the provider. In the mobility sector, it can represent a + fare product like one way journey. In the logistics sector, it + can represent the delivery service offering. In the retail + domain it can represent a product like a grocery item. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: 'Describes the unique ID of the provider. ' + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the provider's description. + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + The type of stop. Allowed values of this property can be + defined by the network policy. + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.686576, 77.441632 + description: Describes a GPS coordinate + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + authorization: + type: + required: optional + type: string + owner: BPP + usage: OTP + description: >- + Type of authorization mechanism used. The allowed values + for this field can be published as part of the network + policy. + token: + required: optional + type: string + owner: BPP + usage: 232312 + description: >- + Token used for authorization. This is typically generated + at the BPP. The BAP can send this value to the user via + any channel that it uses to authenticate the user like + SMS, Email, Push notification, or in-app rendering. + time: + duration: + required: optional + type: string + owner: BPP + usage: PT2H + description: Describes the duration. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the fulfillments stops. + customer: + person: + name: + required: mandatory + type: string + owner: BAP + usage: Jason Roy + description: Name of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer details. + contact: + phone: + required: mandatory + type: string + owner: BAP + usage: 9898657512 + description: Contact number of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer contact details. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer. + agent: + person: + name: + required: mandatory + type: string + owner: BPP + usage: John Doe + description: Name of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent details. + contact: + phone: + required: mandatory + type: string + owner: BPP + usage: 7845981268 + description: Contact number of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent contact details. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent. + vehicle: + registration: + required: mandatory + type: string + owner: BPP + usage: HR-20AS-4578 + description: Describes vehicle registration details + category: + required: mandatory + type: string + owner: BAP + usage: AUTO_RICKSHAW + description: Describes vehicle category + make: + required: mandatory + type: string + owner: BPP + usage: Bajaj + description: Describes vehicle manufacturer + model: + required: mandatory + type: string + owner: BPP + usage: compact-re + description: Describes vehicle model + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the vehicle type. + state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: DRIVER_ENROUTE + description: Describes the state's code for fulfillment. + name: + required: optional + type: string + owner: BPP + usage: Driver is on the way + description: Describes the current state + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the fulfillments description. + type: + required: mandatory + type: string + owner: BPP + usage: P1 + description: Unique reference ID to the payment of an order + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + quote: + price: + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency type of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: This refers to the value of used currency of quoted price. + breakup: + title: + required: mandatory + type: string + owner: BPP + usage: Base Fare + description: Describes the Breakup title of the total quoted price + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the price of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 120 + description: Describes the currency type of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the breakup price + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This attribute describes the breakup of the total quoted + price. + ttl: + required: optional + type: string + owner: BPP + usage: P200s + description: Time to live in seconds for an instance of this schema + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This refers to the complete description of the mutually agreed + upon quotation for this order. + payments: + id: + required: mandatory + type: string + owner: BPP + usage: bc08edb1 + description: >- + ID of the payment term that can be referred at an item or an + order level in a catalog + type: + required: mandatory + type: string + owner: BAP + usage: PRE-ORDER + description: Describe the Payment type + params: + currency: + required: optional + type: string + owner: BPP + usage: INR + description: Describes currency value in string form + amount: + required: optional + type: string + owner: BPP + usage: 60 + description: Describes a numerical value in decimal form + bank_code: + required: mandatory + type: string + owner: BPP + usage: XXXXXXXX + description: Bank code associated with payment activity + bank_account_number: + required: mandatory + type: string + owner: BPP + usage: xxxxxxxxxxxxxx + description: Bank account number associated with payment activity + bank_account_name: + required: optional + type: string + owner: BPP + usage: Raghvinder J + description: Describes the Bank account holder name + virtual_payment_address: + required: optional + type: string + owner: BPP + usage: 9988199772@okicic + description: Virtual payment address associated with payment activity + time: + duration: + required: optional + type: string + owner: BPP + usage: P1D + description: Describes time transaction duration + collected_by: + required: mandatory + type: string + owner: BAP + usage: BAP + description: 'This field indicates who is the collector of payment. ' + status: + required: mandatory + type: string + owner: BAP + usage: NOT-PAID + description: Describe the Payment Status + cancellation_terms: + fulfillment_state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: RIDE_ENROUTE_PICKUP + description: Describes the unique code for the cancellation terms. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + reason_required: + required: mandatory + type: string + owner: BPP + usage: true + description: Indicates whether a reason is required to cancel the order + cancellation_fee: + percentage: + required: optional + type: string + owner: BPP + usage: 2 + description: Describes the percentage value for cancellation fee + amount: + currency: + required: optional + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + value: + required: optional + type: string + owner: BPP + usage: 30 + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the unique code for the cancellation terms + id: + required: mandatory + type: string + owner: BPP + usage: ec08edb2 + description: Describes the unqiue order ID. + status: + required: mandatory + type: string + owner: BPP + usage: SOFT_CANCEL + description: Describes the order status. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the order description. + status: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: status + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order_id: + required: optional + type: string + owner: BPP + usage: 60253df1 + description: 'Describes the unique ID of the order. ' + ref_id: + required: optional + type: string + owner: BPP + usage: 60253df1 + description: >- + Describes unique id for reference, pre-order this will be + transaction ID. + on_status: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_status + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: 'Describes the unique ID of the item. ' + descriptor: + name: + required: mandatory + type: string + owner: BPP + usage: Auto Ride + description: Describes the item name. + code: + required: mandatory + type: string + owner: BPP + usage: RIDE + description: Describes the item code. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the items description. + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency type of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes a numerical value in decimal form + maximum_value: + required: optional + type: string + owner: BPP + usage: 176 + description: Describes a maximum value in decimal form + minimum_value: + required: optional + type: string + owner: BPP + usage: 50 + description: Describes a minimum value in decimal form + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of an item. + location_ids: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: Provider Locations this item is available in + fulfillment_ids: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + payment_ids: + required: mandatory + type: string + owner: BPP + usage: bc08edb1 + description: Unique reference ID to the payment of an order + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + Describes a product or a service offered to the end consumer + by the provider. In the mobility sector, it can represent a + fare product like one way journey. In the logistics sector, it + can represent the delivery service offering. In the retail + domain it can represent a product like a grocery item. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Id of the provider + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the provider's description. + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + stops: + type: + required: mandatory + type: string + owner: BPP + usage: START + description: >- + The type of stop. Allowed values of this property can be + defined by the network policy. + location: + gps: + required: mandatory + type: string + owner: BPP + usage: 28.686576, 77.441632 + description: Describes a GPS coordinate + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the location of stops. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BPP + usage: CAB + description: Describes vehicle category + make: + required: optional + type: string + owner: BPP + usage: Bajaj + description: Describes vehicle manufacturer + model: + required: optional + type: string + owner: BPP + usage: compact-re + description: Describes vehicle model + registration: + required: mandatory + type: string + owner: BPP + usage: HR-20AS-4578 + description: Describes vehicle registration details + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the vehicle type. + customer: + person: + name: + required: mandatory + type: string + owner: BPP + usage: Jason Roy + description: Name of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer details. + contact: + phone: + required: mandatory + type: string + owner: BPP + usage: 9898657512 + description: Contact number of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer contact details. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer. + agent: + person: + name: + required: mandatory + type: string + owner: BPP + usage: John Doe + description: Name of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent details. + contact: + phone: + required: mandatory + type: string + owner: BPP + usage: 7845981268 + description: Contact number of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent contact details. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent. + type: + required: mandatory + type: string + owner: BPP + usage: Delivery + description: Describes type of fullfilment + state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: DRIVER_ENROUTE + description: Describes the state's code for fulfillment. + name: + required: optional + type: string + owner: BPP + usage: Driver is on the way + description: Describes the current state + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the fulfillments description. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + quote: + price: + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: This refers to the value of used currency of quoted price. + breakup: + title: + required: mandatory + type: string + owner: BPP + usage: Base Fare + description: Breakup title of the total quoted price + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the price of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 120 + description: >- + Describes the currency to be paid in of a product or + service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the breakup price + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This attribute describes the breakup of the total quoted + price. + ttl: + required: optional + type: string + owner: BPP + usage: P200s + description: Time to live in seconds for an instance of this schema + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This refers to the complete description of the mutually agreed + upon quotation for this order. + payments: + id: + required: mandatory + type: string + owner: BPP + usage: PA1 + description: >- + ID of the payment term that can be referred at an item or an + order level in a catalog + collected_by: + required: mandatory + type: string + owner: BAP + usage: BAP + description: 'This field indicates who is the collector of payment. ' + status: + required: mandatory + type: string + owner: BAP + usage: NOT-PAID + description: Payment Status + type: + required: mandatory + type: string + owner: BAP + usage: PRE-ORDER + description: Payment type + params: + bank_code: + required: mandatory + type: string + owner: BPP + usage: XXXXXXXX + description: Bank code associated with payment activity + bank_account_number: + required: mandatory + type: string + owner: BPP + usage: xxxxxxxxxxxxxx + description: Bank account number associated with payment activity + virtual_payment_address: + required: mandatory + type: string + owner: BPP + usage: 9988199772@okicic + description: Virtual payment address associated with payment activity + transaction_id: + required: optional + type: string + owner: BPP + usage: cda41144 + description: Describes transaction ID associated with payment activity + amount: + required: optional + type: string + owner: BPP + usage: 146 + description: Describes the amount associated with the payment transaction + currency: + required: optional + type: string + owner: BPP + usage: INR + description: >- + Describes the currency associated with the payment + transaction + cancellation_terms: + fulfillment_state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: RIDE_ENROUTE_PICKUP + description: Describes the unique code for the cancellation terms. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + reason_required: + required: mandatory + type: string + owner: BPP + usage: true + description: Indicates whether a reason is required to cancel the order + cancellation_fee: + percentage: + required: optional + type: string + owner: BPP + usage: 2 + description: Describes the percentage value for cancellation fee + amount: + currency: + required: optional + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + value: + required: optional + type: string + owner: BPP + usage: 30 + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the unique code for the cancellation terms + status: + required: optional + type: string + owner: BPP + usage: ACTIVE + description: Describes the order status. + created_at: + required: optional + type: string + owner: BPP + usage: '2023-12-10T08:03:34.294Z' + description: Describes the date-time of creation of this order + updated_at: + required: optional + type: string + owner: BPP + usage: '2023-12-10T08:03:34.294Z' + description: Describes The date-time of updated of this order + id: + required: optional + type: string + owner: BPP + usage: ec08edb2 + description: Describes the unqiue order ID. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the order description. + update: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_status + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + id: + required: mandatory + type: string + owner: BPP + usage: 1 + description: Describes the unique order id + fulfillments: + customer: + person: + name: + required: optional + type: string + owner: BAP + usage: John Adam + description: Name of the customer + _description: + required: optional + type: object + owner: BAP/BPP + usage: '--' + description: Name of the customer + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the unique order id + on_update: + context: + location: + country: + code: + required: mandatory + type: string + owner: BAP + usage: IND + description: Describes country code as per ISO 3166-1 and ISO 3166-2 format + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the country of location where the + transaction is meant to be completed. + city: + code: + required: mandatory + type: string + owner: BAP + usage: std:080 + description: Describes the city code this location is, or is located within + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the city of location where the + transaction is meant to be completed. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: >- + This attribute defines the location where the transaction is + meant to be completed. + domain: + required: mandatory + type: string + owner: BAP + usage: ONDC:TRV10 + description: Describes domain code that is relevant to this transaction context + timestamp: + required: mandatory + type: string + owner: BAP + usage: '2023-03-23T04:41:16Z' + description: Describes tme of request generation in RFC3339 format + bap_id: + required: mandatory + type: string + owner: BAP + usage: api.example-bap.com + description: Describes subscriber ID of the BAP + transaction_id: + required: mandatory + type: string + owner: BAP + usage: 6743e9e2 + description: Describes a unique value which persists across all API calls + message_id: + required: mandatory + type: string + owner: BAP + usage: 13ba8018f176 + description: >- + Describes a unique value which persists during a request / + callback cycle. + version: + required: mandatory + type: integer + owner: BAP + usage: 2.0.0 + description: >- + Describes the version of transaction protocol being used by the + sender. + action: + required: mandatory + type: string + owner: BAP + usage: on_update + description: >- + Describes the Beckn protocol method being called by the sender and + executed at the receiver. + bap_uri: + required: mandatory + type: string + owner: BAP + usage: https://api.example-bap.com/pilot/bap/cab/v1 + description: >- + Describes subscriber URL of the BAP for accepting callbacks from + BPPs. + ttl: + required: mandatory + type: string + owner: BAP + usage: PT30S + description: >- + Describes the duration in ISO8601 format after timestamp for which + this message holds valid + bpp_id: + required: mandatory + type: string + owner: BPP + usage: api.example-bpp.com + description: Describes subscriber ID of the BPP + bpp_uri: + required: mandatory + type: string + owner: BPP + usage: >- + https://api.example-bpp.com/dobpp/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + description: Describes subscriber URL of the BPP for accepting calls from BAPs. + message: + order: + items: + id: + required: mandatory + type: string + owner: BPP + usage: ecf4d145 + description: 'Describes the unique ID of the item. ' + descriptor: + name: + required: mandatory + type: string + owner: BPP + usage: Auto Ride + description: 'Describes the item name. ' + code: + required: mandatory + type: string + owner: BPP + usage: RIDE + description: 'Describes the item code. ' + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the items description. + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency type of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes a numerical value in decimal form + maximum_value: + required: optional + type: string + owner: BPP + usage: 176 + description: Describes a maximum value in decimal form + minimum_value: + required: optional + type: string + owner: BPP + usage: 50 + description: Describes a minimum value in decimal form + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of an item. + location_ids: + required: optional + type: string + owner: BPP + usage: d3ebf05b + description: Provider Locations this item is available in + fulfillment_ids: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + payment_ids: + required: mandatory + type: string + owner: BPP + usage: bc08edb1 + description: Unique reference ID to the payment of an order + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + Describes a product or a service offered to the end consumer + by the provider. In the mobility sector, it can represent a + fare product like one way journey. In the logistics sector, it + can represent the delivery service offering. In the retail + domain it can represent a product like a grocery item. + provider: + id: + required: mandatory + type: string + owner: BPP + usage: 450dec0f + description: Id of the provider + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the provider's description. + fulfillments: + id: + required: mandatory + type: string + owner: BPP + usage: b68bb35b + description: Unique reference ID to the fulfillment of an order + stops: + type: + required: mandatory + type: string + owner: BAP + usage: START + description: >- + The type of stop. Allowed values of this property can be + defined by the network policy. + location: + gps: + required: mandatory + type: string + owner: BAP + usage: 28.686576, 77.441632 + description: Describes a GPS coordinate + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the location of stops. + authorization: + type: + required: optional + type: string + owner: BPP + usage: OTP + description: >- + Type of authorization mechanism used. The allowed values + for this field can be published as part of the network + policy. + token: + required: optional + type: string + owner: BPP + usage: 232312 + description: >- + Token used for authorization. This is typically generated + at the BPP. The BAP can send this value to the user via + any channel that it uses to authenticate the user like + SMS, Email, Push notification, or in-app rendering. + _description: + required: optional + type: object + owner: BPP + usage: '--' + description: Describes the authorization for a fulfillments stop. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the fulfillments stops. + vehicle: + category: + required: mandatory + type: string + owner: BAP + usage: CAB + description: Describes vehicle category + make: + required: optional + type: string + owner: BPP + usage: Bajaj + description: Describes vehicle manufacturer + model: + required: optional + type: string + owner: BPP + usage: compact-re + description: Describes vehicle model + registration: + required: mandatory + type: string + owner: BPP + usage: HR-20AS-4578 + description: Describes vehicle registration details + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the vehicle type. + customer: + person: + name: + required: mandatory + type: string + owner: BAP + usage: John Adam + description: Name of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer details. + contact: + phone: + required: mandatory + type: string + owner: BAP + usage: 9898657512 + description: Contact number of the customer + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer contact details. + _description: + required: Mandatory + type: object + owner: BAP + usage: '--' + description: Describes the customer. + agent: + person: + name: + required: mandatory + type: string + owner: BPP + usage: John Doe + description: Name of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent details. + contact: + phone: + required: mandatory + type: string + owner: BPP + usage: 7845981268 + description: Contact number of the agent + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent contact details. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the agent. + type: + required: mandatory + type: string + owner: BPP + usage: Delivery + description: Describes type of fullfilment + state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: DRIVER_ENROUTE + description: Describes the state's code for fulfillment. + name: + required: optional + type: string + owner: BPP + usage: Driver is on the way + description: Describes the current state + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the fulfillments description. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: >- + Describes how a an order will be rendered/fulfilled to the + end-customer + quote: + price: + value: + required: mandatory + type: string + owner: BPP + usage: 60 + description: Describes the price of a product or service + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: This refers to the value of used currency of quoted price. + breakup: + title: + required: mandatory + type: string + owner: BPP + usage: Base Fare + description: Breakup title of the total quoted price + price: + currency: + required: mandatory + type: string + owner: BPP + usage: INR + description: Describes the price of a product or service + value: + required: mandatory + type: string + owner: BPP + usage: 120 + description: >- + Describes the currency to be paid in of a product or + service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the breakup price + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This attribute describes the breakup of the total quoted + price. + ttl: + required: optional + type: string + owner: BPP + usage: P200s + description: Time to live in seconds for an instance of this schema + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: >- + This refers to the complete description of the mutually agreed + upon quotation for this order. + payments: + id: + required: mandatory + type: string + owner: BPP + usage: PA1 + description: >- + ID of the payment term that can be referred at an item or an + order level in a catalog + collected_by: + required: mandatory + type: string + owner: BAP + usage: BAP + description: 'This field indicates who is the collector of payment. ' + status: + required: mandatory + type: string + owner: BAP + usage: NOT-PAID + description: Payment Status + type: + required: mandatory + type: string + owner: BAP + usage: PRE-ORDER + description: Payment type + params: + bank_code: + required: mandatory + type: string + owner: BPP + usage: XXXXXXXX + description: Bank code associated with payment activity + bank_account_number: + required: mandatory + type: string + owner: BPP + usage: xxxxxxxxxxxxxx + description: Bank account number associated with payment activity + virtual_payment_address: + required: mandatory + type: string + owner: BPP + usage: 9988199772@okicic + description: Virtual payment address associated with payment activity + cancellation_terms: + fulfillment_state: + descriptor: + code: + required: mandatory + type: string + owner: BPP + usage: RIDE_ENROUTE_PICKUP + description: Describes the unique code for the cancellation terms. + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + reason_required: + required: mandatory + type: string + owner: BPP + usage: true + description: Indicates whether a reason is required to cancel the order + cancellation_fee: + percentage: + required: optional + type: string + owner: BPP + usage: 2 + description: Describes the percentage value for cancellation fee + amount: + currency: + required: optional + type: string + owner: BPP + usage: INR + description: Describes the currency of a product or service + value: + required: optional + type: string + owner: BPP + usage: 30 + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the price of a product or service + _description: + required: Mandatory + type: object + owner: BPP + usage: '--' + description: Describes the unique code for the cancellation terms + status: + required: mandatory + type: string + owner: BPP + usage: COMPLETED + description: Describes the order status. + created_at: + required: mandatory + type: string + owner: BPP + usage: '2023-12-10T08:03:34.294Z' + description: Describes the date-time of creation of this order + updated_at: + required: mandatory + type: string + owner: BPP + usage: '2023-12-10T08:03:34.294Z' + description: Describes The date-time of updated of this order + billing: + name: + required: optional + type: string + owner: BAP + usage: John Doe + description: Describes the Name of the billable entity + email: + required: optional + type: string + owner: BAP + usage: jane.doe@example.com + description: Describes the email of the billable entity + phone: + required: optional + type: string + owner: BAP + usage: 9897867564 + description: Describes the contact number of the billable entity + id: + required: mandatory + type: string + owner: BPP + usage: ec08edb2 + description: Describes the unqiue order ID. + _description: + required: Mandatory + type: object + owner: BAP/BPP + usage: '--' + description: Describes the order description. +x-errorcodes: + code: + - Event: Route Serviceability error + Description: To & from location not serviceable by Seller application + From: BPP + code: 90201 + - Event: Tracking not enabled + Description: Tracking not enabled for any fulfillment in the order + From: BPP + code: 90202 +x-tlc: + code: + - Term: "Buyer App Fee\t" + Api: "search/on_search/init/on_init\t" + Attribute: BUYER_FINDER_FEE_TYPE + Owner: Buyer App + Value: '“amount”, “percent” ' + Description: >- + If set to “amount” it means Buyer App’s fee is a flat amount in INR. + + If set to “percent” it means the Buyer App’s fee is set as a percentage + of the total fare value. + - Term: 'Buyer App Fee ' + Api: "search/on_search/init/on_init\t" + Attribute: |- + BUYER_FINDER_FEE_AMOUNT + BUYER_FINDER_FEE_PERCENTAGE + Owner: Buyer App + Value: Positive Decimal Number + Description: >- + Quantum of the Buyer App’s Fee. To be interpreted in connection with the + “type” field mentioned above. + + For example, let’s assume the value is set at “5”. If the “type” is set + to “Amount”, that means the Buyer App Fee is INR 5. If the “type” is set + to “percent”, it means the Buyer App Fee is 5% of the Total Order Value. + - Term: 'Payment Collector ' + Api: "search/on_search/init/on_init\t" + Attribute: 'payment.collected_by ' + Owner: Either + Value: '“BAP”, “BPP” ' + Description: >- + If set to “BAP”, it means that the Buyer App will collect payment from + the Buyer. + + If set to “BPP”, it means that the Seller App will collect payment from + the Buyer. + - Term: 'Payment Type ' + Api: 'init/on_init ' + Attribute: 'payment.type ' + Owner: Either + Value: | + “ON-ORDER”, “ON-FULFILLMENT” + Description: >- + How payment is going to be collected from the Buyer. If this parameter + is set to “ON-ORDER”, that means it is a pre-paid order, i.e. the + payment is collected at the time of order confirmation. If this + parameter is set to “ON-FULFILLMENT”, that means it is a pay at the end + of the trip, i.e. the payment is collected when the trip ends. + - Term: 'Settlement Basis ' + Api: "search/on_search/init/on_init\t" + Attribute: 'SETTLEMENT_BASIS ' + Owner: "Seller App\t" + Value: '"INVOICE_RECEIPT", “delivery” ' + Description: >- + The event that will trigger settlement from the Payment Collector to + counterparty Network Participant(s). + + If it is set to “trip complete”, that will mean settlement by the + Payment Collector will be after the completion of the trip. + - Term: 'Settlement Window ' + Api: "search/on_search/init/on_init\t" + Attribute: SETTLEMENT_WINDOW + Owner: Either + Value: 'Time period (ISO8601 format) ' + Description: >- + The time period from completion of the Settlement Basis within which the + Payment Collector will settle with counterparty Network Participant(s). + As an example, if the Settlement Basis is set as “trip complete” and the + Settlement Window is set to 7 days, and the Seller App collects the + payment, it means the Seller App will remit funds to the Buyer App on or + before the completion of the 7th day after successful completion of the + trip, + + ISO8601 duration notation is used to specify the value of the parameter. + As an illustration, a Settlement Window of 5 days after delivery can be + specified as “P5D” (i.e. period 5 days) or “PT120H” (i.e. period 120 + hours). + - Term: Settlement Amount + Api: 'init/on_init ' + Attribute: SETTLEMENT_AMOUNT + Owner: Either + Value: 'Positive Decimal Number ' + Description: >- + The amount that the Payment Collector will remit to the counterparty + Network Participant for the instant transaction. + + For clarity, if the Buyer App is the Payment Collector, the Buyer App + will deduct their fee and remit the balance to the Seller App. If the + Seller App is the Payment Collector, they will remit the Buyer App’s + fee, deduct its own charges/commission + - Term: Settlement Type + Api: "search/on_search/init/on_init\t" + Attribute: SETTLEMENT_TYPE + Owner: Either + Value: '"upi", "neft", "rtgs"' + Description: >- + The Payment Collector will use the selected method to remit the due + payment to the counterparty Network Participant. To illustrate, if the + Buyer App collects the payment and the Settlement Type is set to “rtgs”, + when the settlement is due, the Buyer App will transfer the Seller App’s + share of the Buyer Price to the Seller App’s account via RTGS. + - Term: 'Item Cancellability ' + Api: "search/on_search/init/on_init\t" + Attribute: 'Handled in cancellation terms ' + Owner: "Seller App\t" + Value: "true/ false\t" + Description: >- + Whether the order for that item can be canceled after being confirmed. + If set to “TRUE” that means the Seller allows the Buyer to cancel the + order for the item in question, after confirmation. + - Term: 'Mandatory Arbitration ' + Api: "search/on_search/init/on_init\t" + Attribute: 'MANDATORY_ARBITRATION ' + Owner: "Seller App\t" + Value: "true/ false\t" + Description: >- + If this attribute is set to true, that would mean both parties agree + that in case of a dispute, both parties must resolve the dispute through + arbitration. + - Term: 'Court Jurisdiction ' + Api: "search/on_search/init/on_init\t" + Attribute: 'COURT_JURISDICTION ' + Owner: "Seller App\t" + Value: Pick a city from a given list of cities which have a High Court bench + Description: >- + The name of the city whose courts will have exclusive jurisdiction over + disputes related to this contract. The list of options will only contain + Indian cities which have a High Court bench. + - Term: Delay Interest + Api: "search/on_search/init/on_init\t" + Attribute: DELAY_INTEREST + Owner: "Seller App\t" + Value: Positive Decimal Number + Description: >- + This is the annual rate of interest that the Payment Collector will be + charged if they delay a payment to the counterparty Network Participant, + calculated pro rata for each calendar day of delay. As an example, if + the value is set as “7.3”, and the amount of payment due is INR 1000, + that will mean the Payment Collector will pay the counterparty Network + Participant an interest of 7.3% per annum (i.e. INR 100), calculated pro + rata for each day of delay. So if the Payment Collector delay was 50 + days, the total interest payable would be INR 10 [calculated as + 1000x(7.3/100)x(50/365)] + - Term: Static Terms + Api: "search/on_search/init/on_init\t" + Attribute: STATIC_TERMS + Owner: Seller App & Buyer App + Value: URL + Description: >- + This will be the URL of a web-page where the standard Terms and + Conditions of the Network Participant - which are not covered in the API + Specification (e.g.: indemnity) - will be hosted. These terms will apply + to the transaction, in addition to the terms decided through the ONDC + Protocol. If there is a conflict between the terms decided through the + Protocol, and the Static Terms, the terms decided through the ONDC + Protocol will prevail. Also, if there is a conflict between the Static + Terms and the ONDC Network Policy or the Static Terms and the Network + Participant Agreement, the terms of the ONDC Network Policy or the + Network Participant Agreement (as the case may be) will prevail. +x-sandboxui: + dropdown: + - environment-name: staging + link: https://mobility-staging.ondc.org +x-testcasesui: + filenames: + - log-verification.md diff --git a/docs/api/docs/attribute.md b/docs/api/docs/attribute.md new file mode 100644 index 0000000..136e346 --- /dev/null +++ b/docs/api/docs/attribute.md @@ -0,0 +1,4 @@ +| Protocol Attribute | Business Definition | Sample Usage | Pattern (if any) | Description | +| ------------------ | ------------------- | ------------ | ---------------- | ----------- | +| | | | | | +| | | | | | diff --git a/docs/beckn-core.zip b/docs/beckn-core.zip new file mode 100644 index 0000000..2783085 Binary files /dev/null and b/docs/beckn-core.zip differ diff --git a/docs/beckn-core/.gitignore b/docs/beckn-core/.gitignore new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/docs/beckn-core/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/docs/beckn-core/CHANGELOG.md b/docs/beckn-core/CHANGELOG.md new file mode 100644 index 0000000..1c7f66d --- /dev/null +++ b/docs/beckn-core/CHANGELOG.md @@ -0,0 +1,248 @@ +# Changelog + +## Core v1.0 - 31st December 2022 +### API Changes + +| API Endpoint | 0.9.3 | 1.0 | +|---------|-------|-------| +| rating | Sends a single rating | Allows multiple ratings to be sent | +| support| Returns a ref_id | Returns a **Support** object | +| on_select| Returns a few fields from **Order** object | Returns the complete **Order** object | +| on_init | Returns a few fields from **Order** object | Returns the complete **Order** object | +| on_rating | Returned **RatingAck** object | Returns an **XInput** object | +| on_support | Returned phone, email and url | Returns a **Support** object | + + +### Schema Changes + +| Schema | Added | Removed | Modified | +|--------|--------|---------|----------| +| Ack| tags| - | - | - | +| Address| - | all named fields | Changed to string , entities enclosing Address have address as string and also have named city , state , area_code fields pointing to corresponding object types.| +| Agent| person , contact , organization , rating|all attributes that originally existed| +| Billing | state , city , *country* , *area_code* | created_at , updated_at | address | +| Cancellation|reason , addtional_description|type , ref_id , policies , reasons , selected_reason| +| Catalog| ttl | - | Removed "bpp/" prefix from attrbutes that had them +| Category| ttl | - | tags datatype changed to TagGroup| +| Context|location , version|core_version , city , country| +| Descriptor||symbol , audio , 3d_render|media , additional_desc| +| Domain|name , code , additional_info|-|type changed from String to object +| Error|||type - Enum restriction removed| +| Fulfillment||provider_id , person , customer.person , customer.contact , start , end|rateable , stops(array of FulfillmentStop) , path , tags (TagGroup)|customer type changed to point to (Customer) | +| Image|-|-|Schema changed from string to set of properties| +| Intent|-|-|tags changed from (Tags) to array of (TagGroup) +| ItemQuantity|unitized|-|-| +| Item|parent_item_quantity , manufacturer , quantity , category_ids , fulfillment_ids , location_ids , payment_id , add_ons , cancellation_terms , refund_terms , replacement_terms , return_terms , xinput , ttl|category_id , location_id , fulfillent_id , |tags +| Location|map_url , district , state , area_code , rating|station_code| +| Offer|tags|-|-| +| Order|ref_order_ids , status , type , fulfillments , cancellation , cancellation_terms , refund_terms , replacement_terms , return_terms , payments , xinput , tags|state , documents , fulfillment , payment| items , add_ons , offers +| Organization|descriptor , address , city , state , contact|name , cred| +| Payment|id , collected_by , url , params.bank_code , params.bank_account_number , virtual_payment_address , source_bank_code , source_bank_account_number , source_virtual_payment_address , tags | tl_method , uri , params.transaction_status| type enum changed ON_ORDER to PRE_ORDER| +| Person | id , url , age , creds , languages , skills|cred|tags +| Provider| ttl|locations.rateable | tags +| Quotation| id , breakup[].item| | +| Rating|| feedback_form , feedback_id| +| Scalar||| value , estimated_value , computed_value , range.min , range.max - > number to DecimalValue| +| Tracking| id , location| | | +| Vehicle| wheels_count , cargo_volumne , wheelchair_access , code , emmission_standard| + +### New Schemas +|Name| +|-| +|CancellationTerm| +|Credential| +|Customer| +|Fee| +|Form| +|FulfillmentState| +|MediaFile| +|Region| +|ReplacementTerm| +|ReturnTerm| +|Stop| +|Subscription| +|Support | +|Tag| +|TagGroup| +|XInput| + +### Removed Schemas +|Schema| +|-| +|Dimensions| +|Document| +|Feedback| +|FeedbackForm| +|FeedbackFormElement| +|FeedbackUrl| +|Language| +|Subscriber| +|Operator| +|Page| +|Policy| +|Rateable| +|RatingAck| +|Tags| +|TrackingData| + + +## Core v0.9.3 + +### 13 July, 2021 + +**Changes in Context schema object** +- Removed ack from action +- Changed feedback to rating in action enum +- Updated description for bap_id, bpp_id, bap_uri, bpp_uri, transaction_id, message_id +- changed ttl as type string and updated description + +**Removed context object from acknowledgement responses** + +**Changes to Intent schema object** +- removed query_string +- removed purpose + +**The following were changed to message.order** +- select request's message.selected +- on_select request's message.selected +- on_init request's message.initialized + +**Changes to Fulfillment schema object** +- Added provider_id +- Removed purpose + +**Updated description of Provider.id** + +**Removed tl_method from Tracking schema object** + +**Removed type and ref_id from Quotation schema object** + +**Added category_id to the following** +- Provider schema object +- Intent.provider + +**Changes to Payment schema object** +- Added property transaction_status +- Added property currency + +### 10 August, 2021 + +**Fixed inconsistencies in the required properties** +Provider was removed from required in the following places : +- Order property in /select +- Order property in /init +- Order schema object + +In the following places message was made the only required property : +- /on_search +- /on_select +- /on_init +- /on_confirm +- /on_track +- /on_cancel +- /on_update +- /on_status +- /on_rating +- /on_support + +### 12 August, 2021 + +**Added rating property to the following schema objects** +- Item +- Provider +- Fulfillment + +**Fulfillment and Provider have been referenced directly in the Intent schema object** + +**Security schemes cleanup** +- Added Gateway Subscriber Auth at top level security definition. +- Removed security from individual paths. +- Removed Signature headers +- Updated the format of the authorization headers + +### 19 August, 2021 + +**Added schedule to Time schema object** +Schedule schema object was added to Time + +### 19 August, 2021 + +**Updated the rating flow** + +**Added/Edited the following schema objects :** +- **Rating** - Edited so that the rating_category, rating value and id is present +- **RatingAck** - Newly created to send acknowledgement of receival of rating and feedback +- **FeedbackForm** - Newly created object to represent feedback form +- **FeedbackFormElement** - Newly created object to represent an element in a feedback form +- **FeedbackUrl** - Newly created object to represent feedback URL sent by a BPP +- **Feedback** - Object edited to hold feedback form or feedback URL + +**API endpoints edited/created :** +- **/get_rating_categories** : Returns the allowed categories that can be rated +- **/get_feedback_categories** : Returns the allowed categories that can have a feedback +- **/get_feedback_form** : Request the BPP to get a feedback form +- **/feedback_form** : Get a feedback form from the BPP. Callback response of /get_feedback_form +- **/rating** : Uses Rating object as message +- **/on_rating** : Used RatingAck as message + +**Made all the meta APIs async. Created the following new meta BAP APIs :** +- POST /cancellation_reasons +- POST ​/return_reasons +- POST /rating_categories +- POST ​/feedback_categories + +**Added Rateable property** +A new schema object Rateable of type boolean was added. +The same was added to the following : +- Agent +- Fulfillment +- Item +- Provider +- Location array inside Provider + +### October 8, 2021 + +**Added descriptor to Intent schema object** + +### October 11, 2021 + +**Removed enum in rating_category** + +### October 12, 2021 + +**Removed required** +- Removed intent required from /search +- Removed required id and location from provider object in /select +- Removed required quantity from items in /select +- Removed required items from order object in /select +- Removed required id and location from provider object in /init +- Removed required quantity from items in /init +- Removed required items and billing from order object in /init +- Removed cancellation_reason_id from /cancel +- Removed required cred from Agent schema object +- Removed required name and phone from Billing schema object +- Removed required items, billing, quote and payment from Order schema object +- Removed required quantity from items property in Order schema object +- Removed required id and location from provider property in Order schema object + +### November 24, 2021 + +**Added fulfillment_id in Item schema object** + +### December 10, 2021 + +**Added new Gateway Authentication scheme with deprecation notice** + +### December 13, 2021 + +**Changed the order object in select and init call** + +### December 14, 2021 + +**Authorization object in fulfillment start and end** +- New schema object Authorization added +- New property authorization added to Fulfillment schema object and refers to the newly created Authorization object. + +### December 22, 2021 + +**Added document object array in order** \ No newline at end of file diff --git a/docs/beckn-core/CONTRIBUTION.md b/docs/beckn-core/CONTRIBUTION.md new file mode 100644 index 0000000..b4bab84 --- /dev/null +++ b/docs/beckn-core/CONTRIBUTION.md @@ -0,0 +1,244 @@ +# Contributing to the Specification + + +## Draft 01 + + +# Authors + +1. Ravi Prakash - ravi@becknfoundation.org + + +# Latest Version + +Draft 01 + + +# Previous Versions + +None + + +# Scope + +This document intends to establish transparent and open processes and guidelines to contribute to the beckn protocol specification. It contains design principles and guidelines and considerations that should be adopted by anyone wishing to propose changes to the specification. + +This document is intended for the following audience. + + + +1. Any person or organization who wants to propose a change in the specification + + +# Prerequisites + + + +1. Readers must have knowledge and hands-on experience in **git** and **GitHub**. +2. Readers must have knowledge of beckn protocol specification + + +# Context + +Beckn protocol specification exists as a set of public repositories on Github at https://github.com/beckn. Like all version controlled open-source repositories, there are guidelines that must be followed; design principles to be considered in order to propose changes to the files present in these repositories. These pull requests will then be reviewed by the maintainers of the repository and subsequently merged with the main / master branch of that repository. The governing body and repository maintainer of the beckn protocol specification is the **Core Working Group**. + + +# Abstract + +The evolution of beckn protocol specification should be use-case driven. The working group can specify support for hypothetical use cases as they see fit, but specifications should be backed by realistic scenarios. Management of an open-source specification like beckn protocol should be governed by well defined policies and processes. Proposing any change to an open-source repository starts by raising an Issue against a repository. After an Issue is raised, a Pull Request must be created and linked to that issue. These pull requests must be reviewed and merged by the relevant working groups and repository maintainers via a standard governance model. + + +# Terminology + + + +1. **Git:** A decentralized version control software +2. **Github:** An online platform for managing shared repositories via git +3. **Pull Request:** A request to merge a change to an existing version of the repository +4. **Core Working Group:** Current maintainer and governing authority of the specification + + +# Expected Outcomes After Reading This Document + +After reading this document, the reader should be able to understand how to contribute to the specification. + + +# Introduction + +The current process for evolution of beckn protocol specification is described in the **Contribution Guidelines** section of the document. Development of the next version of the specification is guided by the **Core Working Group (CWG)**. This working group contains members that bring their API expertise, industry knowledge, incorporate feedback from the community, and expand the group of committers as and when appropriate. All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. + +The CWG holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. + +The beckn protocol governance principles encourage participation from individuals and companies alike. + + +# Contribution Guidelines + +Contributing to the specification involves active participation by the contributor in the beckn open community. The following guidelines ensure a higher chance of a proposal being accepted by the community. + + + +1. Knowledge of the specification +2. Initiating healthy discussions on Github and Slack +3. Helping other community members with Issues +4. Providing sufficient documentation and in-depth analysis +5. Following a code of conduct in the discussion forums + +Not all feedback can be accommodated as a change and there may be solid arguments for or against a change being appropriate for the specification. + + +# Contribution Process + + +![Flow](http://13.235.139.60/dev-docs-images/PR%20Flowchart.png) + + + +## 1. Review the specification + +All contributors are expected to review the specification before submitting a proposal. If there is anything that a contributor does not understand, they are free to pose questions to the beckn open community of developers. + + +## 2. Join the Beckn Open Community on Slack + +Joining the open community on Slack is a simple process. Click [here](https://join.slack.com/t/beckn/shared_invite/zt-ucfhmyow-5XuHdRpFrqO2sh4gzcnuQw) to join the developer community on Slack. This is useful to have quick real-time interactions with the developers in the community. + + +## 3. Initiate / participate in discussion threads on Github + +Before proposing a change to the specification, visit the discussion threads on Github [here](https://github.com/beckn/protocol-specifications/discussions) + + +## 4. Subscribe to existing Issues or Pull Requests + +Check the [issues](https://github.com/beckn/protocol-specifications/issues) and [pull requests](https://github.com/beckn/protocol-specifications/pulls) to see if someone has already documented your idea or feedback on the specification. If you find something relevant to your proposal, subscribe to the discussions around Issues and PRs. + + +## 5. Raise an Issue (Feature Requests or Enhancements) + +Create an issue to describe a new concern. If possible, propose a solution. + + +## 6. Create a Pull Request + +Submit a Pull Request against that Issue. + + +# Specification Change Criteria + +The specification will evolve over time. Changes may be made when any of the following criteria are met: + + + +1. **Clarity**. The current "way" something is done doesn't make sense, is complicated, or not clear. +2. **Consistency**. A portion of the specification is not consistent with the rest, or with the industry standard terminology. +3. **Necessary functionality**. We are missing functionality because of a certain design of the specification. +4. **Forward-looking** **Designs**. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. +5. **Impact**. A change will provide an impact on a large number of use cases. We should not be forced to accommodate every use case. Maintainers should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec. Evolution cannot be edge-case driven. + + +# Considerations before Proposing a Change + +For each change in the specification we should always consider the following: + + + +1. **Migration Impact : **Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change +2. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. +3. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface [Needs Edit] + +**Note:** Spec change proposals will be approved by the CWG. Approval will be given via a comment on the issue itself, for example, "_Approved by @cwg-admin_". No change will be approved until there is documentation for it, supplied in an accompanying PR. + + +# Change Tracking and Management on GitHub + +**GitHub** is the medium of record for all spec designs, use cases, and so on. + +All the specification related repositories are present on the official beckn protocol Github account [here](https://github.com/beckn). + + +## Sources of Truth + + + +1. The **protocol-specifications** repository is the source of truth for the core transaction API specification. +2. The **registry** repository is the source of truth for implementing the registry infrastructure +3. The **specification-files** repository is the source of truth for all human readable specification files + + +## Branch Structure + +At any given time, there would be _at most_ 4 working branches. The branches would exist if work has started on them. For example, assume a current version of **0.9.2** in the protocol-specifications repository. + + + +1. **master** - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. +2. **core-0.9.3-draft** - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. +3. **core-0.10.0-draft** - The next MINOR version of the specification. This would include backward compatible changes to the specification like attributes to existing schema. +4. **core-1.0.0-draft** - The next MAJOR version of the specification. + +The master branch shall remain the current, released beckn protocol specification. The will describe and link the working branch(es) on the default README.md on main. + +Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. + +New features should be done in feature branches/forks which, upon approval, will be merged into the proper work branch. + + +## Raising an Issue in the Specification + +Any change to the specification must begin with the creation of a Github Issue. The process for raising an issue on GitHub is detailed [here](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue). + + +## Creating a Pull Request + +All PRs to a specific version of the specification must be made to the **draft** branch of the next upcoming version. For example, All patch changes to version **0.9.2** must be made to the** 0.9.3-draft **branch. + + +# Adding Features to the Core Schema + +Wherever and whenever suitable, new features will be introduced inside the core protocol schema in accordance with the beckn protocol design principles. New features should be _namespaced_ by standard prefixes to indicate their deviation from the standard schema. This namespacing approach enables new features to be designed, documented and then implemented by platforms that are interested in the feature, without putting the burden of implementation on all platforms. If the feature is successfully implemented by a majority of platforms and there is demonstrable value added by the feature, it will become a candidate for inclusion inside the Core Schema in a future release of the specification, at which point all implementations will be expected to support the feature. + + +## Feature evolution stages + +All new features have a life cycle starting from a proposal to a required standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. + + +![Feature Stages](http://13.235.139.60/dev-docs-images/Feature%20Stages.drawio.png) + +## Namespacing Non-Standard Properties + +The name of any new property in the core schema must be namespaced using the below format indicating that it is a **Non-Standard Property **of a schema. + + +`"./{namespace-id}.{feature-name}.{feature-stage}"` + +### Non-standard Property Components + +1. **The dot slash ( ./ )** : This symbol in the context of core specification represents a non-standard property in the core schema. If this property is being developed by a network, all platforms must be able to recognize that this attribute is currently not part of the core specification and use / ignore it appropriately. +2. **namespace-id **: This is a unique id linked to a feature being submitted for inclusion in the specification by a unique entity. The format of the ID varies with the proposer of the feature. + 1. **For Individuals** : Individuals submitting new features must namespace the property with their **Github username**.For example, if Alice is a developer (_username : @alice-dev_) wants to add a feature called `"direction"` in core schema, she must submit her proposal with the new property **"./@alice-dev.direction.proposed" + 2. For Organizations: Organizations submitting new features must namespace the property with their Github orgname. For example, if Beckn Foundation (username : @beckn-foundation) wants to add a feature called “speed” in core schema, she must submit her proposal with the new property "./@beckn-foundation.speed.proposed" +3. feature-name : This is the name of the feature. While creating the feature-name, proposers are recommended to use the following guidelines before submitting the proposal. Please note that these are more like guidelines than rules. + - The English language must be used to propose any new features. + - Standard programming jargon can be used as long as it is widely accepted by the developer community. For example "const" is an acceptable keyword. + - The feature name must be generic and not specific to a limited region or domain +4. feature-stage : For a new feature this value will always be “proposed”. The other values are draft, recommended and required. These values are reserved for CWG committers and will be described in detail in the Specification Governance document. + +## Identifying a new feature in the Schema + +New features under discussion should be identified by the prefixed **“./”** in the property of the json schema. If the feature is deemed appropriate for inclusion in the specification, the namespace will be removed and the feature will be moved inside the Core Schema. Implementations that support new features should plan for the future removal of the prefix. When implementations add support for a later version of beckn protocol that includes the final implementation of the feature, they MUST NOT support the use of the prefix for that feature. New features will only be promoted into minor or major releases of the specification and therefore will be transparent to specification description writers and reference implementation providers who choose not to use the feature while in its draft state. This versioning schema does not apply to V0.x features. In 0.x features, even patch versions can contain bug fixes and enhancements rather than just text changes. + + +## Identifying a new feature in Issues + +New features in Github Issues will be **labeled** with the **feature-stage** label and will be initially labelled as **proposed, draft, recommended, required or not-recommended**. When the proposal is considered sufficiently stable for pilot implementation, it will be labeled **recommended**. If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the “draft” feature-stage name itself may be versioned with a version suffix. e.g. draft-02. When a draft feature becomes part of a future update to the specification any version suffix will be removed. Draft features that are deemed not appropriate for inclusion MUST be marked with the **not-recommended** label. Draft-features that are considered suitably specified and have had successful pilot implementations will be marked with the **recommended** label. If a draft feature is considered to be a required feature in ALL implementations, it will be marked with a **required** label. + +Not all future new features will be introduced in this way. Some new features impact the specification in ways that cannot be encapsulated in this way. However, where a new feature can be introduced in this way, it should be. + + +# Participation + +While governance of the specification is the role of the CWG, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. + +However, during any interaction with the community or its members, there is a code of conduct and a set of community guidelines that everyone is expected to adhere to. Please find the details [here](https://becknprotocol.io/community-guidelines/). \ No newline at end of file diff --git a/docs/beckn-core/GOVERNANCE.md b/docs/beckn-core/GOVERNANCE.md new file mode 100644 index 0000000..164b61c --- /dev/null +++ b/docs/beckn-core/GOVERNANCE.md @@ -0,0 +1,391 @@ +# Specification Governance + +# Version +0.6.0 + +# Draft Version +Draft 03 + +# Previous Versions + +- Draft 02 +- Draft 01 + +# Scope + +This document intends to establish processes and guidelines which build a transparent, open mechanism for deciding how to manage contributions to the beckn protocol specification. The Core Working Group will initially follow these processes when merging changes from contributors. This guideline document will be adjusted as practicality dictates. + +This document is intended for the following audience. + +1. Anyone who wants to understand how contributions are reviewed and merged by the Core Working Group + +# Prerequisites + +1. Readers must have a working knowledge of git +2. Readers should also know how open-source repositories are managed on Github. +3. Readers must have knowledge and understanding of beckn protocol specification + +# Context + +Beckn protocol exists as a set of specifications documented within public repositories on Github at https://github.com/beckn. These repositories contain specification documents, reference implementations, tools and utilities. Like all version controlled open-source repositories, there are processes that must be adopted to manage changes to the files present in these repositories. The most common way a change is proposed to the specification is via an Issue linked to that repository which ultimately gets converted to a Pull Request linked to that Issue. These pull requests must then be reviewed by the maintainers of the repository and subsequently merged with the main / master branch of that repository. + +# Abstract + +The evolution of beckn protocol specification is always use-case driven. The Core Working Group can specify support for hypothetical use cases as they see fit, but the specifications should be backed by realistic scenarios. Management of contributions towards an open-source specification like beckn protocol are governed by well defined policies and processes. These processes will evolve just like the specification does, based on use cases. Given beckn is designed to be a global protocol, maintainers and committers must be aware any change committed to the specification has a global impact on implementation. Therefore, the governance model of beckn protocol specification is based on strict and unambiguous design principles described in this document. Anyone reviewing pull requests must apply these principles on each suggested change and decide if a change is deemed worthy of inclusion into the specification. The methodologies, guidelines and processes of conducting working group meetings to review contributions made to the specification is described in this document. + + +# Terminology + +1. **Git:** A decentralized version control software +2. **Github:** An online platform for managing shared repositories via git +3. **Pull Request:** A request to merge a change to an existing version of the repository +4. **Core Working Group:** Current maintainer of the specification + + +# Expected Outcomes after reading this document + +After reading this document, the reader should be able to + +- TODO +- TODO + +# The Beckn Credo +The beckn community is an open community. So, no registrations. No memberships. No partnerships. Just a minimal footprint of an open and equally accessible Beckn Protocol that anyone can use. Multiple businesses and organizations have started using beckn protocol to fuel their digital acceleration. The credo of being an open protocol creates a level-playing field for any market player, small or large. + +## Motivation +To make the internet small-business friendly. be a force multiplier with minimal footprint. + +## Guiding Lights +Open specs, equal access. retain agency of small businesses. non-rivalrous, non-exclusive networks + +## Community Driven +Increase value for all participants. be a network weaver in your own way. be a contributor of specs and best practices + +Beckn protocol is an open protocol with an abstract core, that is enabling market players to re-imagine building seamless digital experiences and networks. This is very similar to how HTTP, while being a simple and open protocol has fueled seamless interaction between multiple systems and led to an explosive growth in internet adoption. + +## Open Community Contributions +Beckn protocol has been accepting community contributions to the specification since May 2020. + +# Design Principles for Specification Evolution +To allow contributions from the beckn open community, the following design principles need to be applied while reviewing or proposing changes to the specification. They are: + +## Interoperability: +Any feature added to the specification must ensure that it increases interoperability between implementations. + +## Abstraction +Any feature included in the specification must be abstracted so as to allow it to be consumed across a global range of use cases. That means no feature should be linked to a specific domain, region or use case. + +## Optimal ignorance: +Before including any feature in the specification, reviewers should ask the following questions: a) _Do we need it?_ And, b) _Do we need it now?_ If the answer to both these questions is “Yes” then that feature may be included in the specification. + +## Security +Any feature being included in the specification must be tested for any security vulnerabilities. Free text fields, loosely-typed fields should be avoided. + +## Privacy and Consent +Any feature that may be used to explicitly capture Personally Identifiable Information should not be accepted. Features especially like age, gender, contact information must be avoided and must only be shared via a consent mechanism. + +## Scalability +Any feature being included in the specification must be tested for scalability. Any feature that is included must be agnostic of scale. Contributors should keep in mind that the implementors may not always have the capability to scale their platform and hence contributors should be aware of this limitation while proposing changes to the spec. + +## Reusability +Any new feature must be checked if it can reuse components from the existing schema before inclusion into the specification. + +## Unification over Standardization +Not all features across the globe can be standardized. Standard values vary with domain, region and adoption. In case multiple standards are being adopted for a single feature, it is recommended that both the standards are included in the feature instead of proposing a new standard. For example, if a Location schema is defined using gps and address, then the feature should include both gps and address instead of choosing one over the other. Standardization should occur as a natural consequence of market adoption rather than a forced adoption. + +There will be exceptions to the above principles. The objective of the Core Working Group is to address such exceptions and define the most logical way to include such exceptions in the specification and clearly document those deviations. + +# Introduction +Beckn protocol is maintained via an open community-driven governance model. The community comprises multiple businesses and organizations that actively contribute to the specification to fuel their digital acceleration. This collaboration across domains, technologies and expertises will bring in new ideas which need to be part of the protocol. Hence there is a need for a standardised process for making relevant changes to the specification as well and for a retrospective understanding of the specification. The governance model for beckn protocol has been created using some of the best practices of globally recognized governance models. + +Evolution of beckn protocol is managed by committers of the **Core Working Group**. This working group consists of members from the **Beckn Open Community** that bring their architectural expertise, open-source knowledge, and industry experience to continuously review proposals to update the specification, and to also manage its releases. They constantly interact with the community members and incorporate their feedback, and also expand the group of committers as and when appropriate. + +The Core Working Group holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. + +This governance model is inspired from the [OpenAPI ](https://www.openapis.org/participate/how-to-contribute/governance) Specification and IETF governance models. + +## Need for Governance +Since the core specification is essentially abstracted, the implementors of the specification must use instances of the core specification for various domains, regions and scope. Moreover, the beckn protocol specification is implemented by applying policies on the core specification. Hence, there is a need for a strong and inclusive governance model that adheres to the basic design principles while simultaneously being inclusive in its approach to evolution as opposed to a foundation-controlled evolution. + +## Areas That Require Governance + +There are many independently governable specification elements in the Beckn Protocol. These elements are called areas. Each area will have multiple working groups under it. The following are the areas currently identified : + +### Design Principles +Beckn protocol specification adopts a set of design principles that must be adhered to at all times while updating the specification. These principles, like all other principles, are not applicable for all time. Hence, the design principles must also allow themselves to evolve over time. Only then will the protocol be future-proof. The Core Working Group must: + +- Document the design principles in its purest and most unambiguous form +- Identify any overlaps between design principles, and find a way to make each principle atomic in its definition +- Define a methodology to apply each principle on various decision points related to the specification +- Create sufficient examples for each principle to allow contributors to self-apply the principles before proposing changes to the specification +- Periodically stress-test the design principles on the various components of the specification +- Record any violation of said design principles and report it to the violator with suggested changes + + +### Licensing +Beckn protocol is currently covered under a Creative Commons License. Just like the design principles, the licensing also may change basis the extent of adoption by the community. The Core Working Group must: + +- Clearly define what is allowed and not allowed as per the licensing rules in practical implementation scenarios +- Gather feedback from the ecosystem around issues faced by implementors due to the licensing +- Provide solutions to overcome problems around licensing +- If all of the above fail to achieve outomes, also consider changing the license to make the protocol more flexible without loss of interoperability + +### API +Beckn protocol defines a set of actions that may be implemented as APIs. The Core Working Group must: + +- Clearly define the methods supported by the API +- Document the API in standard machine-readable formats like Open API, Async API or likewise +- Define methodologies to test the API against various use cases +- Extend the API to support more use cases + +### Schema +Beckn protocol defines a standard schema that can be composed and instantiated as run-time objects. The Core Working Group must: + +- Clearly define the schema in an unambiguous manner +- Document the schema in standard formats like JSON Schema +- Define methodologies to test the schema against various use cases +- Extend the schema set to support more use cases via addition or extension +- Define methodologies to map any sector-specific knowledge model to the core schema + +### Communication +Beckn protocol defines a standard communication protocol for each API endpoint. The Core Working Group must: + +- Clearly define the exchange mechanism for each action via UML sequence diagrams +- Link the schema and API definition in each sequence +- Explain each interaction in simple terms +- Define methodologies to map real-world consumer-provider interactions to beckn protocol interactions + +### Architecture +Beckn protocol specifies a standard reference architecture of an open network. The network actors it currently includes are BAP, BPP, BG and a Network Registry. The Core Working Group must: + +- Document the ecosystem architecture in an unambiguous, machine-readable way. Using UML wherever possible +- Clearly define each layer of the architecture +- Clearly define the actors in each layer of the architecture +- To clearly define the purpose of each Network Actor +- To maintain an up-to-date, technology-agnostic, high-level reference implementation architecture document for each network actor +- To define processes to add new Network Actors to the specification +- Define processes to periodically evolve the architecture based on community contributions + +# Area Director (AD) + +Each area will have an Area Director who will be responsible for the functioning and creation of the Working Groups (WG) under it and appointing the WG chair(s). The AD will be a volunteer from the community who will adhere to the design principles while reviewing any proposal submitted by a contributor. + +# Working Groups (WG) + +A Working Group is a collection of people who collaborate on, and are responsible for managing evolution of the specification. + +## Purpose of Specification Working Groups + +## Working Group Roles + +Each WG has the following roles + +1. Administrator +2. Core Committer +3. API Designer +4. System Architect +5. Community Manager +6. Project Manager +7. Subject Matter Expert +8. Implementation Expert +9. Call Moderator +10. Scribe + +### Administrator + +Each WG will have an Administrator (Admin). The Admin will be responsible for declaring a rough consensus on any decision the group has to make. Having full consensus is preferred but not required. During a decision process if the Admin decides that the issues brought forward have been discussed enough and the group has made an informed decision, the Admin can declare that there is rough consensus to go ahead with the decision. For assets (github repository, document collections, group email id etc) coming under each WG, the Admin will have access to modify it. + +There could be more than one person in the group qualified for an Administrator role, but at any time there will only be one person playing that role. The remaining members may be selected via a selection process that is mutually agreed by the members of the working group. + +#### Selection Criteria for a WG Admin +1. Architectural expertise +2. Domain expertise across multiple industry sectors +3. Implementation expertise across multiple technologies +4. In-depth understanding of beckn protocol design principles and its applications +5. Open-source experience +6. Experience with Git and Github management + +### Core Committers + +Each WG will have at least one Core Committer. The objective of a core committer is to +1. Review Proposals +2. Review Protocol Drafts +3. Respond to discussion threads +4. Review and merge PRs to the specification. + +#### Selection Criteria for a Core Committer +1. Architectural expertise +2. Domain expertise across multiple industry sectors +3. Implementation expertise across multiple technologies +4. In-depth understanding of beckn protocol and its applications +5. Open-source experience + + +### Working Group Members + +Anyone can send a request to be added to the WG to attend meetings and weigh in with opinions about any decision or through mails. To become part of a WG, one must send an email to the WG Admin. WG members can participate in discussions on Issues and Pull Requests, and respond to comments in the discussion forums. However, the approval of a working group member will not be decisiove in merging PRs to the specification. + +# Managing Specification Evolution + +The specification will evolve over time. Changes may be made when any of the following criteria are met: + +1. **Clarity**. The current "way" something is done doesn't make sense, is complicated, or not clear. +2. **Consistency**. A portion of the specification is not consistent with the rest, or with the industry standard terminology. +3. **Necessary functionality**. We are missing functionality because of a certain design of the specification. +4. **Forward-looking Designs**. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. +5. **Impact**. A change will have an impact on a large number of use cases. We should not be forced to accommodate every use case. Maintainers should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. + +# Specification Evolution Guidelines + +Any change made to specification must happen via a rigourous and comprehensive review mechanism. The review broadly requires the core committers to apply each of the design principles on the proposed change and submit an objective response to the proposer(s). + +1. **Relevance**: Beckn protocol has defined clear boundaries on what is in-scope of beckn protocol and what is not. CWG members should ask themselves some basic questions like. Is it network-specific? Is it technology-specific? Is it implementation-specific? + +2. **Migration Impact**: Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change +3. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. +4. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface + +Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @cwgadmin" however at least one formal GitHub-based flow approval must be given. After the voting criteria is met, the WG Admin can merge or assign a member to merge the PR. No change should be approved until there is documentation for it, supplied in an accompanying PR. + +# Feature Evolution + +All new features have a lifecycle starting from a proposal to a protocol standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. + +All proposals to the specification are submitted as namespaced properties as mentioned in CONTRIBUTIONS.md. The working group has the responsibility of reviewing these proposals and classify them accordingly as draft, recommended, required or not-recommended features. Once classified, the WGs must rename the namespace with the appropriate feature stage component after review. + +All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. + + +## Proposal + +All proposals will have the following namespace + +``` +"./@alice-dev.direction.proposed" +``` + + + +## Draft Features + +All draft features will have the following namespace structure + + +``` +"./@proposer.feature.draft" +``` + + + +## Recommended Standard + +All recommended standards will have the following namespace structure + + +``` +"./@proposer.feature.recommended" +``` + + + +## Required Standard + +All recommended standards will have the following namespace structure on the draft branch. All namespaces from required standards have to be replaced with the feature names before merging them to master. + + +``` +"./@proposer.feature.required" +``` + +### Not Recommended + +``` +"./@proposer.direction.not-recommended" +``` + +# Working Group Weekly Meetings + +To review change requests to the specification, Working Groups should review and discuss their inclusion in weekly meetings. The meeting consists of four major agenda items. + +1. **Bugs:** This involves discussing all Issues that have been raised as bugs. These will have the highest priority in terms of consideration and will have to be acknowledged and resolved within one week of submission. +2. **Proposed Enhancements:** This involves listing all the new features that have been proposed in the form of Pull Requests to the draft branches. As there are four types of branches, there is an order of priority with which proposals to each branch should be reviewed. The order of priority is recommended as follows + 1. Minor Version Draft Branch + 2. Patch Version Draft Branch + 3. Major Version Draft Branch + +As the master branch cannot accept any proposals, any proposal to the master branch must be explicitly rejected by the committers. + +3. **Draft features:** This agenda involves all the proposals that have been accepted and have been classified as draft features in the previous working group meeting. In this agenda, the working group will decide whether to classify it as a **Recommended** or a **Not Recommended** standard. +4. **Recommended Standard:** This agenda involves all the draft features that have been accepted as a **Recommended Standard**. The outcome of this agenda is to classify whether a Recommended Standard can be classified as a **Required Standard**. +5. **Final Decision and Commit Approvals**: This is the final agenda of the meeting and contains a list of commits that have to be merged to the various branches. + +The duration of the working group meetings can be set by the Working Group Administrator. In case all proposals are not reviewed within the meeting, the WG Admin can propose a second meeting during the week to complete the discussion, + + +# Change Tracking and Management + +**GitHub** is the medium of record for all spec designs, use cases, and so on. + +All the specification documents are present on the official beckn protocol Github account [here](https://github.com/beckn). + + +## Sources of Truth + +1. The **protocol-specifications** repository is the source of truth for the core transaction API specification. +2. The **registry** repository is the source of truth for implementing the registry infrastructure +3. The **specification-files** repository is the source of truth for all human readable specification files + + +## Branch Structure + +At any given time, there should be _at most_ 4 working branches. The branches would exist if implementation has started on them. For example, assume a current version of **0.9.2** in the protocol-specifications repository. + +1. **master** - Current stable version. No PRs should be accepted directly to modify the specification. PRs against supporting files can be accepted. +2. **core-0.9.3-draft** - The next PATCH version of the specification. This should include non-breaking changes such as typo fixes, document fixes, wording clarifications. +3. **core-0.10.0-draft** - The next MINOR version of the specification. This would include backward compatible changes to the specification like attributes to existing schema. +4. **core-1.0.0-draft** - The next MAJOR version of the specification. + +The master branch shall remain the current, released beckn protocol specification. The will describe and link the working branch(es) on the default README.md on main. + +Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. + +Use labels for the workflow of specification changes. Examples of labels are _proposed_, _draft-*_, _recommended_, _required_-, _not-recommended_, _review_ (candidate for upcoming WG meeting), _rejected_, and _needs-approval_. These labels must be assigned by WG members. Style is lowercase with dashes in place of spaces. + +An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change. + +A PR will be used to describe the _proposed_ solution and linked to the original issue. + +Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel. + +When the work branch is ready and approved, the branch will be merged to main. + + +## Reviewing Pull Requests + +Any Pull Request must have an associated Issue. If an Issue is not present, the reviewer must post a comment on the PR comment section asking the contributor to Raise an Issue and link the PR to it. If an Issue is not raised within 24 hours, the PR should be considered as rejected and must be closed by the reviewer with the comment _“Closing this due to unlinked Issue”_ + + +## Managing Conflicts + +If a Pull Request causes a merge conflict, the reviewer should respond with a comment “Merge conflicts present, kindly resolve and re-submit PR”. If the merge conflict is not resolved within 24 hours, the PR should be considered as rejected and must be closed by the reviewer with the comment “_Closing this due to unresolved merge conflicts_” + + +# Release Process + +A release requires a vote on the release notes by CWG members within the voting period. Major or minor release voting periods will be announced by the CWG admin in the Slack channel and noted on the calendar at least 6 days in advance. During this time, CWG members who have not yet voted must note their approval on the GitHub pull request for the release notes. Patch releases must happen at the first CWG meeting of a calendar month. The CWG admin is responsible for coordinating the actual merge to main with marketing support, if any. + +* Patch-level releases require majority approval by WG members. (Max voting period 3 days) +* Minor: requires approval by 66% of WG members. (Max voting period 7 days) +* Major: requires approval by 66% of WG members. (Max voting period 14 days) + +The above policies apply to the Core Working Group. However, a WG Admin may override the majority and voting period depending on the area and size of the group. + + +# Transparency + +The process should be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. General discussions should happen on the GitHub issues for this project. + + +# Participation + +While governance of the specification is the role of the CWG, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. diff --git a/docs/beckn-core/LICENSE.md b/docs/beckn-core/LICENSE.md new file mode 100644 index 0000000..6b81a4b --- /dev/null +++ b/docs/beckn-core/LICENSE.md @@ -0,0 +1,177 @@ +## creative commons + +# Attribution-NonCommercial-ShareAlike 4.0 International + +Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. + +### Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. + +* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors). + +* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). + +## Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. + +### Section 1 – Definitions. + +a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. + +b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. + +c. __BY-NC-SA Compatible License__ means a license listed at [creativecommons.org/compatiblelicenses](http://creativecommons.org/compatiblelicenses), approved by Creative Commons as essentially the equivalent of this Public License. + +d. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. + +e. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. + +f. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. + +g. __License Elements__ means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution, NonCommercial, and ShareAlike. + +h. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. + +i. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. + +h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. + +i. __NonCommercial__ means not primarily intended for or directed towards commercial advantage or monetary compensation. For purposes of this Public License, the exchange of the Licensed Material for other material subject to Copyright and Similar Rights by digital file-sharing or similar means is NonCommercial provided there is no payment of monetary compensation in connection with the exchange. + +j. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. + +k. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. + +l. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. + +### Section 2 – Scope. + +a. ___License grant.___ + + 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: + + A. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and + + B. produce, reproduce, and Share Adapted Material for NonCommercial purposes only. + + 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + + 3. __Term.__ The term of this Public License is specified in Section 6(a). + + 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + + 5. __Downstream recipients.__ + + A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. + + B. __Additional offer from the Licensor – Adapted Material.__ Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. + + C. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. + + 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + +b. ___Other rights.___ + + 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this Public License. + + 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Licensed Material is used other than for NonCommercial purposes. + +### Section 3 – License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the following conditions. + +a. ___Attribution.___ + + 1. If You Share the Licensed Material (including in modified form), You must: + + A. retain the following if it is supplied by the Licensor with the Licensed Material: + + i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of warranties; + + v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + + B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and + + C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. + + 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. + +b. ___ShareAlike.___ + +In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. + + 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-NC-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. + +### Section 4 – Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: + +a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database for NonCommercial purposes only; + +b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and + +c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. + +### Section 5 – Disclaimer of Warranties and Limitation of Liability. + +a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__ + +b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__ + +c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. + +### Section 6 – Term and Termination. + +a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. + +b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + + 2. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + + For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. + +c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. + +d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. + +### Section 7 – Other Terms and Conditions. + +a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. + +b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. + +### Section 8 – Interpretation. + +a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. + +b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. + +c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. + +d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. + +``` +Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. + +Creative Commons may be contacted at [creativecommons.org](http://creativecommons.org/). +``` \ No newline at end of file diff --git a/docs/beckn-core/MAINTAINERS.md b/docs/beckn-core/MAINTAINERS.md new file mode 100644 index 0000000..f528d71 --- /dev/null +++ b/docs/beckn-core/MAINTAINERS.md @@ -0,0 +1,8 @@ +# Ravi Prakash +* __Github__ : [ravi-prakash-v](https://github.com/ravi-prakash-v) + +# Pramod Varma +* __Github__ : [pramodkvarma](https://github.com/pramodkvarma) + +# Venkataraman Mahadevan +* __Github__ : [venkatramanm](https://github.com/venkatramanm) diff --git a/docs/beckn-core/README.md b/docs/beckn-core/README.md new file mode 100644 index 0000000..19a71d1 --- /dev/null +++ b/docs/beckn-core/README.md @@ -0,0 +1,106 @@ +--- +title: "Beckn Protocol - Core" +metaTitle: "Beckn Protocol Transaction API Core" +metaDescription: "Domain agnostic transaction specification for e-commerce" +--- + +## Specification Evolution + +| Domain | Version | Release Date | +|-----------------------|-----------|-----------------------| +| Core | 1.0.0 | 31 December 2022 | +| Core | 0.9.3 | 22 December 2021 | +| Core | 0.9.2 | 27 July, 2021 | +| Core | 0.9.1 | 09 November, 2020 | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/fd154368c4670218ce6ad0fc8ee4ada5c401b485/final-mile-delivery/v0) | 0.8.3 | 10 October, 2020 | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/ba54b53aa341d6d0bc0f65633b0a33ff75b628ab/final-mile-delivery/v0) | 0.8.2 | 21 August, 2020 | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/029496c7e969fc322f654e19ee4ae7299c25fdb5/final-mile-delivery/v0) | 0.8.1 | 19 August, 2020 | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/v0) | 0.8.0 | 10 August, 2020 | +| [Core](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/v0) | 0.8.2 | 10 August, 2020 | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/archives/schema/0.7.0) | 0.7.0 | 06 July, 2020 | +| [Mobility](https://github.com/beckn/protocol-specifications/tree/master/mobility/schema/0.8.0) | 0.8.0 | 02 July, 2020 | +| Final Mile Delivery | 0.6.0 (depr) | 02 June, 2020 | +| [Food and Beverage](https://github.com/beckn/protocol-specifications/tree/master/food-and-beverage/schema/0.4.0) | 0.4.0 | 02 June, 2020 | +| Final Mile Delivery | 0.5.1 (depr) | 21 May, 2020 | +| [Core](https://github.com/beckn/protocol-specifications/tree/master/core/schema/0.8.0) | 0.8.0 | 21 May, 2020 | +| [Healthcare](https://developers.beckn.org/Healthcare) | 0.5.0 | 02 May, 2020 | +| Food and Beverage | 0.3.1 (depr) | 22 April, 2020 | +| Core (depr) | 0.7.1 | 17 April, 2020 | +| Mobility (depr) | 0.7.1 | 09 December, 2019 | +| Mobility (depr) | 0.7.0 | 31 October, 2019 | + +# Introduction + +**Beckn** is an open protocol that allows local businesses across any industry to be discovered and engaged by any beckn-enabled application. Beckn protocol helps businesses co-create solutions for the masses seamlessly, by combining services of any form or provider. + +**Beckn protocol** is a collection of open specifications consisting of protocol APIs, message formats, network design and reference architectures to allow any two entities to execute commercial transactions without being on the same platform. + +This server-to-server communication protocol allows any consumer facing online platform to discover and transact with any business with minimal implementation overhead. The server-to-server nature of the protocol allows rich user experiences to be built by bundling services from multiple independent platforms. + +Beckn protocol decouples the demand side digital infrastructure in the form of apps and other channels from the supply side service provisioning infrastructure. It does this by making integratedservices available not just on a single platform but potentially on any online consumer interface, (online maps, messaging, wallets, voice assistant apps and devices) that have mainstream adoption in a city. + +Beckn is a protocol, not a platform. It adopts a decentralized architecture that obviates the need for creating a centralised platform in order to integrate services from multiple providers simultaneously ensuring privacy and security by design by enabling secure, encrypted iteractions. + +## Beckn Protocol - Core Specification + +Beckn protocol - core specification defines a generic, abstracted API that when implemented allows domain-agnostic interoperable e-commerce transactions between a buyer and seller irrespective of which platform they are on. An analogy similar to this would be the case of SMTP specification that allows email communication between any two platforms that have implemented the same specification. + +The core specification defines APIs for the following events in e-commerce + +1. Discovery - This involves activities like platform discovery, catalog browsing, filtering and item viewing +2. Ordering - This involves activities like cart building, quote calculation, checkout & payment terms agreement, and ultimately order confirmation +3. Fulfillment - This involves all post-order-creation activities like tracking, order update, cancellation and status updates +4. Post-fulfillment - The involves all post-fulfillment activities like rating, feedback, support, returns and replacements + +## Packet Structure + +All communication using beckn protocol have the following packet structure + +| Field | Description | +|---------------|-----------------------------------------------------------------------------------------------| +| `context` | Contains header information that is used for packet switching, key lookup, and encryption | +| `message` | Contains transaction information that is visible only to the participants of a transaction | + +## Transport Protocol + +While beckn protocol it designed to be transport agnostic, it is conventional to use HTTP as the default transport protocol. Additional layers like security and trust can be layered on top of this protocol using exisiting standards like HTTPS and SSL. It is recommended that any platform implementing beckn protocol use HTTPS to secure its communication. + + +## Communication + +Communication on beckn enabled networks is server-to-server. Server-to-server means that communication between any two systems on a beckn network does not involve the client application. The client is free to render the data in whatever form chosen by the product. Secondly, all communication is asynchronous. Asynchronous API calls do not block (or wait) for the API call to return from the receiver server in the same session. Instead, an immediate acknowledgment is sent to the sender server in the same session and the actual response from the receiver server is in the form of a callback API call to the sender server. The above two features provide a remarkable advantage as all sorts of innovations are possible in the application layer due to the experience layer being unbundled from the session and presentation layer of the application. + +A beckn enabled network has multiple entities communicating with each other via standard protocol APIs. The following types of communication are possible. The communication can be between, + +- BAP and BG +- BAP and BPP +- BG and BPP +- BAP and Registry +- BPP and Registry +- BG and Registry + +All API calls between any two entities on the beckn network are asynchronous. Meaning, an API call from a BAP server (sender) to a BPP server (receiver) does not expect an informational response from a BPP in the same session. The immediate response in the same session is merely an acknowledgment or ACK which basically means, “Hey, I have received your request and it looks okay during validation of the input. Let me call you back when I have the details you need”. The actual response is sent later in the form of a standard callback API which the sender is required to implement. + +## Communication Protocol Between 2 Entities +The sequence diagram of a typical beckn protocol API is shown in Figure 1. For example, let’s say X is the sender and Y is the receiver, and the API being called is search. + +In most cases, the sender will call the API first and the receiver will respond immediately with an ACK and close the session. After an arbitrary period of time (which is dependent on the processing of the message), the receiver will respond with an API callback to the sender. The name of the callback API is the name of the sender API with an “on_” prefix. For example, if the request API is called “search” then the associated callback API will be “on_search”. + +## Communication Protocol Via Beckn Gateway + +Most communication in a beckn enabled network involves two entities - the BAP and the BPP. But sometimes during the discovery stage, an intermediate entity like a Beckn Gateway (BG) is involved. In those cases, the recommended flow of communication is as follows. + +If the address of the BPP is _not_ specified in the `context` field of the request body, only then should the BAP should call the `search` request to the BG. The BG may then broadcast this request to multiple BPPs that match the `context` of the request. + +Sometimes the BG may query a Registry via the `lookup` API to get the BPP addresses that _match_ the `context` and then broadcast the message to those BPPs. + +The BPPs immediately respond with ACKs. Soon after, the BPPs call the `on_search` API which is sent back to the BG. The BG then forwards those requests back to the BAPs. + +To protect the privacy and confidentiality of the end user, it is recommended not to send _Personally Identifiable Information_ (PII) or _transactional information_ in the `message` object when transmitting via a BG. The BG should be able to only use the `context` header to perform BPP discovery and routing. + + +# Acknowledgments +The author would like to thank the following individuals for their contributions in creating the this document. (in alphabetical order): + +Pramod Varma, Beckn Foundation +Sujith Nair, Beckn Foundation diff --git a/docs/beckn-core/WORKING-GROUPS.md b/docs/beckn-core/WORKING-GROUPS.md new file mode 100644 index 0000000..4f185ca --- /dev/null +++ b/docs/beckn-core/WORKING-GROUPS.md @@ -0,0 +1,39 @@ +# Core Working Group +* [Ravi Prakash](#TODO) +* [Pramod Varma](#TODO) +* [Sujith Nair](#TODO) +* [Nirmal Rajeevan](#TODO) +* [Venkataraman Mahadevan](#TODO) +* [Paul Kapustin](#TODO) + +# Mobility Working Group +* [Sujith Nair](#TODO) +* [Ravi Prakash](#TODO) +* [Srikanth Chunduri](#TODO) +* [Nirmal Rajeevan](#TODO) +* [Nikith Shetty](#TODO) +* [Paul Kapustin](#TODO) +* [Oleg Romashin](#TODO) + +# Retail Working Group +* [Venkatraman Mahadevan](#TODO) +* [Thejesh GN](#TODO) +* [Ashok Ayengar](#TODO) +* [Akshay Mathur](#TODO) + +# Logistics Working Group +* [Oleg Romashin](#TODO) +* [Paul Kapustin](#TODO) +* [Nikith Shetty](#TODO) + +# Infrastructure Working Group +* [Dhiraj Patorkar](#TODO) +* [Devendra Rane](#TODO) +* [Sujeet Suryavanshi](#TODO) +* [Nikith Shetty](#TODO) +* [Dharmesh Bajpai](#TODO) + +# Network Security Working Group +* [Sasi Kumar Ganesan](#TODO) +* [Venkataraman Mahadevan](#TODO) +* [Ravi Prakash](#TODO) diff --git a/docs/beckn-core/api/meta/README.md b/docs/beckn-core/api/meta/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/beckn-core/api/meta/build/meta.yaml b/docs/beckn-core/api/meta/build/meta.yaml new file mode 100644 index 0000000..4992bd2 --- /dev/null +++ b/docs/beckn-core/api/meta/build/meta.yaml @@ -0,0 +1,526 @@ +openapi: 3.0.0 +info: + title: Beckn Protocol Meta API + description: This document contains all the meta API endpoints that are implemented by the network participants. The information returned from these endpoints typically contain cacheable information. + version: 1.0.0 +security: + - SubscriberAuth: [] +paths: + /get_cancellation_reasons: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP fetches the list of cancellation reasons from BPP + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - properties: + action: + enum: + - get_cancellation_reasons + required: + - action + required: + - context + responses: + default: + $ref: '#/paths/~1return_reasons/post/responses/default' + /cancellation_reasons: + post: + tags: + - Beckn Application Platform (BPP) + description: BPP sends cancellation reasons to BAP + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - properties: + action: + enum: + - cancellation_reasons + required: + - action + message: + type: object + properties: + cancellation_reasons: + type: array + items: + $ref: '#/components/schemas/Option' + required: + - cancellation_reasons + required: + - context + - message + responses: + default: + $ref: '#/paths/~1return_reasons/post/responses/default' + /get_return_reasons: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP requests BPP to provide the list of return reasons + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - properties: + action: + enum: + - get_return_reasons + required: + - action + required: + - context + responses: + default: + $ref: '#/paths/~1return_reasons/post/responses/default' + /return_reasons: + post: + tags: + - Beckn Application Platform (BPP) + description: BPP provides the list of return reasons to the BAP + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - properties: + action: + enum: + - return_reasons + required: + - action + message: + type: object + properties: + return_reasons: + type: array + items: + $ref: '#/components/schemas/Option' + required: + - return_reasons + required: + - context + - message + responses: + default: + description: Acknowledgement of message received after successful validation of schema and signature + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + allOf: + - description: 'Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack must be returned in the same session. Every API call to a BPP must be responded to with an Ack whether the BPP intends to respond with a callback or not. This has one property called `status` that indicates the status of the Acknowledgement.' + type: object + properties: + status: + type: string + description: 'The status of the acknowledgement. If the request passes the validation criteria of the BPP, then this is set to ACK. If a BPP responds with status = `ACK` to a request, it is required to respond with a callback. If the request fails the validation criteria, then this is set to NACK. Additionally, if a BPP does not intend to respond with a callback even after the request meets the validation criteria, it should set this value to `NACK`.' + enum: + - ACK + - NACK + tags: + description: A list of tags containing any additional information sent along with the Acknowledgement. + type: array + items: + description: 'A collection of tag objects with group level attributes. For detailed documentation on the Tags and Tag Groups schema go to https://github.com/beckn/protocol-specifications/discussions/316' + type: object + properties: + display: + description: 'Indicates the display properties of the tag group. If display is set to false, then the group will not be displayed. If it is set to true, it should be displayed. However, group-level display properties can be overriden by individual tag-level display property. As this schema is purely for catalog display purposes, it is not recommended to send this value during search.' + type: boolean + default: true + code: + description: 'The machine-readable name of the tag group. The allowed values of this property can be published at three levels namely, a) Core specification, b) industry sector-specific adaptations, and c) Network-specific adaptations. Except core, each adaptation (sector or network) should prefix a unique namespace with the allowed value. Values outside the allowed values may or may not be ignored by the rendering platform. As this schema is purely for catalog display purposes, it is not recommended to send this value during search.' + type: string + name: + description: 'A human-readable string describing the heading under which the tags are to be displayed. Sometimes, the network policy may reserve some names for this property. Values outside the reserved values can be set by the BPP. However,the BAP may choose to rename or even ignore this value and render the output purely using code property, but it is recommended for BAPs to keep the name same to avoid confusion and provide consistency. As this schema is purely for catalog display purposes, it is not recommended to send this value during `search`.' + type: string + list: + description: 'An array of Tag objects listed under this group. This property can be set by BAPs during search to narrow the `search` and achieve more relevant results. When received during `on_search`, BAPs must render this list under the heading described by the `name` property of this schema.' + type: array + items: + description: 'Describes a tag. This is a simple key-value store which is used to contain extended metadata. This object can be added as a property to any schema to describe extended attributes. For BAPs, tags can be sent during search to optimize and filter search results. BPPs can use tags to index their catalog to allow better search functionality. Tags are sent by the BPP as part of the catalog response in the `on_search` callback. Tags are also meant for display purposes. Upon receiving a tag, BAPs are meant to render them as name-value pairs. This is particularly useful when rendering tabular information about a product or service.' + type: object + properties: + code: + description: 'The machine-readable name of the tag. The allowed values of this property can be published at three levels namely, a) Core specification, b) industry sector-specific adaptations, and c) Network-specific adaptations. Except core, each adaptation (sector or network) should prefix a unique namespace with the allowed value.' + type: string + name: + description: 'The human-readable name of the tag. This set by the BPP and rendered as-is by the BAP. Sometimes, the network policy may reserve some names for this property. Values outside the reserved values can be set by the BPP. However,the BAP may choose to rename or even ignore this value and render the output purely using the `code` property, but it is recommended for BAPs to keep the name same to avoid confusion and provide consistency.' + type: string + value: + description: The value of the tag. This set by the BPP and rendered as-is by the BAP. + type: string + display: + description: 'This value indicates if the tag is intended for display purposes. If set to `true`, then this tag must be displayed. If it is set to `false`, it should not be displayed. This value can override the group display value.' + type: boolean + - properties: + status: + enum: + - ACK + - NACK + required: + - ack + error: + description: 'Describes an error object that is returned by a BAP, BPP or BG as a response or callback to an action by another network participant. This object is sent when any request received by a network participant is unacceptable. This object can be sent either during Ack or with the callback.' + type: object + properties: + code: + type: string + description: 'Standard error code. For full list of error codes, refer to docs/protocol-drafts/BECKN-005-ERROR-CODES-DRAFT-01.md of this repo"' + paths: + type: string + description: Path to json schema generating the error. Used only during json schema validation errors + message: + type: string + description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user. + required: + - message + /get_rating_categories: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP requests BPP to provide the list of entities that can be rated on its system + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - properties: + action: + enum: + - get_rating_categories + required: + - action + required: + - context + responses: + default: + $ref: '#/paths/~1return_reasons/post/responses/default' + /rating_categories: + post: + tags: + - Beckn Application Platform (BPP) + description: BPP provides the list of entities that can be rated in its system to the BAP + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - properties: + action: + enum: + - rating_categories + required: + - action + message: + type: object + properties: + rating_categories: + type: array + items: + $ref: '#/components/schemas/Rating/properties/rating_category' + required: + - return_reasons + required: + - context + - message + responses: + default: + $ref: '#/paths/~1return_reasons/post/responses/default' +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using signing public key of the caller.

Format:

Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"' + schemas: + Context: + description: 'Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the BAP that sets the transaction context based on the consumer''s location and action on their UI. But sometimes, during unsolicited callbacks, the BPP also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the BAP and the BPP. The context object contains four types of fields.
  1. Demographic information about the transaction using fields like `domain`, `country`, and `region`.
  2. Addressing details like the sending and receiving platform''s ID and API URL.
  3. Interoperability information like the protocol version that implemented by the sender and,
  4. Transaction details like the method being called at the receiver''s endpoint, the transaction_id that represents an end-to-end user session at the BAP, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.
This object must be passed in every interaction between a BAP and a BPP. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions,' + type: object + properties: + domain: + description: Domain code that is relevant to this transaction context + allOf: + - description: 'Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network.' + location: + description: The location where the transaction is intended to be fulfilled. + allOf: + - description: The physical location of something + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Option/properties/descriptor' + map_url: + description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy. + type: string + format: uri + gps: + description: The GPS co-ordinates of this location. + allOf: + - description: Describes a GPS coordinate + type: string + pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$' + address: + description: The address of this location. + allOf: + - description: Describes a postal address. + type: string + city: + description: 'The city this location is, or is located within' + allOf: + - description: Describes a city + type: object + properties: + name: + description: Name of the city + type: string + code: + description: City code + type: string + district: + description: 'The state this location is, or is located within' + type: string + state: + description: 'The state this location is, or is located within' + allOf: + - description: A bounded geopolitical region of governance inside a country. + type: object + properties: + name: + type: string + description: Name of the state + code: + type: string + description: State code as per country or international standards + country: + description: 'The country this location is, or is located within' + allOf: + - description: Describes a country + type: object + properties: + name: + type: string + description: Name of the country + code: + type: string + description: Country code as per ISO 3166-1 and ISO 3166-2 format + area_code: + type: string + circle: + description: Describes a circular region of a specified radius centered at a specified GPS coordinate. + type: object + properties: + gps: + $ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/gps/allOf/0' + radius: + description: Describes a scalar + type: object + properties: + type: + type: string + enum: + - CONSTANT + - VARIABLE + value: + description: Describes a numerical value in decimal form + type: string + pattern: '[+-]?([0-9]*[.])?[0-9]+' + estimated_value: + $ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value' + computed_value: + $ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value' + range: + type: object + properties: + min: + $ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value' + max: + $ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value' + unit: + type: string + polygon: + description: The boundary polygon of this location + type: string + 3dspace: + description: The three dimensional region describing this location + type: string + rating: + description: The rating of this location + allOf: + - $ref: '#/components/schemas/Rating/properties/value' + action: + description: The Beckn protocol method being called by the sender and executed at the receiver. + type: string + version: + type: string + description: Version of transaction protocol being used by the sender. + bap_id: + description: Subscriber ID of the BAP + allOf: + - description: 'A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform.' + type: string + bap_uri: + description: Subscriber URL of the BAP for accepting callbacks from BPPs. + allOf: + - description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``. + type: string + format: uri + bpp_id: + description: Subscriber ID of the BPP + allOf: + - $ref: '#/components/schemas/Context/properties/bap_id/allOf/0' + bpp_uri: + description: Subscriber URL of the BPP for accepting calls from BAPs. + allOf: + - $ref: '#/components/schemas/Context/properties/bap_uri/allOf/0' + transaction_id: + description: 'This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The BPPs can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the BAP.' + type: string + format: uuid + message_id: + description: 'This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, BAPs need a common value to match an incoming callback from a BPP to an earlier call. This value can also be used to ignore duplicate messages coming from the BPP. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, BPPs must generate a new message_id.' + type: string + format: uuid + timestamp: + description: Time of request generation in RFC3339 format + type: string + format: date-time + key: + description: The encryption public key of the sender + type: string + ttl: + description: The duration in ISO8601 format after timestamp for which this message holds valid + type: string + Option: + description: Describes a selectable option + type: object + properties: + id: + type: string + descriptor: + description: Physical description of something. + type: object + properties: + name: + type: string + code: + type: string + short_desc: + type: string + long_desc: + type: string + additional_desc: + type: object + properties: + url: + type: string + content_type: + type: string + enum: + - text/plain + - text/html + - application/json + media: + type: array + items: + description: This object contains a url to a media file. + type: object + properties: + mimetype: + description: 'indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF''s RFC 6838' + type: string + url: + description: The URL of the file + type: string + format: uri + signature: + description: The digital signature of the file signed by the sender + type: string + dsa: + description: The signing algorithm used by the sender + type: string + images: + type: array + items: + description: Describes an image + type: object + properties: + url: + description: URL to the image. This can be a data url or an remote url + type: string + format: uri + size_type: + description: The size of the image. The network policy can define the default dimensions of each type + type: string + enum: + - xs + - sm + - md + - lg + - xl + - custom + width: + description: Width of the image in pixels + type: string + height: + description: Height of the image in pixels + type: string + Rating: + description: Describes the rating of an entity + type: object + properties: + rating_category: + description: Category of the entity being rated + type: string + enum: + - Item + - Order + - Fulfillment + - Provider + - Agent + - Support + id: + description: Id of the object being rated + type: string + value: + description: 'Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||.' + type: string diff --git a/docs/beckn-core/api/meta/components/index.yaml b/docs/beckn-core/api/meta/components/index.yaml new file mode 100644 index 0000000..ca6df55 --- /dev/null +++ b/docs/beckn-core/api/meta/components/index.yaml @@ -0,0 +1,97 @@ +openapi: 3.0.0 +info: + title: Beckn Protocol Meta API + description: This document contains all the meta API endpoints that are implemented by the network participants. The information returned from these endpoints typically contain cacheable information. + version: "1.0.0" +security: + - SubscriberAuth: [] +paths: + /get_cancellation_reasons: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP fetches the list of cancellation reasons from BPP + requestBody: + content: + application/json: + schema: + $ref: "./io/GetCancellationReasons.yaml" + responses: + default: + $ref: "./io/Response.yaml" + /cancellation_reasons: + post: + tags: + - Beckn Application Platform (BPP) + description: BPP sends cancellation reasons to BAP + requestBody: + content: + application/json: + schema: + $ref: "./io/CancellationReasons.yaml" + responses: + default: + $ref: "./io/Response.yaml" + /get_return_reasons: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP requests BPP to provide the list of return reasons + requestBody: + content: + application/json: + schema: + $ref: "./io/GetReturnReasons.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /return_reasons: + post: + tags: + - Beckn Application Platform (BPP) + description: BPP provides the list of return reasons to the BAP + requestBody: + content: + application/json: + schema: + $ref: "./io/ReturnReasons.yaml" + responses: + default: + $ref: "./io/Response.yaml" + /get_rating_categories: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP requests BPP to provide the list of entities that can be rated on its system + requestBody: + content: + application/json: + schema: + $ref: "./io/GetRatingCategories.yaml" + responses: + default: + $ref: "./io/Response.yaml" + /rating_categories: + post: + tags: + - Beckn Application Platform (BPP) + description: BPP provides the list of entities that can be rated in its system to the BAP + requestBody: + content: + application/json: + schema: + $ref: "./io/RatingCategories.yaml" + responses: + default: + $ref: "./io/Response.yaml" +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using signing public key of the caller.

Format:

Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"' + schemas: + $ref: "./schema/index.yaml" + diff --git a/docs/beckn-core/api/meta/components/io/CancellationReasons.yaml b/docs/beckn-core/api/meta/components/io/CancellationReasons.yaml new file mode 100644 index 0000000..e70c29c --- /dev/null +++ b/docs/beckn-core/api/meta/components/io/CancellationReasons.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - properties: + action: + enum: + - cancellation_reasons + required: + - action + message: + type: object + additionalProperties: false + properties: + cancellation_reasons: + type: array + items: + $ref: '../../../../schema/Option.yaml' + required: + - cancellation_reasons +required: + - context + - message diff --git a/docs/beckn-core/api/meta/components/io/GetCancellationReasons.yaml b/docs/beckn-core/api/meta/components/io/GetCancellationReasons.yaml new file mode 100644 index 0000000..9f78d94 --- /dev/null +++ b/docs/beckn-core/api/meta/components/io/GetCancellationReasons.yaml @@ -0,0 +1,14 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - properties: + action: + enum: + - get_cancellation_reasons + required: + - action +required: + - context diff --git a/docs/beckn-core/api/meta/components/io/GetRatingCategories.yaml b/docs/beckn-core/api/meta/components/io/GetRatingCategories.yaml new file mode 100644 index 0000000..4943fb1 --- /dev/null +++ b/docs/beckn-core/api/meta/components/io/GetRatingCategories.yaml @@ -0,0 +1,14 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - properties: + action: + enum: + - get_rating_categories + required: + - action +required: + - context diff --git a/docs/beckn-core/api/meta/components/io/GetReturnReasons.yaml b/docs/beckn-core/api/meta/components/io/GetReturnReasons.yaml new file mode 100644 index 0000000..b494823 --- /dev/null +++ b/docs/beckn-core/api/meta/components/io/GetReturnReasons.yaml @@ -0,0 +1,14 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - properties: + action: + enum: + - get_return_reasons + required: + - action +required: + - context diff --git a/docs/beckn-core/api/meta/components/io/RatingCategories.yaml b/docs/beckn-core/api/meta/components/io/RatingCategories.yaml new file mode 100644 index 0000000..15e345f --- /dev/null +++ b/docs/beckn-core/api/meta/components/io/RatingCategories.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - properties: + action: + enum: + - rating_categories + required: + - action + message: + type: object + additionalProperties: false + properties: + rating_categories: + type: array + items: + $ref: '../../../../schema/Rating.yaml#/properties/rating_category' + required: + - return_reasons +required: + - context + - message diff --git a/docs/beckn-core/api/meta/components/io/Response.yaml b/docs/beckn-core/api/meta/components/io/Response.yaml new file mode 100644 index 0000000..8b6380e --- /dev/null +++ b/docs/beckn-core/api/meta/components/io/Response.yaml @@ -0,0 +1,25 @@ +description: Acknowledgement of message received after successful validation of schema and signature +content: + application/json: + schema: + type: object + additionalProperties: false + properties: + message: + type: object + additionalProperties: false + properties: + ack: + allOf: + - $ref: "../../../../schema/Ack.yaml" + - properties: + status: + enum: + - ACK + - NACK + required: + - ack + error: + $ref: "../../../../schema/Error.yaml" + required: + - message \ No newline at end of file diff --git a/docs/beckn-core/api/meta/components/io/ReturnReasons.yaml b/docs/beckn-core/api/meta/components/io/ReturnReasons.yaml new file mode 100644 index 0000000..ce2ef93 --- /dev/null +++ b/docs/beckn-core/api/meta/components/io/ReturnReasons.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - properties: + action: + enum: + - return_reasons + required: + - action + message: + type: object + additionalProperties: false + properties: + return_reasons: + type: array + items: + $ref: '../../../../schema/Option.yaml' + required: + - return_reasons +required: + - context + - message diff --git a/docs/beckn-core/api/meta/components/schema/index.yaml b/docs/beckn-core/api/meta/components/schema/index.yaml new file mode 100644 index 0000000..426d4f8 --- /dev/null +++ b/docs/beckn-core/api/meta/components/schema/index.yaml @@ -0,0 +1,8 @@ +Context: + $ref: "../../../../schema/Context.yaml" + +Option: + $ref: "../../../../schema/Option.yaml" + +Rating: + $ref: "../../../../schema/Rating.yaml" \ No newline at end of file diff --git a/docs/beckn-core/api/registry/README.md b/docs/beckn-core/api/registry/README.md new file mode 100644 index 0000000..0e6977c --- /dev/null +++ b/docs/beckn-core/api/registry/README.md @@ -0,0 +1,97 @@ +# How to build the specification + +The full specification can be found at `api/transaction/build/transaction.yaml` + +This is an autogenerated file created by compiling two sets of components namely, + +1. APIs : found at `api/components/io` +2. Schema : found at `core/v0/api/components/schemas` + +The compilation flow is illustrated below + + + +# Compilation steps + +## Step 1 : Create the schema index file + +- Go to the ```core/v0/api/components/schemas/``` folder +- Create a file ```_index.yaml```. If already present, open it in a text editor +- It will contain a list of schema with $refs pointing to specific schema files in the current folder as shown below + +``` +Ack: + $ref: "./Ack.yaml" + +AddOn: + $ref: "./AddOn.yaml" +... +``` +- Ensure that each file in the ```schemas``` folder has an entry in this file. If it is not present, it will not be compiled + + +## Step 2 : Create the unresolved OpenAPI file + +- Go to the `core/v0/api/` folder +- In this folder, create a file - `core-unresolved.yaml`. If it is already present, open it in a text editor. +- In the file, you will see the following + +``` +openapi: 3.0.0 +info: + title: Beckn Protocol Core + description: Beckn Core API specification + version: "1.0.0" + +security: + - SubscriberAuth: [] + - GatewaySubscriberAuth: [] +paths: + /search: + post: + tags: + - Beckn Provider Platform (BPP) + - Beckn Gateway (BG) + description: BAP declares the customer's intent to buy/avail products or services + requestBody: + content: + application/json: + schema: + $ref : "./components/io/Search.yaml" + + responses: + default: + $ref: "./components/io/Response.yaml" + +... + +``` +- As you can see, the ```core-unresolved.yaml``` contains the unresolved Open API definitions with references to the APIs found in ```core/v0/api/components/io/``` +- Ensure each API definition in the ```core/v0/api/components/io/``` folder is referenced in this file. If it is not present, it will not be compiled. +- Once all API referencing is done, save this file and close it. + +## Install swagger CLI + +- Install the swagger command line tool using ```npm``` +- Note: you may need to use root privileges if installing it globally + +``` +sudo npm install -g swagger-cli +``` + +## Generate the resolved OpenAPI definition file + +- Go to the root directory of this project i.e ```protocol-specifications/``` +- Run the following command + +``` +swagger-cli bundle core/v0/api/core-unresolved.yaml --outfile core/v0/api/build/core.yaml --type yaml +``` + +- If the command runs successfully, you should see an output like this, + +``` +Created core/v0/api/build/core.yaml from core/v0/api/core-unresolved.yaml +``` + +- Commit the changes and push the updated code \ No newline at end of file diff --git a/docs/beckn-core/api/registry/build/README.md b/docs/beckn-core/api/registry/build/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/beckn-core/api/registry/build/registry.yaml b/docs/beckn-core/api/registry/build/registry.yaml new file mode 100644 index 0000000..8f1f377 --- /dev/null +++ b/docs/beckn-core/api/registry/build/registry.yaml @@ -0,0 +1,343 @@ +openapi: 3.0.0 +info: + title: Beckn Protocol Registry Infrastructure API + description: 'This document contains the API specification for the Registry infrastructure of a beckn-enabled network. The Registry API forms the trust layer of beckn protocol. When implemented, they enable creation of an infrastructure that allow trusted transactions between network participants to take place by means of digital signature authentication. The core infrastructure is called the Network Registry or simply, Registry. Any network participant that is listed on the registry can be assumed to have successfully passed the certfication and compliance process of the network, and hence be trusted to transact with.' + version: 1.0.0 +security: + - SubscriberAuth: [] +paths: + /lookup: + description: Look up platforms listed on the network registry. This is a protected endpoint only accessible to network participants that have subscribed to the network (i.e Subscribers). Any subscriber can query the Registry by sending a `Lookup` object. The Registry will respond with all the platforms that match the lookup parameters. + post: + tags: + - Registry + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Subscription' + responses: + default: + description: Array of subscribers matching the lookup request attributes + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Subscription' + /subscribe: + description: 'Subscribe to a network. This endpoint allows registered network participants (a.k.a Subscribers), to update their subscription details like `domain`, `location`, `signing_public_key`, `encr_public_key` on the registry. The fields that can be updated can vary from network to network. Every network policy must contain the fields that can be updated for each type of subscriber. For example, the network policy may allow BAPs and BPPs to update all fields, but BGs may not be allowed to update any field except the public keys.' + post: + tags: + - Registry + requestBody: + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Subscription' + - properties: + nonce: + description: A randomly generated uuid nonce value + type: string + format: uuid + responses: + default: + description: The Registry returns the status of the subscription request. + content: + application/json: + schema: + type: object + properties: + status: + type: string + enum: + - UNDER_SUBSCRIPTION + /on_subscribe: + description: 'This endpoint is implemented by all platforms that have successfully passed the certification and compliance requirements on a network. In this endpoint, the Subscriber receives an encrypted challenge string generated by the Registry to verify the subscription details of the Network Participant sent during the `subscribe` call. During this call, Registry also validates the SSL certificate of Subscriber. If the SSL certificate is invalid, the Registry will update the subscriber’s status = INVALID_SSL and call the Subscriber''s `on_subscribe` endpoint again. Anytime the state of the Subscriber changes in the registry, the Registry can make an unsolicited call to the subscriber''s `on_subscribe` endpoint. This request must be digitally signed by the Registry. The Registry''s public key must be published at a publicly accessible trusted location so that the Subscribers can save it on their systems.' + post: + tags: + - 'Subscriber (BAP, BPP, BG)' + requestBody: + content: + application/json: + schema: + type: object + properties: + status: + description: The current status of the Registrant + type: string + enum: + - INITIATED + - UNDER_SUBSCRIPTION + - SUBSCRIBED + - INVALID_SSL + - UNSUBSCRIBED + challenge: + type: string + description: A random string generated by the registry encrypted with the subscriber's encryption public key + required: + - challenge + responses: + default: + description: Network Participant decrypts the challenge string using its private key and returns the decrypted value. + content: + application/json: + schema: + type: object + properties: + answer: + description: Decrypted challenge string + type: string + required: + - answer +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using signing public key of the caller.

Format:

Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"' + schemas: + Gps: + description: Describes a GPS coordinate + type: string + pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$' + Location: + description: The physical location of something + type: object + properties: + id: + type: string + descriptor: + description: Physical description of something. + type: object + properties: + name: + type: string + code: + type: string + short_desc: + type: string + long_desc: + type: string + additional_desc: + type: object + properties: + url: + type: string + content_type: + type: string + enum: + - text/plain + - text/html + - application/json + media: + type: array + items: + description: This object contains a url to a media file. + type: object + properties: + mimetype: + description: 'indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF''s RFC 6838' + type: string + url: + description: The URL of the file + type: string + format: uri + signature: + description: The digital signature of the file signed by the sender + type: string + dsa: + description: The signing algorithm used by the sender + type: string + images: + type: array + items: + description: Describes an image + type: object + properties: + url: + description: URL to the image. This can be a data url or an remote url + type: string + format: uri + size_type: + description: The size of the image. The network policy can define the default dimensions of each type + type: string + enum: + - xs + - sm + - md + - lg + - xl + - custom + width: + description: Width of the image in pixels + type: string + height: + description: Height of the image in pixels + type: string + map_url: + description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy. + type: string + format: uri + gps: + description: The GPS co-ordinates of this location. + allOf: + - $ref: '#/components/schemas/Gps' + address: + description: The address of this location. + allOf: + - description: Describes a postal address. + type: string + city: + description: 'The city this location is, or is located within' + allOf: + - description: Describes a city + type: object + properties: + name: + description: Name of the city + type: string + code: + description: City code + type: string + district: + description: 'The state this location is, or is located within' + type: string + state: + description: 'The state this location is, or is located within' + allOf: + - description: A bounded geopolitical region of governance inside a country. + type: object + properties: + name: + type: string + description: Name of the state + code: + type: string + description: State code as per country or international standards + country: + description: 'The country this location is, or is located within' + allOf: + - description: Describes a country + type: object + properties: + name: + type: string + description: Name of the country + code: + type: string + description: Country code as per ISO 3166-1 and ISO 3166-2 format + area_code: + type: string + circle: + description: Describes a circular region of a specified radius centered at a specified GPS coordinate. + type: object + properties: + gps: + $ref: '#/components/schemas/Gps' + radius: + $ref: '#/components/schemas/Scalar' + polygon: + description: The boundary polygon of this location + type: string + 3dspace: + description: The three dimensional region describing this location + type: string + rating: + description: The rating of this location + allOf: + - description: 'Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||.' + type: string + Scalar: + description: Describes a scalar + type: object + properties: + type: + type: string + enum: + - CONSTANT + - VARIABLE + value: + description: Describes a numerical value in decimal form + type: string + pattern: '[+-]?([0-9]*[.])?[0-9]+' + estimated_value: + $ref: '#/components/schemas/Scalar/properties/value' + computed_value: + $ref: '#/components/schemas/Scalar/properties/value' + range: + type: object + properties: + min: + $ref: '#/components/schemas/Scalar/properties/value' + max: + $ref: '#/components/schemas/Scalar/properties/value' + unit: + type: string + Subscriber: + description: A unique operational configuration of a trusted platform on a network. + type: object + properties: + subscriber_id: + description: 'A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform.' + type: string + url: + description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``. + type: string + format: uri + type: + description: The role of subscriber on the network + type: string + enum: + - BAP + - BPP + - BG + domain: + description: Operating industry domain that this subscriber offers its products or services in. A single subscriber can operate in multiple domains. Each operating domain must have a unique subscriber object entry in the req + allOf: + - description: 'Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network.' + location: + description: The region of operation of this subscriber + allOf: + - $ref: '#/components/schemas/Location' + Subscription: + description: Subscription details of a Network Participant. + allOf: + - $ref: '#/components/schemas/Subscriber' + - properties: + key_id: + description: A unique ID of the subscription entry in a registry. + type: string + format: uuid + signing_public_key: + description: The signing public key of the subscriber + type: string + encr_public_key: + description: The encryption public key of the subscriber + type: string + valid_from: + description: Date-time which the signing and encryption keys are valid from + type: string + format: date-time + valid_until: + description: Time till which the signing and encryption keys are valid + type: string + format: date-time + status: + description: Status of the subscription + type: string + enum: + - INITIATED + - UNDER_SUBSCRIPTION + - SUBSCRIBED + - EXPIRED + - UNSUBSCRIBED + - INVALID_SSL + created: + type: string + format: date-time + updated: + type: string + format: date-time diff --git a/docs/beckn-core/api/registry/components/index.yaml b/docs/beckn-core/api/registry/components/index.yaml new file mode 100644 index 0000000..6319cc5 --- /dev/null +++ b/docs/beckn-core/api/registry/components/index.yaml @@ -0,0 +1,58 @@ +openapi: 3.0.0 +info: + title: Beckn Protocol Registry Infrastructure API + description: This document contains the API specification for the Registry infrastructure of a beckn-enabled network. The Registry API forms the trust layer of beckn protocol. When implemented, they enable creation of an infrastructure that allow trusted transactions between network participants to take place by means of digital signature authentication. The core infrastructure is called the Network Registry or simply, Registry. Any network participant that is listed on the registry can be assumed to have successfully passed the certfication and compliance process of the network, and hence be trusted to transact with. + version: "1.0.0" +security: + - SubscriberAuth: [] +paths: + /lookup: + description: Look up platforms listed on the network registry. This is a protected endpoint only accessible to network participants that have subscribed to the network (i.e Subscribers). Any subscriber can query the Registry by sending a `Lookup` object. The Registry will respond with all the platforms that match the lookup parameters. + post: + tags: + - Registry + requestBody: + content: + application/json: + schema: + $ref : "./io/Lookup.yaml" + responses: + default: + $ref: "./io/LookupResponse.yaml" + /subscribe: + description: Subscribe to a network. This endpoint allows registered network participants (a.k.a Subscribers), to update their subscription details like `domain`, `location`, `signing_public_key`, `encr_public_key` on the registry. The fields that can be updated can vary from network to network. Every network policy must contain the fields that can be updated for each type of subscriber. For example, the network policy may allow BAPs and BPPs to update all fields, but BGs may not be allowed to update any field except the public keys. + post: + tags: + - Registry + requestBody: + content: + application/json: + schema: + $ref: "./io/Subscribe.yaml" + responses: + default: + $ref: "./io/SubscriptionResponse.yaml" + + /on_subscribe: + description: This endpoint is implemented by all platforms that have successfully passed the certification and compliance requirements on a network. In this endpoint, the Subscriber receives an encrypted challenge string generated by the Registry to verify the subscription details of the Network Participant sent during the `subscribe` call. During this call, Registry also validates the SSL certificate of Subscriber. If the SSL certificate is invalid, the Registry will update the subscriber’s status = INVALID_SSL and call the Subscriber's `on_subscribe` endpoint again. Anytime the state of the Subscriber changes in the registry, the Registry can make an unsolicited call to the subscriber's `on_subscribe` endpoint. This request must be digitally signed by the Registry. The Registry's public key must be published at a publicly accessible trusted location so that the Subscribers can save it on their systems. + post: + tags: + - Subscriber (BAP, BPP, BG) + requestBody: + content: + application/json: + schema: + $ref: "./io/OnSubscribe.yaml" + responses: + default: + $ref: "./io/OnSubscribeResponse.yaml" +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using signing public key of the caller.

Format:

Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"' + schemas: + $ref: "./schema/index.yaml" + diff --git a/docs/beckn-core/api/registry/components/io/Lookup.yaml b/docs/beckn-core/api/registry/components/io/Lookup.yaml new file mode 100644 index 0000000..eccbda7 --- /dev/null +++ b/docs/beckn-core/api/registry/components/io/Lookup.yaml @@ -0,0 +1 @@ +$ref: "../../../../schema/Subscription.yaml" diff --git a/docs/beckn-core/api/registry/components/io/LookupResponse.yaml b/docs/beckn-core/api/registry/components/io/LookupResponse.yaml new file mode 100644 index 0000000..2d7c988 --- /dev/null +++ b/docs/beckn-core/api/registry/components/io/LookupResponse.yaml @@ -0,0 +1,7 @@ +description: Array of subscribers matching the lookup request attributes +content: + application/json: + schema: + type: array + items: + $ref: '../../../../schema/Subscription.yaml' \ No newline at end of file diff --git a/docs/beckn-core/api/registry/components/io/OnSubscribe.yaml b/docs/beckn-core/api/registry/components/io/OnSubscribe.yaml new file mode 100644 index 0000000..8880236 --- /dev/null +++ b/docs/beckn-core/api/registry/components/io/OnSubscribe.yaml @@ -0,0 +1,16 @@ +type: object +properties: + status: + description: The current status of the Registrant + type: string + enum: + - INITIATED + - UNDER_SUBSCRIPTION + - SUBSCRIBED + - INVALID_SSL + - UNSUBSCRIBED + challenge: + type: string + description: A random string generated by the registry encrypted with the subscriber's encryption public key +required: + - challenge \ No newline at end of file diff --git a/docs/beckn-core/api/registry/components/io/OnSubscribeResponse.yaml b/docs/beckn-core/api/registry/components/io/OnSubscribeResponse.yaml new file mode 100644 index 0000000..1b6cfb1 --- /dev/null +++ b/docs/beckn-core/api/registry/components/io/OnSubscribeResponse.yaml @@ -0,0 +1,11 @@ +description: Network Participant decrypts the challenge string using its private key and returns the decrypted value. +content: + application/json: + schema: + type: object + properties: + answer: + description: Decrypted challenge string + type: string + required: + - answer \ No newline at end of file diff --git a/docs/beckn-core/api/registry/components/io/README.md b/docs/beckn-core/api/registry/components/io/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/beckn-core/api/registry/components/io/Register.yaml b/docs/beckn-core/api/registry/components/io/Register.yaml new file mode 100644 index 0000000..cdaf8dc --- /dev/null +++ b/docs/beckn-core/api/registry/components/io/Register.yaml @@ -0,0 +1,7 @@ +allOf: + - $ref: "../../../../schema/Subscriber.yaml" + - properties: + nonce: + type: string + xinput_response: + $ref: "../../../../schema/XInputResponse.yaml" diff --git a/docs/beckn-core/api/registry/components/io/Subscribe.yaml b/docs/beckn-core/api/registry/components/io/Subscribe.yaml new file mode 100644 index 0000000..7528e3c --- /dev/null +++ b/docs/beckn-core/api/registry/components/io/Subscribe.yaml @@ -0,0 +1,7 @@ +allOf: + - $ref: "../../../../schema/Subscription.yaml" + - properties: + nonce: + description: A randomly generated uuid nonce value + type: string + format: uuid \ No newline at end of file diff --git a/docs/beckn-core/api/registry/components/io/SubscriptionResponse.yaml b/docs/beckn-core/api/registry/components/io/SubscriptionResponse.yaml new file mode 100644 index 0000000..6d0c42e --- /dev/null +++ b/docs/beckn-core/api/registry/components/io/SubscriptionResponse.yaml @@ -0,0 +1,10 @@ +description: The Registry returns the status of the subscription request. +content: + application/json: + schema: + type: object + properties: + status: + type: string + enum: + - UNDER_SUBSCRIPTION \ No newline at end of file diff --git a/docs/beckn-core/api/registry/components/schema/index.yaml b/docs/beckn-core/api/registry/components/schema/index.yaml new file mode 100644 index 0000000..38335df --- /dev/null +++ b/docs/beckn-core/api/registry/components/schema/index.yaml @@ -0,0 +1,15 @@ +Gps: + $ref: "../../../../schema/Gps.yaml" + +Location: + $ref: "../../../../schema/Location.yaml" + +Scalar: + $ref: "../../../../schema/Scalar.yaml" + +Subscriber: + $ref: "../../../../schema/Subscriber.yaml" + +Subscription: + $ref: "../../../../schema/Subscription.yaml" + diff --git a/docs/beckn-core/api/transaction/README.md b/docs/beckn-core/api/transaction/README.md new file mode 100644 index 0000000..ddaae61 --- /dev/null +++ b/docs/beckn-core/api/transaction/README.md @@ -0,0 +1,97 @@ +# How to build the specification + +**Note:** All folders mentioned here are relative to the root folder ```protocol-specifications``` + +The full specification can be found at `api/transaction/build/transaction.yaml` + +This is an autogenerated file created by compiling two sets of components namely, + +1. APIs : found at `api/components/io/` +2. Schema : found at `api/components/schemas/` + +The compilation flow is illustrated below + + + +# Compilation steps + +## Step 1 : Create the schema index file + +- Go to the ```core/v0/api/components/schemas/``` folder +- Create a file ```index.yaml```. If already present, open it in a text editor +- It will contain a list of schema with $refs pointing to specific schema files in the ```schema/``` folder as shown below + +``` +Ack: + $ref: "../../../../Ack.yaml" + +AddOn: + $ref: "../../../../AddOn.yaml" +... +``` +- Ensure that each file in the ```schemas``` folder has an entry in this file. If it is not present, it will not be compiled + + +## Step 2 : Create the unresolved OpenAPI file + +- Go to the `api/transaction/components/` folder +- In this folder, create a file - `index.yaml`. If it is already present, open it in a text editor. +- In the file, you will see the following + +``` +openapi: 3.0.0 +info: + title: Beckn Protocol Core + description: Beckn Core API specification + version: "1.0.0" + +security: + - SubscriberAuth: [] +paths: + /search: + post: + tags: + - Beckn Provider Platform (BPP) + - Beckn Gateway (BG) + description: BAP declares the customer's intent to buy/avail products or services + requestBody: + content: + application/json: + schema: + $ref : "./io/Search.yaml" + + responses: + default: + $ref: "./io/Response.yaml" + +... + +``` +- As you can see, the ```api/transaction/components/index.yaml``` contains the unresolved Open API definitions with references to the schemas found in ```core/v0/api/components/io/``` +- Ensure each API definition in the ```api/transaction/components/io/``` folder is referenced in this file. If it is not present, it will not be compiled. +- Once all API referencing is done, save this file and close it. + +## Install swagger CLI + +- Install the swagger command line tool using ```npm``` (Note: you may need to use root privileges if installing it globally) + +``` +sudo npm install -g swagger-cli +``` + +## Generate the resolved OpenAPI definition file + +- Go to the root directory of this project +- Run the following command + +``` +swagger-cli bundle api/transaction/components/index.yaml --outfile api/transaction/build/transaction.yaml --type yaml +``` + +- If the command runs successfully, you should see an output like this, + +``` +Created api/transaction/build/transaction.yaml from api/transaction/components/index.yaml +``` + +- Commit the changes and push the updated code \ No newline at end of file diff --git a/docs/beckn-core/api/transaction/build/transaction.yaml b/docs/beckn-core/api/transaction/build/transaction.yaml new file mode 100644 index 0000000..32ff539 --- /dev/null +++ b/docs/beckn-core/api/transaction/build/transaction.yaml @@ -0,0 +1,2187 @@ +openapi: 3.0.0 +info: + title: Beckn Protocol Core + description: Beckn Core Transaction API specification + version: 1.1.0 +security: + - SubscriberAuth: [] +paths: + /search: + post: + tags: + - Beckn Provider Platform (BPP) + - Beckn Gateway (BG) + description: BAP declares the customer's intent to buy/avail products or services + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - search + message: + type: object + properties: + intent: + $ref: '#/components/schemas/Intent' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /select: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP declares the customer's cart (or equivalent) created by selecting objects from the catalog + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - select + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /init: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - init + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + default: + description: Acknowledgement of message received after successful validation of schema and signature + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + allOf: + - $ref: '#/components/schemas/Ack' + - properties: + status: + enum: + - ACK + - NACK + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /confirm: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - confirm + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /status: + post: + tags: + - Beckn Provider Platform (BPP) + description: Fetch the latest order object + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - status + required: + - action + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + required: + - order_id + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /track: + post: + tags: + - Beckn Provider Platform (BPP) + description: Track an active order + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - track + required: + - action + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + callback_url: + type: string + format: uri + required: + - order_id + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /cancel: + post: + tags: + - Beckn Provider Platform (BPP) + description: Cancel an order + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - cancel + required: + - action + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + cancellation_reason_id: + $ref: '#/components/schemas/Option/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + required: + - order_id + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /update: + post: + tags: + - Beckn Provider Platform (BPP) + description: Remove object + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - update + required: + - action + message: + type: object + properties: + update_target: + description: 'Comma separated values of order objects being updated. For example: ```"update_target":"item,billing,fulfillment"```' + type: string + order: + description: Updated order object + allOf: + - $ref: '#/components/schemas/Order' + required: + - update_target + - order + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /rating: + post: + tags: + - Beckn Provider Platform (BPP) + description: Provide feedback on a service + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - rating + required: + - action + message: + type: object + properties: + ratings: + type: array + items: + $ref: '#/components/schemas/Rating' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /support: + post: + tags: + - Beckn Provider Platform (BPP) + description: Contact support + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - support + required: + - action + message: + type: object + properties: + support: + $ref: '#/components/schemas/Support' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_search: + post: + tags: + - Beckn Application Platform (BAP) + - Beckn Gateway (BG) + description: BPP sends its catalog in response to a search request. + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_search + required: + - action + message: + type: object + properties: + catalog: + $ref: '#/components/schemas/Catalog' + required: + - catalog + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_select: + post: + tags: + - Beckn Application Platform (BAP) + description: Send draft order object with quoted price for selected items + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_select + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_init: + post: + tags: + - Beckn Application Platform (BAP) + description: Send order object with payment details updated + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_init + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_confirm: + post: + tags: + - Beckn Application Platform (BAP) + description: Send active order object + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_confirm + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_track: + post: + tags: + - Beckn Application Platform (BAP) + description: Send tracking details of an active order + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_track + required: + - action + message: + type: object + properties: + tracking: + $ref: '#/components/schemas/Tracking' + required: + - tracking + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_cancel: + post: + tags: + - Beckn Application Platform (BAP) + description: Send cancellation request_id with reasons list in case of cancellation request. Else send cancelled order object + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_cancel + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_update: + post: + tags: + - Beckn Application Platform (BAP) + description: Returns updated service with updated runtime object + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_update + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_status: + post: + tags: + - Beckn Application Platform (BAP) + description: Fetch the status of a Service + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_status + required: + - action + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_rating: + post: + tags: + - Beckn Application Platform (BAP) + description: Provide feedback on a service + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_rating + required: + - action + message: + type: object + properties: + feedback_form: + description: A feedback form to allow the user to provide additional information on the rating provided + allOf: + - $ref: '#/components/schemas/XInput' + error: + $ref: '#/components/schemas/Error' + required: + - context + - message + responses: + default: + $ref: '#/paths/~1init/post/responses/default' + /on_support: + post: + tags: + - Beckn Application Platform (BAP) + description: Contact Support + requestBody: + content: + application/json: + schema: + type: object + properties: + context: + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + enum: + - on_support + required: + - action + message: + type: object + properties: + support: + $ref: '#/components/schemas/Support' + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + default: + $ref: '#/paths/~1init/post/responses/default' +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using BAP or BPP subscriber''s signing public key.

Format:

Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"' + schemas: + Ack: + description: 'Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack must be returned in the same session. Every API call to a BPP must be responded to with an Ack whether the BPP intends to respond with a callback or not. This has one property called `status` that indicates the status of the Acknowledgement.' + type: object + properties: + status: + type: string + description: 'The status of the acknowledgement. If the request passes the validation criteria of the BPP, then this is set to ACK. If a BPP responds with status = `ACK` to a request, it is required to respond with a callback. If the request fails the validation criteria, then this is set to NACK. Additionally, if a BPP does not intend to respond with a callback even after the request meets the validation criteria, it should set this value to `NACK`.' + enum: + - ACK + - NACK + tags: + description: A list of tags containing any additional information sent along with the Acknowledgement. + type: array + items: + $ref: '#/components/schemas/TagGroup' + AddOn: + description: Describes an additional item offered as a value-addition to a product or service. This does not exist independently in a catalog and is always associated with an item. + type: object + properties: + id: + description: Provider-defined ID of the add-on + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + price: + $ref: '#/components/schemas/Price' + Address: + description: Describes a postal address. + type: string + Agent: + type: object + description: 'Describes the direct performer, driver or executor that fulfills an order. It is usually a person. But in some rare cases, it could be a non-living entity like a drone, or a bot. Some examples of agents are Doctor in the healthcare sector, a driver in the mobility sector, or a delivery person in the logistics sector. This object can be set at any stage of the order lifecycle. This can be set at the discovery stage when the BPP wants to provide details on the agent fulfilling the order, like in healthcare, where the doctor''s name appears during search. This object can also used to search for a particular person that the customer wants fulfilling an order. Sometimes, this object gets instantiated after the order is confirmed, like in the case of on-demand taxis, where the driver is assigned after the user confirms the ride.' + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + organization: + $ref: '#/components/schemas/Organization' + rating: + $ref: '#/components/schemas/Rating/properties/value' + Authorization: + description: 'Describes an authorization mechanism used to start or end the fulfillment of an order. For example, in the mobility sector, the driver may require a one-time password to initiate the ride. In the healthcare sector, a patient may need to provide a password to open a video conference link during a teleconsultation.' + type: object + properties: + type: + description: Type of authorization mechanism used. The allowed values for this field can be published as part of the network policy. + type: string + token: + description: 'Token used for authorization. This is typically generated at the BPP. The BAP can send this value to the user via any channel that it uses to authenticate the user like SMS, Email, Push notification, or in-app rendering.' + type: string + valid_from: + description: Timestamp in RFC3339 format from which token is valid + type: string + format: date-time + valid_to: + description: Timestamp in RFC3339 format until which token is valid + type: string + format: date-time + status: + description: Status of the token + type: string + Billing: + description: 'Describes the billing details of an entity.
This has properties like name,organization,address,email,phone,time,tax_number, created_at,updated_at' + type: object + properties: + name: + description: Name of the billable entity + type: string + organization: + description: Details of the organization being billed. + allOf: + - $ref: '#/components/schemas/Organization' + address: + description: The address of the billable entity + allOf: + - $ref: '#/components/schemas/Address' + state: + description: The state where the billable entity resides. This is important for state-level tax calculation + allOf: + - $ref: '#/components/schemas/State' + city: + description: The city where the billable entity resides. + allOf: + - $ref: '#/components/schemas/City' + email: + description: Email address where the bill is sent to + type: string + format: email + phone: + description: Phone number of the billable entity + type: string + time: + description: Details regarding the billing period + allOf: + - $ref: '#/components/schemas/Time' + tax_id: + description: ID of the billable entity as recognized by the taxation authority + type: string + Cancellation: + description: Describes a cancellation event + type: object + properties: + time: + description: Date-time when the order was cancelled by the buyer + type: string + format: date-time + cancelled_by: + type: string + enum: + - CONSUMER + - PROVIDER + reason: + description: The reason for cancellation + allOf: + - $ref: '#/components/schemas/Option' + additional_description: + description: Any additional information regarding the nature of cancellation + allOf: + - $ref: '#/components/schemas/Descriptor' + CancellationTerm: + description: Describes the cancellation terms of an item or an order. This can be referenced at an item or order level. Item-level cancellation terms can override the terms at the order level. + type: object + properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: '#/components/schemas/FulfillmentState' + reason_required: + description: Indicates whether a reason is required to cancel the order + type: boolean + cancel_by: + description: Information related to the time of cancellation. + allOf: + - $ref: '#/components/schemas/Time' + cancellation_fee: + $ref: '#/components/schemas/Fee' + xinput: + $ref: '#/components/schemas/XInput' + external_ref: + $ref: '#/components/schemas/MediaFile' + Catalog: + description: 'Describes the products or services offered by a BPP. This is typically sent as the response to a search intent from a BAP. The payment terms, offers and terms of fulfillment supported by the BPP can also be included here. The BPP can show hierarchical nature of products/services in its catalog using the parent_category_id in categories. The BPP can also send a ttl (time to live) in the context which is the duration for which a BAP can cache the catalog and use the cached catalog.
This has properties like bbp/descriptor,bbp/categories,bbp/fulfillments,bbp/payments,bbp/offers,bbp/providers and exp
This is used in the following situations.
  • This is typically used in the discovery stage when the BPP sends the details of the products and services it offers as response to a search intent from the BAP.
' + type: object + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + fulfillments: + description: Fulfillment modes offered at the BPP level. This is used when a BPP itself offers fulfillments on behalf of the providers it has onboarded. + type: array + items: + $ref: '#/components/schemas/Fulfillment' + payments: + description: Payment terms offered by the BPP for all transactions. This can be overriden at the provider level. + type: array + items: + $ref: '#/components/schemas/Payment' + offers: + description: Offers at the BPP-level. This is common across all providers onboarded by the BPP. + type: array + items: + $ref: '#/components/schemas/Offer' + providers: + type: array + items: + $ref: '#/components/schemas/Provider' + exp: + description: Timestamp after which catalog will expire + type: string + format: date-time + ttl: + description: Duration in seconds after which this catalog will expire + type: string + Category: + description: A label under which a collection of items can be grouped. + type: object + properties: + id: + description: ID of the category + type: string + parent_category_id: + $ref: '#/components/schemas/Category/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + time: + $ref: '#/components/schemas/Time' + ttl: + description: Time to live for an instance of this schema + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Circle: + description: Describes a circular region of a specified radius centered at a specified GPS coordinate. + type: object + properties: + gps: + $ref: '#/components/schemas/Gps' + radius: + $ref: '#/components/schemas/Scalar' + City: + description: Describes a city + type: object + properties: + name: + description: Name of the city + type: string + code: + description: City code + type: string + Contact: + description: Describes the contact information of an entity + type: object + properties: + phone: + type: string + email: + type: string + jcard: + type: object + description: A Jcard object as per draft-ietf-jcardcal-jcard-03 specification + Context: + description: 'Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the BAP that sets the transaction context based on the consumer''s location and action on their UI. But sometimes, during unsolicited callbacks, the BPP also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the BAP and the BPP. The context object contains four types of fields.
  1. Demographic information about the transaction using fields like `domain`, `country`, and `region`.
  2. Addressing details like the sending and receiving platform''s ID and API URL.
  3. Interoperability information like the protocol version that implemented by the sender and,
  4. Transaction details like the method being called at the receiver''s endpoint, the transaction_id that represents an end-to-end user session at the BAP, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.
This object must be passed in every interaction between a BAP and a BPP. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions,' + type: object + properties: + domain: + description: Domain code that is relevant to this transaction context + allOf: + - $ref: '#/components/schemas/Domain/properties/code' + location: + description: The location where the transaction is intended to be fulfilled. + allOf: + - $ref: '#/components/schemas/Location' + action: + description: The Beckn protocol method being called by the sender and executed at the receiver. + type: string + version: + type: string + description: Version of transaction protocol being used by the sender. + bap_id: + description: Subscriber ID of the BAP + allOf: + - description: 'A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform.' + type: string + bap_uri: + description: Subscriber URL of the BAP for accepting callbacks from BPPs. + allOf: + - description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``. + type: string + format: uri + bpp_id: + description: Subscriber ID of the BPP + allOf: + - $ref: '#/components/schemas/Context/properties/bap_id/allOf/0' + bpp_uri: + description: Subscriber URL of the BPP for accepting calls from BAPs. + allOf: + - $ref: '#/components/schemas/Context/properties/bap_uri/allOf/0' + transaction_id: + description: 'This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The BPPs can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the BAP.' + type: string + format: uuid + message_id: + description: 'This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, BAPs need a common value to match an incoming callback from a BPP to an earlier call. This value can also be used to ignore duplicate messages coming from the BPP. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, BPPs must generate a new message_id.' + type: string + format: uuid + timestamp: + description: Time of request generation in RFC3339 format + type: string + format: date-time + key: + description: The encryption public key of the sender + type: string + ttl: + description: The duration in ISO8601 format after timestamp for which this message holds valid + type: string + max_callbacks: + description: Number of callbacks expected. If this value is -1, then there is no limit. If it is 0, then no callbacks are expected. + type: integer + minimum: -1 + Country: + description: Describes a country + type: object + properties: + name: + type: string + description: Name of the country + code: + type: string + description: Country code as per ISO 3166-1 and ISO 3166-2 format + Credential: + description: Describes a credential of an entity - Person or Organization + type: object + properties: + id: + type: string + type: + type: string + default: VerifiableCredential + url: + description: URL of the credential + type: string + format: uri + Customer: + description: Describes a customer buying/availing a product or a service + type: object + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + DecimalValue: + description: Describes a numerical value in decimal form + type: string + pattern: '[+-]?([0-9]*[.])?[0-9]+' + Descriptor: + description: Physical description of something. + type: object + properties: + name: + type: string + code: + type: string + short_desc: + type: string + long_desc: + type: string + additional_desc: + type: object + properties: + url: + type: string + content_type: + type: string + enum: + - text/plain + - text/html + - application/json + media: + type: array + items: + $ref: '#/components/schemas/MediaFile' + images: + type: array + items: + $ref: '#/components/schemas/Image' + Domain: + description: 'Described the industry sector or sub-sector. The network policy should contain codes for all the industry sectors supported by the network. Domains can be created in varying levels of granularity. The granularity of a domain can be decided by the participants of the network. Too broad domains will result in irrelevant search broadcast calls to BPPs that don''t have services supporting the domain. Too narrow domains will result in a large number of registry entries for each BPP. It is recommended that network facilitators actively collaborate with various working groups and network participants to carefully choose domain codes keeping in mind relevance, performance, and opportunity cost. It is recommended that networks choose broad domains like mobility, logistics, healthcare etc, and progressively granularize them as and when the number of network participants for each domain grows large.' + type: object + properties: + name: + description: Name of the domain + type: string + code: + description: 'Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network.' + additional_info: + description: A url that contains addtional information about that domain. + allOf: + - $ref: '#/components/schemas/MediaFile' + Duration: + description: Describes duration as per ISO8601 format + type: string + Error: + description: 'Describes an error object that is returned by a BAP, BPP or BG as a response or callback to an action by another network participant. This object is sent when any request received by a network participant is unacceptable. This object can be sent either during Ack or with the callback.' + type: object + properties: + code: + type: string + description: 'Standard error code. For full list of error codes, refer to docs/protocol-drafts/BECKN-005-ERROR-CODES-DRAFT-01.md of this repo"' + paths: + type: string + description: Path to json schema generating the error. Used only during json schema validation errors + message: + type: string + description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user. + Fee: + description: A fee applied on a particular entity + type: object + properties: + percentage: + description: Percentage of a value + allOf: + - $ref: '#/components/schemas/DecimalValue' + amount: + description: A fixed value + allOf: + - $ref: '#/components/schemas/Price' + Form: + description: Describes a form + type: object + properties: + url: + description: 'The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form.' + type: string + format: uri + data: + description: The form submission data + type: object + additionalProperties: + type: string + mime_type: + description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. + type: string + enum: + - text/html + - application/xml + submission_id: + type: string + format: uuid + Fulfillment: + description: Describes how a an order will be rendered/fulfilled to the end-customer + type: object + properties: + id: + description: Unique reference ID to the fulfillment of an order + type: string + type: + description: 'A code that describes the mode of fulfillment. This is typically set when there are multiple ways an order can be fulfilled. For example, a retail order can be fulfilled either via store pickup or a home delivery. Similarly, a medical consultation can be provided either in-person or via tele-consultation. The network policy must publish standard fulfillment type codes for the different modes of fulfillment.' + type: string + rateable: + description: Whether the fulfillment can be rated or not + type: boolean + rating: + description: The rating value of the fulfullment service. + allOf: + - $ref: '#/components/schemas/Rating/properties/value' + state: + description: The current state of fulfillment. The BPP must set this value whenever the state of the order fulfillment changes and fire an unsolicited `on_status` call. + allOf: + - $ref: '#/components/schemas/FulfillmentState' + tracking: + type: boolean + description: Indicates whether the fulfillment allows tracking + default: false + customer: + description: The person that will ultimately receive the order + allOf: + - $ref: '#/components/schemas/Customer' + agent: + $ref: '#/components/schemas/Agent' + contact: + $ref: '#/components/schemas/Contact' + vehicle: + $ref: '#/components/schemas/Vehicle' + stops: + description: The list of logical stops encountered during the fulfillment of an order. + type: array + items: + $ref: '#/components/schemas/Stop' + path: + description: The physical path taken by the agent that can be rendered on a map. The allowed format of this property can be set by the network. + type: string + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + FulfillmentState: + description: Describes the state of fulfillment + type: object + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + updated_at: + type: string + format: date-time + updated_by: + type: string + description: ID of entity which changed the state + Gps: + description: Describes a GPS coordinate + type: string + pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$' + Image: + description: Describes an image + type: object + properties: + url: + description: URL to the image. This can be a data url or an remote url + type: string + format: uri + size_type: + description: The size of the image. The network policy can define the default dimensions of each type + type: string + enum: + - xs + - sm + - md + - lg + - xl + - custom + width: + description: Width of the image in pixels + type: string + height: + description: Height of the image in pixels + type: string + Intent: + description: 'The intent to buy or avail a product or a service. The BAP can declare the intent of the consumer containing
  • What they want (A product, service, offer)
  • Who they want (A seller, service provider, agent etc)
  • Where they want it and where they want it from
  • When they want it (start and end time of fulfillment
  • How they want to pay for it

This has properties like descriptor,provider,fulfillment,payment,category,offer,item,tags
This is typically used by the BAP to send the purpose of the user''s search to the BPP. This will be used by the BPP to find products or services it offers that may match the user''s intent.
For example, in Mobility, the mobility consumer declares a mobility intent. In this case, the mobility consumer declares information that describes various aspects of their journey like,
  • Where would they like to begin their journey (intent.fulfillment.start.location)
  • Where would they like to end their journey (intent.fulfillment.end.location)
  • When would they like to begin their journey (intent.fulfillment.start.time)
  • When would they like to end their journey (intent.fulfillment.end.time)
  • Who is the transport service provider they would like to avail services from (intent.provider)
  • Who is traveling (This is not recommended in public networks) (intent.fulfillment.customer)
  • What kind of fare product would they like to purchase (intent.item)
  • What add-on services would they like to avail
  • What offers would they like to apply on their booking (intent.offer)
  • What category of services would they like to avail (intent.category)
  • What additional luggage are they carrying
  • How would they like to pay for their journey (intent.payment)

For example, in health domain, a consumer declares the intent for a lab booking the describes various aspects of their booking like,
  • Where would they like to get their scan/test done (intent.fulfillment.start.location)
  • When would they like to get their scan/test done (intent.fulfillment.start.time)
  • When would they like to get the results of their test/scan (intent.fulfillment.end.time)
  • Who is the service provider they would like to avail services from (intent.provider)
  • Who is getting the test/scan (intent.fulfillment.customer)
  • What kind of test/scan would they like to purchase (intent.item)
  • What category of services would they like to avail (intent.category)
  • How would they like to pay for their journey (intent.payment)
' + type: object + properties: + descriptor: + description: 'A raw description of the search intent. Free text search strings, raw audio, etc can be sent in this object.' + allOf: + - $ref: '#/components/schemas/Descriptor' + provider: + description: The provider from which the customer wants to place to the order from + allOf: + - $ref: '#/components/schemas/Provider' + fulfillment: + description: Details on how the customer wants their order fulfilled + allOf: + - $ref: '#/components/schemas/Fulfillment' + payment: + description: Details on how the customer wants to pay for the order + allOf: + - $ref: '#/components/schemas/Payment' + category: + description: Details on the item category + allOf: + - $ref: '#/components/schemas/Category' + offer: + description: details on the offer the customer wants to avail + allOf: + - $ref: '#/components/schemas/Offer' + item: + description: Details of the item that the consumer wants to order + allOf: + - $ref: '#/components/schemas/Item' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + ItemQuantity: + description: Describes the count or amount of an item + type: object + properties: + allocated: + description: This represents the exact quantity allocated for purchase of the item. + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + available: + description: This represents the exact quantity available for purchase of the item. The buyer can only purchase multiples of this + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + maximum: + description: This represents the maximum quantity allowed for purchase of the item + type: object + properties: + count: + type: integer + minimum: 1 + measure: + $ref: '#/components/schemas/Scalar' + minimum: + description: This represents the minimum quantity allowed for purchase of the item + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + selected: + description: This represents the quantity selected for purchase of the item + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + unitized: + description: This represents the quantity available in a single unit of the item + type: object + properties: + count: + type: integer + minimum: 1 + maximum: 1 + measure: + $ref: '#/components/schemas/Scalar' + Item: + description: 'Describes a product or a service offered to the end consumer by the provider. In the mobility sector, it can represent a fare product like one way journey. In the logistics sector, it can represent the delivery service offering. In the retail domain it can represent a product like a grocery item.' + type: object + properties: + id: + description: ID of the item. + type: string + parent_item_id: + description: 'ID of the item, this item is a variant of' + allOf: + - $ref: '#/components/schemas/Item/properties/id' + parent_item_quantity: + description: The number of units of the parent item this item is a multiple of + allOf: + - $ref: '#/components/schemas/ItemQuantity' + descriptor: + description: Physical description of the item + allOf: + - $ref: '#/components/schemas/Descriptor' + creator: + description: The creator of this item + allOf: + - $ref: '#/components/schemas/Organization' + price: + description: 'The price of this item, if it has intrinsic value' + allOf: + - $ref: '#/components/schemas/Price' + quantity: + description: The selling quantity of the item + allOf: + - $ref: '#/components/schemas/ItemQuantity' + category_ids: + description: Categories this item can be listed under + type: array + items: + allOf: + - $ref: '#/components/schemas/Category/properties/id' + fulfillment_ids: + description: Modes through which this item can be fulfilled + type: array + items: + allOf: + - $ref: '#/components/schemas/Fulfillment/properties/id' + location_ids: + description: Provider Locations this item is available in + type: array + items: + allOf: + - $ref: '#/components/schemas/Location/properties/id' + payment_ids: + description: Payment modalities through which this item can be ordered + type: array + items: + allOf: + - $ref: '#/components/schemas/Payment/properties/id' + add_ons: + type: array + items: + $ref: '#/components/schemas/AddOn' + cancellation_terms: + description: Cancellation terms of this item + type: array + items: + $ref: '#/components/schemas/CancellationTerm' + refund_terms: + description: Refund terms of this item + type: array + items: + description: Refund term of an item or an order + type: object + properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: '#/components/schemas/State' + refund_eligible: + description: Indicates if cancellation will result in a refund + type: boolean + refund_within: + description: Time within which refund will be processed after successful cancellation. + allOf: + - $ref: '#/components/schemas/Time' + refund_amount: + $ref: '#/components/schemas/Price' + replacement_terms: + description: Terms that are applicable be met when this item is replaced + type: array + items: + $ref: '#/components/schemas/ReplacementTerm' + return_terms: + description: Terms that are applicable when this item is returned + type: array + items: + $ref: '#/components/schemas/ReturnTerm' + xinput: + description: Additional input required from the customer to purchase / avail this item + allOf: + - $ref: '#/components/schemas/XInput' + time: + description: Temporal attributes of this item. This property is used when the item exists on the catalog only for a limited period of time. + allOf: + - $ref: '#/components/schemas/Time' + rateable: + description: Whether this item can be rated + type: boolean + rating: + description: The rating of the item + allOf: + - $ref: '#/components/schemas/Rating/properties/value' + matched: + description: Whether this item is an exact match of the request + type: boolean + related: + description: Whether this item is a related item to the exactly matched item + type: boolean + recommended: + description: Whether this item is a recommended item to a response + type: boolean + ttl: + description: Time to live in seconds for an instance of this schema + type: string + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Location: + description: The physical location of something + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + map_url: + description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy. + type: string + format: uri + gps: + description: The GPS co-ordinates of this location. + allOf: + - $ref: '#/components/schemas/Gps' + address: + description: The address of this location. + allOf: + - $ref: '#/components/schemas/Address' + city: + description: 'The city this location is, or is located within' + allOf: + - $ref: '#/components/schemas/City' + district: + description: 'The state this location is, or is located within' + type: string + state: + description: 'The state this location is, or is located within' + allOf: + - $ref: '#/components/schemas/State' + country: + description: 'The country this location is, or is located within' + allOf: + - $ref: '#/components/schemas/Country' + area_code: + type: string + circle: + $ref: '#/components/schemas/Circle' + polygon: + description: The boundary polygon of this location + type: string + 3dspace: + description: The three dimensional region describing this location + type: string + rating: + description: The rating of this location + allOf: + - $ref: '#/components/schemas/Rating/properties/value' + MediaFile: + description: This object contains a url to a media file. + type: object + properties: + mimetype: + description: 'indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF''s RFC 6838' + type: string + url: + description: The URL of the file + type: string + format: uri + signature: + description: The digital signature of the file signed by the sender + type: string + dsa: + description: The signing algorithm used by the sender + type: string + Offer: + description: An offer associated with a catalog. This is typically used to promote a particular product and enable more purchases. + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + location_ids: + type: array + items: + $ref: '#/components/schemas/Location/properties/id' + category_ids: + type: array + items: + $ref: '#/components/schemas/Category/properties/id' + item_ids: + type: array + items: + $ref: '#/components/schemas/Item/properties/id' + time: + $ref: '#/components/schemas/Time' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Option: + description: Describes a selectable option + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + Order: + description: Describes a legal purchase order. It contains the complete details of the legal contract created between the buyer and the seller. + type: object + properties: + id: + type: string + description: Human-readable ID of the order. This is generated at the BPP layer. The BPP can either generate order id within its system or forward the order ID created at the provider level. + ref_order_ids: + description: A list of order IDs to link this order to previous orders. + type: array + items: + type: string + description: ID of a previous order + status: + description: Status of the order. Allowed values can be defined by the network policy + type: string + enum: + - ACTIVE + - COMPLETE + - CANCELLED + type: + description: 'This is used to indicate the type of order being created to BPPs. Sometimes orders can be linked to previous orders, like a replacement order in a retail domain. A follow-up consultation in healthcare domain. A single order part of a subscription order. The list of order types can be standardized at the network level.' + type: string + default: DEFAULT + enum: + - DRAFT + - DEFAULT + provider: + description: Details of the provider whose catalog items have been selected. + allOf: + - $ref: '#/components/schemas/Provider' + items: + description: The items purchased / availed in this order + type: array + items: + $ref: '#/components/schemas/Item' + add_ons: + description: The add-ons purchased / availed in this order + type: array + items: + $ref: '#/components/schemas/AddOn' + offers: + description: The offers applied in this order + type: array + items: + $ref: '#/components/schemas/Offer' + billing: + description: The billing details of this order + allOf: + - $ref: '#/components/schemas/Billing' + fulfillments: + description: The fulfillments involved in completing this order + type: array + items: + $ref: '#/components/schemas/Fulfillment' + cancellation: + description: The cancellation details of this order + allOf: + - $ref: '#/components/schemas/Cancellation' + cancellation_terms: + description: Cancellation terms of this item + type: array + items: + $ref: '#/components/schemas/CancellationTerm' + refund_terms: + description: Refund terms of this item + type: array + items: + $ref: '#/components/schemas/Item/properties/refund_terms/items' + replacement_terms: + description: Replacement terms of this item + type: array + items: + $ref: '#/components/schemas/ReplacementTerm' + return_terms: + description: Return terms of this item + type: array + items: + $ref: '#/components/schemas/ReturnTerm' + quote: + description: The mutually agreed upon quotation for this order. + allOf: + - $ref: '#/components/schemas/Quotation' + payments: + description: The terms of settlement for this order + type: array + items: + $ref: '#/components/schemas/Payment' + created_at: + description: The date-time of creation of this order + type: string + format: date-time + updated_at: + description: The date-time of updated of this order + type: string + format: date-time + xinput: + description: Additional input required from the customer to confirm this order + allOf: + - $ref: '#/components/schemas/XInput' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Organization: + description: An organization. Usually a recognized business entity. + type: object + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + address: + description: The postal address of the organization + allOf: + - $ref: '#/components/schemas/Address' + state: + description: The state where the organization's address is registered + allOf: + - $ref: '#/components/schemas/State' + city: + description: The city where the the organization's address is registered + allOf: + - $ref: '#/components/schemas/City' + contact: + $ref: '#/components/schemas/Contact' + Payment: + description: 'Describes the terms of settlement between the BAP and the BPP for a single transaction. When instantiated, this object contains
  1. the amount that has to be settled,
  2. The payment destination destination details
  3. When the settlement should happen, and
  4. A transaction reference ID
. During a transaction, the BPP reserves the right to decide the terms of payment. However, the BAP can send its terms to the BPP first. If the BPP does not agree to those terms, it must overwrite the terms and return them to the BAP. If overridden, the BAP must either agree to the terms sent by the BPP in order to preserve the provider''s autonomy, or abort the transaction. In case of such disagreements, the BAP and the BPP can perform offline negotiations on the payment terms. Once an agreement is reached, the BAP and BPP can resume transactions.' + type: object + properties: + id: + description: ID of the payment term that can be referred at an item or an order level in a catalog + type: string + collected_by: + description: 'This field indicates who is the collector of payment. The BAP can set this value to ''bap'' if it wants to collect the payment first and settle it to the BPP. If the BPP agrees to those terms, the BPP should not send the payment url. Alternatively, the BPP can set this field with the value ''bpp'' if it wants the payment to be made directly.' + url: + type: string + description: 'A payment url to be called by the BAP. If empty, then the payment is to be done offline. The details of payment should be present in the params object. If tl_method = http/get, then the payment details will be sent as url params. Two url param values, ```$transaction_id``` and ```$amount``` are mandatory.' + format: uri + params: + type: object + properties: + transaction_id: + type: string + description: The reference transaction ID associated with a payment activity + amount: + type: string + currency: + type: string + bank_code: + type: string + bank_account_number: + type: string + virtual_payment_address: + type: string + source_bank_code: + type: string + source_bank_account_number: + type: string + source_virtual_payment_address: + type: string + type: + type: string + enum: + - PRE-ORDER + - PRE-FULFILLMENT + - ON-FULFILLMENT + - POST-FULFILLMENT + status: + type: string + enum: + - PAID + - NOT-PAID + time: + $ref: '#/components/schemas/Time' + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Person: + description: Describes a person as any individual + type: object + properties: + id: + type: string + description: Describes the identity of the person + url: + description: Profile url of the person + type: string + format: uri + name: + description: the name of the person + type: string + image: + $ref: '#/components/schemas/Image' + age: + description: Age of the person + allOf: + - $ref: '#/components/schemas/Duration' + dob: + description: Date of birth of the person + type: string + format: date + gender: + type: string + description: 'Gender of something, typically a Person, but possibly also fictional characters, animals, etc. While Male and Female may be used, text strings are also acceptable for people who do not identify as a binary gender.Allowed values for this field can be published in the network policy' + creds: + type: array + items: + $ref: '#/components/schemas/Credential' + languages: + type: array + items: + description: Describes a language known to the person. + type: object + properties: + code: + type: string + name: + type: string + skills: + type: array + items: + description: Describes a skill of the person. + type: object + properties: + code: + type: string + name: + type: string + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Price: + description: Describes the price of a product or service + type: object + properties: + currency: + type: string + value: + $ref: '#/components/schemas/DecimalValue' + estimated_value: + $ref: '#/components/schemas/DecimalValue' + computed_value: + $ref: '#/components/schemas/DecimalValue' + listed_value: + $ref: '#/components/schemas/DecimalValue' + offered_value: + $ref: '#/components/schemas/DecimalValue' + minimum_value: + $ref: '#/components/schemas/DecimalValue' + maximum_value: + $ref: '#/components/schemas/DecimalValue' + Provider: + description: Describes the catalog of a business. + type: object + properties: + id: + type: string + description: Id of the provider + descriptor: + $ref: '#/components/schemas/Descriptor' + category_id: + type: string + description: Category Id of the provider at the BPP-level catalog + rating: + $ref: '#/components/schemas/Rating/properties/value' + time: + $ref: '#/components/schemas/Time' + categories: + type: array + items: + $ref: '#/components/schemas/Category' + fulfillments: + type: array + items: + $ref: '#/components/schemas/Fulfillment' + payments: + type: array + items: + $ref: '#/components/schemas/Payment' + locations: + type: array + items: + $ref: '#/components/schemas/Location' + offers: + type: array + items: + $ref: '#/components/schemas/Offer' + items: + type: array + items: + $ref: '#/components/schemas/Item' + exp: + type: string + description: Time after which catalog has to be refreshed + format: date-time + rateable: + description: Whether this provider can be rated or not + type: boolean + ttl: + description: 'The time-to-live in seconds, for this object. This can be overriden at deeper levels. A value of -1 indicates that this object is not cacheable.' + type: integer + minimum: -1 + tags: + type: array + items: + $ref: '#/components/schemas/TagGroup' + Quotation: + description: 'Describes a quote. It is the estimated price of products or services from the BPP.
This has properties like price, breakup, ttl' + type: object + properties: + id: + description: ID of the quote. + type: string + format: uuid + price: + description: The total quoted price + allOf: + - $ref: '#/components/schemas/Price' + breakup: + description: the breakup of the total quoted price + type: array + items: + type: object + properties: + item: + $ref: '#/components/schemas/Item' + title: + type: string + price: + $ref: '#/components/schemas/Price' + ttl: + $ref: '#/components/schemas/Duration' + Rating: + description: Describes the rating of an entity + type: object + properties: + rating_category: + description: Category of the entity being rated + type: string + enum: + - Item + - Order + - Fulfillment + - Provider + - Agent + - Support + id: + description: Id of the object being rated + type: string + value: + description: 'Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||.' + type: string + Region: + description: Describes an arbitrary region of space. The network policy should contain a published list of supported regions by the network. + type: object + properties: + dimensions: + description: 'The number of dimensions that are used to describe any point inside that region. The most common dimensionality of a region is 2, that represents an area on a map. There are regions on the map that can be approximated to one-dimensional regions like roads, railway lines, or shipping lines. 3 dimensional regions are rarer, but are gaining popularity as flying drones are being adopted for various fulfillment services.' + type: string + enum: + - '1' + - '2' + - '3' + type: + description: 'The type of region. This is used to specify the granularity of the region represented by this object. Various examples of two-dimensional region types are city, country, state, district, and so on. The network policy should contain a list of all possible region types supported by the network.' + type: string + name: + type: string + description: Name of the region as specified on the map where that region exists. + code: + type: string + description: A standard code representing the region. This should be interpreted in the same way by all network participants. + boundary: + type: string + description: 'A string representing the boundary of the region. One-dimensional regions are represented by polylines. Two-dimensional regions are represented by polygons, and three-dimensional regions can represented by polyhedra.' + map_url: + type: string + description: The url to the map of the region. This can be a globally recognized map or the one specified by the network policy. + ReplacementTerm: + description: The replacement policy of an item or an order + type: object + properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: '#/components/schemas/State' + replace_within: + description: 'Applicable only for buyer managed returns where the buyer has to replace the item before a certain date-time, failing which they will not be eligible for replacement' + allOf: + - $ref: '#/components/schemas/Time' + external_ref: + $ref: '#/components/schemas/MediaFile' + ReturnTerm: + description: Describes the return policy of an item or an order + type: object + properties: + fulfillment_state: + description: The state of fulfillment during which this term IETF''s applicable. + allOf: + - $ref: '#/components/schemas/State' + return_eligible: + description: Indicates whether the item is eligible for return + type: boolean + return_time: + description: 'Applicable only for buyer managed returns where the buyer has to return the item to the origin before a certain date-time, failing which they will not be eligible for refund.' + allOf: + - $ref: '#/components/schemas/Time' + return_location: + description: The location where the item or order must / will be returned to + allOf: + - $ref: '#/components/schemas/Location' + fulfillment_managed_by: + description: The entity that will perform the return + type: string + enum: + - CONSUMER + - PROVIDER + Scalar: + description: Describes a scalar + type: object + properties: + type: + type: string + enum: + - CONSTANT + - VARIABLE + value: + $ref: '#/components/schemas/DecimalValue' + estimated_value: + $ref: '#/components/schemas/DecimalValue' + computed_value: + $ref: '#/components/schemas/DecimalValue' + range: + type: object + properties: + min: + $ref: '#/components/schemas/DecimalValue' + max: + $ref: '#/components/schemas/DecimalValue' + unit: + type: string + Schedule: + description: 'Describes schedule as a repeating time period used to describe a regularly recurring event. At a minimum a schedule will specify frequency which describes the interval between occurrences of the event. Additional information can be provided to specify the schedule more precisely. This includes identifying the timestamps(s) of when the event will take place. Schedules may also have holidays to exclude a specific day from the schedule.
This has properties like frequency, holidays, times' + type: object + properties: + frequency: + $ref: '#/components/schemas/Duration' + holidays: + type: array + items: + type: string + format: date-time + times: + type: array + items: + type: string + format: date-time + State: + description: A bounded geopolitical region of governance inside a country. + type: object + properties: + name: + type: string + description: Name of the state + code: + type: string + description: State code as per country or international standards + Stop: + description: A logical point in space and time during the fulfillment of an order. + type: object + properties: + id: + type: string + parent_stop_id: + type: string + location: + description: Location of the stop + allOf: + - $ref: '#/components/schemas/Location' + type: + description: The type of stop. Allowed values of this property can be defined by the network policy. + type: string + time: + description: Timings applicable at the stop. + allOf: + - $ref: '#/components/schemas/Time' + instructions: + description: Instructions that need to be followed at the stop + allOf: + - $ref: '#/components/schemas/Descriptor' + contact: + description: Contact details of the stop + allOf: + - $ref: '#/components/schemas/Contact' + person: + description: The details of the person present at the stop + allOf: + - $ref: '#/components/schemas/Person' + authorization: + $ref: '#/components/schemas/Authorization' + Support: + description: Details of customer support + type: object + properties: + ref_id: + type: string + callback_phone: + type: string + format: phone + phone: + type: string + format: phone + email: + type: string + format: email + url: + type: string + format: uri + Tag: + description: 'Describes a tag. This is used to contain extended metadata. This object can be added as a property to any schema to describe extended attributes. For BAPs, tags can be sent during search to optimize and filter search results. BPPs can use tags to index their catalog to allow better search functionality. Tags are sent by the BPP as part of the catalog response in the `on_search` callback. Tags are also meant for display purposes. Upon receiving a tag, BAPs are meant to render them as name-value pairs. This is particularly useful when rendering tabular information about a product or service.' + type: object + properties: + descriptor: + description: 'Description of the Tag, can be used to store detailed information.' + allOf: + - $ref: '#/components/schemas/Descriptor' + value: + description: The value of the tag. This set by the BPP and rendered as-is by the BAP. + type: string + display: + description: 'This value indicates if the tag is intended for display purposes. If set to `true`, then this tag must be displayed. If it is set to `false`, it should not be displayed. This value can override the group display value.' + type: boolean + TagGroup: + description: 'A collection of tag objects with group level attributes. For detailed documentation on the Tags and Tag Groups schema go to https://github.com/beckn/protocol-specifications/discussions/316' + type: object + properties: + display: + description: 'Indicates the display properties of the tag group. If display is set to false, then the group will not be displayed. If it is set to true, it should be displayed. However, group-level display properties can be overriden by individual tag-level display property. As this schema is purely for catalog display purposes, it is not recommended to send this value during search.' + type: boolean + default: true + descriptor: + description: 'Description of the TagGroup, can be used to store detailed information.' + allOf: + - $ref: '#/components/schemas/Descriptor' + list: + description: 'An array of Tag objects listed under this group. This property can be set by BAPs during search to narrow the `search` and achieve more relevant results. When received during `on_search`, BAPs must render this list under the heading described by the `name` property of this schema.' + type: array + items: + $ref: '#/components/schemas/Tag' + Time: + description: 'Describes time in its various forms. It can be a single point in time; duration; or a structured timetable of operations
This has properties like label, time stamp,duration,range, days, schedule' + type: object + properties: + label: + type: string + timestamp: + type: string + format: date-time + duration: + $ref: '#/components/schemas/Duration' + range: + type: object + properties: + start: + type: string + format: date-time + end: + type: string + format: date-time + days: + type: string + description: comma separated values representing days of the week + schedule: + $ref: '#/components/schemas/Schedule' + Tracking: + description: Contains tracking information that can be used by the BAP to track the fulfillment of an order in real-time. which is useful for knowing the location of time sensitive deliveries. + type: object + properties: + id: + description: A unique tracking reference number + type: string + url: + description: 'A URL to the tracking endpoint. This can be a link to a tracking webpage, a webhook URL created by the BAP where BPP can push the tracking data, or a GET url creaed by the BPP which the BAP can poll to get the tracking data. It can also be a websocket URL where the BPP can push real-time tracking data.' + type: string + format: uri + location: + description: 'In case there is no real-time tracking endpoint available, this field will contain the latest location of the entity being tracked. The BPP will update this value everytime the BAP calls the track API.' + allOf: + - $ref: '#/components/schemas/Location' + status: + description: 'This value indicates if the tracking is currently active or not. If this value is `active`, then the BAP can begin tracking the order. If this value is `inactive`, the tracking URL is considered to be expired and the BAP should stop tracking the order.' + type: string + enum: + - active + - inactive + Vehicle: + description: 'Describes a vehicle is a device that is designed or used to transport people or cargo over land, water, air, or through space.
This has properties like category, capacity, make, model, size,variant,color,energy_type,registration' + type: object + properties: + category: + type: string + capacity: + type: integer + make: + type: string + model: + type: string + size: + type: string + variant: + type: string + color: + type: string + energy_type: + type: string + registration: + type: string + wheels_count: + type: string + cargo_volumne: + type: string + wheelchair_access: + type: string + code: + type: string + emission_standard: + type: string + XInput: + description: 'Contains any additional or extended inputs required to confirm an order. This is typically a Form Input. Sometimes, selection of catalog elements is not enough for the BPP to confirm an order. For example, to confirm a flight ticket, the airline requires details of the passengers along with information on baggage, identity, in addition to the class of ticket. Similarly, a logistics company may require details on the nature of shipment in order to confirm the shipping. A recruiting firm may require additional details on the applicant in order to confirm a job application. For all such purposes, the BPP can choose to send this object attached to any object in the catalog that is required to be sent while placing the order. This object can typically be sent at an item level or at the order level. The item level XInput will override the Order level XInput as it indicates a special requirement of information for that particular item. Hence the BAP must render a separate form for the Item and another form at the Order level before confirmation.' + type: object + properties: + form: + $ref: '#/components/schemas/Form' + required: + description: Indicates whether the form data is mandatorily required by the BPP to confirm the order. + type: boolean diff --git a/docs/beckn-core/api/transaction/components/index.yaml b/docs/beckn-core/api/transaction/components/index.yaml new file mode 100644 index 0000000..f0a6537 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/index.yaml @@ -0,0 +1,299 @@ +openapi: 3.0.0 +info: + title: Beckn Protocol Core + description: Beckn Core Transaction API specification + version: "1.1.0" + +security: + - SubscriberAuth: [] +paths: + /search: + post: + tags: + - Beckn Provider Platform (BPP) + - Beckn Gateway (BG) + description: BAP declares the customer's intent to buy/avail products or services + requestBody: + content: + application/json: + schema: + $ref : "./io/Search.yaml" + + responses: + default: + $ref: "./io/Response.yaml" + + /select: + post: + tags: + - Beckn Provider Platform (BPP) + description: BAP declares the customer's cart (or equivalent) created by selecting objects from the catalog + requestBody: + content: + application/json: + schema: + $ref: "./io/Select.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /init: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + content: + application/json: + schema: + $ref: "./io/Init.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /confirm: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + content: + application/json: + schema: + $ref: "./io/Confirm.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /status: + post: + tags: + - Beckn Provider Platform (BPP) + description: Fetch the latest order object + requestBody: + content: + application/json: + schema: + $ref: "./io/Status.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /track: + post: + tags: + - Beckn Provider Platform (BPP) + description: Track an active order + requestBody: + content: + application/json: + schema: + $ref: "./io/Track.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /cancel: + post: + tags: + - Beckn Provider Platform (BPP) + description: Cancel an order + requestBody: + content: + application/json: + schema: + $ref: "./io/Cancel.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /update: + post: + tags: + - Beckn Provider Platform (BPP) + description: Remove object + requestBody: + content: + application/json: + schema: + $ref: "./io/Update.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /rating: + post: + tags: + - Beckn Provider Platform (BPP) + description: Provide feedback on a service + requestBody: + content: + application/json: + schema: + $ref: "./io/Rating.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /support: + post: + tags: + - Beckn Provider Platform (BPP) + description: Contact support + requestBody: + content: + application/json: + schema: + $ref : "./io/Support.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_search: + post: + tags: + - Beckn Application Platform (BAP) + - Beckn Gateway (BG) + description: BPP sends its catalog in response to a search request. + requestBody: + content: + application/json: + schema: + $ref: "./io/OnSearch.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_select: + post: + tags: + - Beckn Application Platform (BAP) + description: Send draft order object with quoted price for selected items + requestBody: + content: + application/json: + schema: + $ref : "./io/OnSelect.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_init: + post: + tags: + - Beckn Application Platform (BAP) + description: Send order object with payment details updated + requestBody: + content: + application/json: + schema: + $ref : "./io/OnInit.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_confirm: + post: + tags: + - Beckn Application Platform (BAP) + description: Send active order object + requestBody: + content: + application/json: + schema: + $ref : "./io/OnConfirm.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_track: + post: + tags: + - Beckn Application Platform (BAP) + description: Send tracking details of an active order + requestBody: + content: + application/json: + schema: + $ref : "./io/OnTrack.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_cancel: + post: + tags: + - Beckn Application Platform (BAP) + description: Send cancellation request_id with reasons list in case of cancellation request. Else send cancelled order object + requestBody: + content: + application/json: + schema: + $ref: "./io/OnCancel.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_update: + post: + tags: + - Beckn Application Platform (BAP) + description: Returns updated service with updated runtime object + requestBody: + content: + application/json: + schema: + $ref: "./io/OnUpdate.yaml" + responses: + default: + $ref: "./io/Response.yaml" + /on_status: + post: + tags: + - Beckn Application Platform (BAP) + description: Fetch the status of a Service + requestBody: + content: + application/json: + schema: + $ref: "./io/OnStatus.yaml" + responses: + default: + $ref: "./io/Response.yaml" + /on_rating: + post: + tags: + - Beckn Application Platform (BAP) + description: Provide feedback on a service + requestBody: + content: + application/json: + schema: + $ref: "./io/OnRating.yaml" + responses: + default: + $ref: "./io/Response.yaml" + + /on_support: + post: + tags: + - Beckn Application Platform (BAP) + description: Contact Support + requestBody: + content: + application/json: + schema: + $ref: "./io/OnSupport.yaml" + responses: + default: + $ref: "./io/Response.yaml" +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using BAP or BPP subscriber''s signing public key.

Format:

Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"' + schemas: + $ref: "./schema/index.yaml" + diff --git a/docs/beckn-core/api/transaction/components/io/Cancel.yaml b/docs/beckn-core/api/transaction/components/io/Cancel.yaml new file mode 100644 index 0000000..c223469 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Cancel.yaml @@ -0,0 +1,28 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - cancel + required: + - action + message: + type: object + additionalProperties: false + properties: + order_id: + $ref: "../../../../schema/Order.yaml#/properties/id" + cancellation_reason_id: + $ref: "../../../../schema/Option.yaml#/properties/id" + descriptor: + $ref: "../../../../schema/Descriptor.yaml" + required: + - order_id +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/io/Confirm.yaml b/docs/beckn-core/api/transaction/components/io/Confirm.yaml new file mode 100644 index 0000000..66d64d5 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Confirm.yaml @@ -0,0 +1,24 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - confirm + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/io/Init.yaml b/docs/beckn-core/api/transaction/components/io/Init.yaml new file mode 100644 index 0000000..ceb23b8 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Init.yaml @@ -0,0 +1,24 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - init + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order +required: + - context + - message \ No newline at end of file diff --git a/docs/beckn-core/api/transaction/components/io/OnCancel.yaml b/docs/beckn-core/api/transaction/components/io/OnCancel.yaml new file mode 100644 index 0000000..e806109 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnCancel.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_cancel + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnConfirm.yaml b/docs/beckn-core/api/transaction/components/io/OnConfirm.yaml new file mode 100644 index 0000000..d3008fc --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnConfirm.yaml @@ -0,0 +1,24 @@ +type: object +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_confirm + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnInit.yaml b/docs/beckn-core/api/transaction/components/io/OnInit.yaml new file mode 100644 index 0000000..5ee3e7d --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnInit.yaml @@ -0,0 +1,24 @@ +type: object +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_init + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnRating.yaml b/docs/beckn-core/api/transaction/components/io/OnRating.yaml new file mode 100644 index 0000000..c00582b --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnRating.yaml @@ -0,0 +1,24 @@ +type: object +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_rating + required: + - action + message: + type: object + properties: + feedback_form: + description: A feedback form to allow the user to provide additional information on the rating provided + allOf: + - $ref: "../../../../schema/XInput.yaml" + error: + $ref: "../../../../schema/Error.yaml" +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/io/OnSearch.yaml b/docs/beckn-core/api/transaction/components/io/OnSearch.yaml new file mode 100644 index 0000000..fcbc4a8 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnSearch.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_search + required: + - action + message: + type: object + additionalProperties: false + properties: + catalog: + $ref: "../../../../schema/Catalog.yaml" + required: + - catalog + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnSelect.yaml b/docs/beckn-core/api/transaction/components/io/OnSelect.yaml new file mode 100644 index 0000000..41faf78 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnSelect.yaml @@ -0,0 +1,23 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_select + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnStatus.yaml b/docs/beckn-core/api/transaction/components/io/OnStatus.yaml new file mode 100644 index 0000000..48a6dbc --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnStatus.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_status + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnSupport.yaml b/docs/beckn-core/api/transaction/components/io/OnSupport.yaml new file mode 100644 index 0000000..3fe3174 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnSupport.yaml @@ -0,0 +1,21 @@ +type: object +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_support + required: + - action + message: + type: object + properties: + support: + $ref: "../../../../schema/Support.yaml" + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnTrack.yaml b/docs/beckn-core/api/transaction/components/io/OnTrack.yaml new file mode 100644 index 0000000..41c1d49 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnTrack.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_track + required: + - action + message: + type: object + additionalProperties: false + properties: + tracking: + $ref: "../../../../schema/Tracking.yaml" + required: + - tracking + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/OnUpdate.yaml b/docs/beckn-core/api/transaction/components/io/OnUpdate.yaml new file mode 100644 index 0000000..27f28c4 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/OnUpdate.yaml @@ -0,0 +1,25 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - on_update + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order + error: + $ref: "../../../../schema/Error.yaml" +required: + - context diff --git a/docs/beckn-core/api/transaction/components/io/README.md b/docs/beckn-core/api/transaction/components/io/README.md new file mode 100644 index 0000000..ffbaaf9 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/README.md @@ -0,0 +1,41 @@ +# Transaction API Endpoints + +This folder contains API specification for Transaction API endpoints + +The transaction APIs can be classified into three groups:- + +1. BPP API +2. BAP API +3. BG API + + +The BPP API endpoints are: + +1. `search` : Search.yaml +2. `select` : Select.yaml +3. `init` : Init.yaml +4. `confirm` : Confirm.yaml +5. `status` : Status.yaml +6. `update` : Update.yaml +7. `track` : Track.yaml +8. `cancel` : Cancel.yaml +9. `rating` : Rating.yaml +10. `support` : Support.yaml + +The BAP API endpoints are: + +1. `on_search` : OnSearch.yaml +2. `on_select` : OnSelect.yaml +3. `on_init` : OnInit.yaml +4. `on_confirm` : OnConfirm.yaml +5. `on_status` : OnStatus.yaml +6. `on_update` : OnUpdate.yaml +7. `on_track` : OnTrack.yaml +8. `on_cancel` : OnCancel.yaml +9. `on_rating` : OnRating.yaml +10. `on_support` : OnSupport.yaml + +The BG API endpoints are: + +1. `search` : Search.yaml +2. `on_search` _(Only supported till version 0.9.3)_ : OnSearch.yaml. From 1.x, BPPs will call BAPs' `on_search` endpoint directly. diff --git a/docs/beckn-core/api/transaction/components/io/Rating.yaml b/docs/beckn-core/api/transaction/components/io/Rating.yaml new file mode 100644 index 0000000..64714b2 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Rating.yaml @@ -0,0 +1,22 @@ +type: object +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - rating + required: + - action + message: + type: object + properties: + ratings: + type: array + items: + $ref: "../../../../schema/Rating.yaml" +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/io/Response.yaml b/docs/beckn-core/api/transaction/components/io/Response.yaml new file mode 100644 index 0000000..26e7685 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Response.yaml @@ -0,0 +1,24 @@ +description: Acknowledgement of message received after successful validation of schema and signature +content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + allOf: + - $ref: "../../../../schema/Ack.yaml" + - type: object + - properties: + status: + enum: + - ACK + - NACK + required: + - ack + error: + $ref: "../../../../schema/Error.yaml" + required: + - message \ No newline at end of file diff --git a/docs/beckn-core/api/transaction/components/io/Search.yaml b/docs/beckn-core/api/transaction/components/io/Search.yaml new file mode 100644 index 0000000..d6ff6bd --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Search.yaml @@ -0,0 +1,19 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - properties: + action: + enum: + - search + message: + type: object + additionalProperties: false + properties: + intent: + $ref: "../../../../schema/Intent.yaml" +required: + - context + - message \ No newline at end of file diff --git a/docs/beckn-core/api/transaction/components/io/Select.yaml b/docs/beckn-core/api/transaction/components/io/Select.yaml new file mode 100644 index 0000000..423a607 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Select.yaml @@ -0,0 +1,24 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - select + required: + - action + message: + type: object + additionalProperties: false + properties: + order: + $ref: "../../../../schema/Order.yaml" + required: + - order +required: + - context + - message \ No newline at end of file diff --git a/docs/beckn-core/api/transaction/components/io/Status.yaml b/docs/beckn-core/api/transaction/components/io/Status.yaml new file mode 100644 index 0000000..a68bdea --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Status.yaml @@ -0,0 +1,26 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - status + required: + - action + message: + type: object + additionalProperties: false + properties: + ref_id: + $ref: "../../../../schema/Order.yaml#/properties/id" + order_id: + $ref: "../../../../schema/Order.yaml#/properties/id" + # required: + # - order_id +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/io/Support.yaml b/docs/beckn-core/api/transaction/components/io/Support.yaml new file mode 100644 index 0000000..3eb0d8a --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Support.yaml @@ -0,0 +1,20 @@ +type: object +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - support + required: + - action + message: + type: object + properties: + support: + $ref: "../../../../schema/Support.yaml" +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/io/Track.yaml b/docs/beckn-core/api/transaction/components/io/Track.yaml new file mode 100644 index 0000000..282cad3 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Track.yaml @@ -0,0 +1,27 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - track + required: + - action + message: + type: object + additionalProperties: false + properties: + order_id: + $ref: "../../../../schema/Order.yaml#/properties/id" + callback_url: + type: string + format: uri + required: + - order_id +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/io/Update.yaml b/docs/beckn-core/api/transaction/components/io/Update.yaml new file mode 100644 index 0000000..aae055f --- /dev/null +++ b/docs/beckn-core/api/transaction/components/io/Update.yaml @@ -0,0 +1,30 @@ +type: object +additionalProperties: false +properties: + context: + allOf: + - $ref: "../../../../schema/Context.yaml" + - type: object + properties: + action: + enum: + - update + required: + - action + message: + type: object + additionalProperties: false + properties: + update_target: + description: 'Comma separated values of order objects being updated. For example: ```"update_target":"item,billing,fulfillment"```' + type: string + order: + description: Updated order object + allOf: + - $ref: "../../../../schema/Order.yaml" + required: + - update_target + - order +required: + - context + - message diff --git a/docs/beckn-core/api/transaction/components/schema/index.yaml b/docs/beckn-core/api/transaction/components/schema/index.yaml new file mode 100644 index 0000000..ff412a3 --- /dev/null +++ b/docs/beckn-core/api/transaction/components/schema/index.yaml @@ -0,0 +1,170 @@ +Ack: + $ref: "../../../../schema/Ack.yaml" + +AddOn: + $ref: "../../../../schema/AddOn.yaml" + +Address: + $ref: "../../../../schema/Address.yaml" + +Agent: + $ref: "../../../../schema/Agent.yaml" + +Authorization: + $ref: "../../../../schema/Authorization.yaml" + +Billing: + $ref: "../../../../schema/Billing.yaml" + +Cancellation: + $ref: "../../../../schema/Cancellation.yaml" + +CancellationTerm: + $ref: "../../../../schema/CancellationTerm.yaml" + +Catalog: + $ref: "../../../../schema/Catalog.yaml" + +Category: + $ref: "../../../../schema/Category.yaml" + +Circle: + $ref: "../../../../schema/Circle.yaml" + +City: + $ref: "../../../../schema/City.yaml" + +Contact: + $ref: "../../../../schema/Contact.yaml" + +Context: + $ref: "../../../../schema/Context.yaml" + +Country: + $ref: "../../../../schema/Country.yaml" + +Credential: + $ref: "../../../../schema/Credential.yaml" + +Customer: + $ref: "../../../../schema/Customer.yaml" + +DecimalValue: + $ref: "../../../../schema/DecimalValue.yaml" + +Descriptor: + $ref: "../../../../schema/Descriptor.yaml" + +Domain: + $ref: "../../../../schema/Domain.yaml" + +Duration: + $ref: "../../../../schema/Duration.yaml" + +Error: + $ref: "../../../../schema/Error.yaml" + +Fee: + $ref: "../../../../schema/Fee.yaml" + +Form: + $ref: "../../../../schema/Form.yaml" + +Fulfillment: + $ref: "../../../../schema/Fulfillment.yaml" + +FulfillmentState: + $ref: "../../../../schema/FulfillmentState.yaml" + +Gps: + $ref: "../../../../schema/Gps.yaml" + +Image: + $ref: "../../../../schema/Image.yaml" + +Intent: + $ref: "../../../../schema/Intent.yaml" + +ItemQuantity: + $ref: "../../../../schema/ItemQuantity.yaml" + +Item: + $ref: "../../../../schema/Item.yaml" + +Location: + $ref: "../../../../schema/Location.yaml" + +MediaFile: + $ref: "../../../../schema/MediaFile.yaml" + +Offer: + $ref: "../../../../schema/Offer.yaml" + +Option: + $ref: "../../../../schema/Option.yaml" + +Order: + $ref: "../../../../schema/Order.yaml" + +Organization: + $ref: "../../../../schema/Organization.yaml" + +Payment: + $ref: "../../../../schema/Payment.yaml" + +Person: + $ref: "../../../../schema/Person.yaml" + +Price: + $ref: "../../../../schema/Price.yaml" + +Provider: + $ref: "../../../../schema/Provider.yaml" + +Quotation: + $ref: "../../../../schema/Quotation.yaml" + +Rating: + $ref: "../../../../schema/Rating.yaml" + +Region: + $ref: "../../../../schema/Region.yaml" + +ReplacementTerm: + $ref: "../../../../schema/ReplacementTerm.yaml" + +ReturnTerm: + $ref: "../../../../schema/ReturnTerm.yaml" + +Scalar: + $ref: "../../../../schema/Scalar.yaml" + +Schedule: + $ref: "../../../../schema/Schedule.yaml" + +State: + $ref: "../../../../schema/State.yaml" + +Stop: + $ref: "../../../../schema/Stop.yaml" + +Support: + $ref: "../../../../schema/Support.yaml" + +Tag: + $ref: "../../../../schema/Tag.yaml" + +TagGroup: + $ref: "../../../../schema/TagGroup.yaml" + +Time: + $ref: "../../../../schema/Time.yaml" + +Tracking: + $ref: "../../../../schema/Tracking.yaml" + +Vehicle: + $ref: "../../../../schema/Vehicle.yaml" + +XInput: + $ref: "../../../../schema/XInput.yaml" diff --git a/docs/beckn-core/docs/BECKN-001-Layering-Network-Policy-Draft-01.md b/docs/beckn-core/docs/BECKN-001-Layering-Network-Policy-Draft-01.md new file mode 100644 index 0000000..b8849dd --- /dev/null +++ b/docs/beckn-core/docs/BECKN-001-Layering-Network-Policy-Draft-01.md @@ -0,0 +1,425 @@ +# Layering Network Policy on the Specification + +## ID: +BECKN-RFC-001 + +## Draft ID +Draft-01 + +## Title: +Layering Network Policy on the Specification + +## Category: +Network Policy + +## Status: +Protocol Draft + +## Published on: +December 10, 2021 + +## Expires on: +December 10, 2022 or Date of publication of next draft which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Ravi Prakash : ravi@becknfoundation.org + +## Reviewers: +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + +# Scope + +This document contains design principles and methodologies that should be used to configure beckn protocol specification for various sector-specific networks. This document is intended for the following audience. + +1. Anyone who is using beckn protocol specifications to design open commerce networks for a specific set of use cases + +# Prerequisites + +Readers of this document must: + +1. Have knowledge of the core protocol specification +2. Have knowledge of the Architecture of Open Commerce Networks instantiated using beckn protocol. +3. Have knowledge of Open API 3.0 Specification + + +# Context + +Beckn protocol is a set of specifications that enables any two platforms to perform commercial transactions by implementing an API with standard action calls and schema. These specifications are by-design generic and therefore, sector agnostic. However, to establish a smart contract between a BAP and a BPP, additional domain-specific information must sometimes be transmitted between the platforms. For example, a logistics network might have different allowed values for the types of fulfillments it supports like “HOME-DELIVERY” and “STORE-PICKUP” as opposed to an education network where the allowed values may be “TELE-CONSULTATION” or “PHYSICAL-CONSULTATION''. These values are not standardized in the core schema but rather exist as _policies_ framed by the architects of a beckn-enabled open commerce network. + +Similarly, a network might put a limit on the number of matched items that can be returned in a single catalog object. To maintain interoperability but also allow its configurability, beckn protocol specification governance restricts modification of the core schema and actions. However, to allow its adaptability, instead of forcing all specification users to adhere to the core specification and, beckn protocol governance allows creation of network-specific policies. These policies allow sector-agnostic rules and validation criteria to be published along with the specification based on recommendations and comments received from various ecosystem contributors and network participants implementing the protocol. These rules and policies must be layered on the core specification and published as a separate document that can be accessed by the network participants in a machine readable manner. + + +# Abstract + +Beckn Protocol is an abstracted but **highly configurable** specification. A network is an **instantiation** of the core protocol specification. However, to instantiate a network, additional policies must be layered via machine-readable configuration files. These configurations vary from network to network depending upon the use cases supported by them. These configurations allow sector-specific policies to be applied on a network _without_ changing the underlying core specification. This document defines a methodology to publish these network-specific policies as machine-readable documents that can be read by network participants to create API validation middleware. + + +# Terminology + + + +1. **Network :** In the context of beckn protocol, a network refers to an open commerce network formed by the instantiation of beckn protocol specification with a standard network policy +2. **Network Participant:** Any platform that has implemented beckn protocol specification and is part of an open commerce network +3. **Schema:** These are JSON Schema objects with properties as defined in +4. **Action:** These are specific events that occur during the lifecycle of a typical commerce transaction +5. **Network Policy**: These are specific rules that apply to the implementers of a network while developing the protocol API middleware + + +# Problem + +Given the Non-Derivative nature of the core specification, how can networks allow configurability of the core specification without disrupting global interoperability? + + +# Forces + +Beckn protocol governance allows highly specific configurations to the core specification via network policies. These policies must be designed not to modify the underlying schema itself but rather govern the values these schema properties are allowed to take like, + + + +1. Adding enumerations to core schema properties +2. Adding additional qualifiers like min / max and defaults +3. Adding sector-specific and region-specific standards to using regex patterns + + +# Expected Outcomes after reading this document + +After reading this document, the reader should be able to + + + +1. Understand how policies can be layered on the core specification +2. Understand how a machine-readable network-specific protocol can be published +3. Understand how such policies can be made available as an infrastructure on a network for dynamic network policy transmission and enforcement + + +# Network Policy as Code + +A network policy is a set of rules that must be published by the architects of beckn-enabled open commerce networks as a machine-readable specification to allow its participants to create protocol validation middleware in their implementations. This specification should **inherit** all the attributes of the core specification along with some additional constraints on the usage of the specification during network transactions. + + +## Inheritance and Polymorphism in Open API 3.0 + +The core specification currently exists in the form of an Open API Specification 3.0 document with some reserved modifications. To layer policy on the specification, beckn protocol governance allows layering of policies by way of configuration. This configuration is done on the core Open API document by using the inheritance and polymorphism feature of Open API Specification 3.0. Inheritance and polymorphism are terms used in Object Oriented Design and are applicable to beckn protocol specifications as well. To learn more about Inheritance and Polymorphism as a generic concept, click here. + +In Open API 3.0, inheritance and Polymorphism are enabled using the “allOf”, “oneOf” and “anyOf” keywords. + + +### The allOf keyword + +While implementing a protocol API, the data-model may have model schemas that share common properties. Instead of describing these properties for each schema repeatedly, it is possible to describe the schemas as a composition of the common property set and schema-specific properties. In OpenAPI version 3, we can do this with the allOf keyword[4] as shown in the example below + + +``` +components: + schemas: + Tags: + type: object + + CategoryTags: + allOf:# Combines the basic Tags model and the inline Category Tags model + - $ref: '#/components/schemas/Tags + - type: object + properties: + brand: + type: string + enum: + - brand + - purpose + - season +``` + + +As shown above, the **CategoryTags** schema introduces a property called “brand” that is extended from the otherwise generic **Tags** object in the core specification. + + +### The oneOf keyword + +This keyword allows the validator to validate a value against exactly one of the subschemas out of several schemas. + + +### The anyOf keyword + +This keyword allows the validator to validate a value against exactly one or more of the subschemas out of several schemas. + + +## Applying Network-Specific Policies using Open API 3.0 + + +### Adding enumerations, defaults and min / max values + +It is possible to add **enumerations**, **defaults**, **min/max** values to any schema. For example, a network may allow only **search** and **confirm** actions. Hence the `context.action` attribute will contain an enumeration of only `search / on_search` and `confirm / on_confirm` API calls as shown below. + + +``` +ContextPolicy1: + description: Describes the context policy of a message on this network + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + type: string + description: Actions supported by this policy + enum: + - search + - confirm + - on_search + - on_confirm + core_version: + type: string + description: Specification versions supported by this policy + enum: + - '0.9.1' + - '0.9.2' + - '0.9.3-draft' + default: 0.9.2 + ttl: + type: string + description: TTL of the message + minimum: P0S + maximum: P1M +``` + + +Another example is related to the **Rating** schema + + +``` +Rating: + description: Describes the rating of a person or an object. + type: object + properties: + rating_category: + description: Category of the object being rated + type: string + id: + description: Id of the object being rated + type: string + value: + description: Rating value given to the object + type: number +``` + + +If a network policy requires rating to range between 1 and 10, it must create a Rating Policy schema that inherits the properties of the Core **Rating** Schema as shown below + + +``` +RatingPolicy1: + description: Describes the context policy of a message on this network + allOf: + - $ref: '#/components/schemas/Rating + - type: object + properties: + value: + type: number + minimum: 1 + maximum: 10 +``` + + + +### Adding alternative schemas + +Sometimes it is possible to have requests and responses that can be described by several alternative schemas. In OpenAPI 3.0, to describe such a model, we can use the oneOf or anyOf keywords. For example, while transmitting payment terms from BPP to the BAP via the **on_init** action, multiple payment endpoints can be sent in the _params_ property of the **Payment** schema as shown below. + + +``` +PaymentParams: + type: object + properties: + transaction_id: + type: string + transaction_status: + type: string + amount: + $ref: '#/components/schemas/Price/properties/value' + currency: + $ref: '#/components/schemas/Price/properties/currency' + required: + - currency + - amount + +PaymentParamsPolicy1: + allOf: + - $ref: '#/components/schemas/PaymentParams' + - type: object + properties: + anyOf: + - $ref: '#/components/schemas/BankTransfer' + - $ref: '#/components/schemas/UnifiedPaymentInterface' + - $ref: '#/components/schemas/PaymentGatewayParams' + +BankTransfer: + type: object + properties: + account_name: + type: string + account_id: + type: string + ifsc: + type: string + +UnifiedPaymentInterface: + type: object + properties: + vpa: + type: string + +PaymentGatewayParams: + type: object + properties: + merchant_id: + type: string + redirect_uri: + type: string +``` + + + +### Adding required fields + +It is also possible to add **required** properties to any attribute. For example, in the domain of mobility, the origin location’s gps coordinate must be a required field. + + +``` +FulfillmentPolicy1: + description: Describes how a mobility service should be fulfilled + type: object + properties: + id: + type: string + description: Unique reference ID to the fulfillment of an order + type: + type: string + description: This describes the type of fulfillment + provider_id: + $ref: '#/components/schemas/Provider/properties/id' + rating: + $ref: '#/components/schemas/Rating/properties/value' + state: + $ref: '#/components/schemas/State' + tracking: + type: boolean + description: Indicates whether the fulfillment allows tracking + default: false + customer: + type: object + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + agent: + $ref: '#/components/schemas/Agent' + vehicle: + $ref: '#/components/schemas/Vehicle' + start: + description: Details on the start of fulfillment + type: object + properties: + location: + allOf: + - $ref: '#/components/schemas/Location' + - required: + - gps + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + end: + description: Details on the end of fulfillment + type: object + properties: + location: + $ref: '#/components/schemas/Location' + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + rateable: + $ref: '#/components/schemas/Rateable' + tags: + $ref: '#/components/schemas/Tags' + +``` + + + +### Adding standards and formats + +A network in India might choose to use the NIC 2004, Industry Classification Codes to identify the Industry Sector of a network via the **Context.domain** attribute as shown below + + +``` +Domain: + description: Describes the industry domain of an object in the country of India. + type: string + pattern: "^nic2004:(52110|52114)" +``` + + + + The above pattern indicates that the network allows only Retail and Delivery transactions + +Adding domain-specific, region-specific, technology-specific attributes or schema to the **Tags** object to accommodate extensions that might get abstracted and merged into core specifications in future releases. For example, a retail network should publish a list of allowed tags for various schemas used by a network. + + +``` +Tags: + description: Describes a tag. This is a simple key-value store which is used to contain extended metadata + additionalProperties: + type: string +``` + + +All these extensions must be published as part of a separate document called **Network Implementation Policy** + +It is recommended that this document be published along with the API specification of that network using the **externalDocs** attribute as defined by Open API Specification 3.0 + +More Examples: + +The specifications allow a network to define a master list of Rating Categories that can be used by NPs. So when creating the API specification of a network, the **rating_categories ** API must define all the allowed rating categories as enums as shown below. + + +``` +Rating: + description: Describes the rating of an object. + type: object + properties: + rating_category: + description: Category of the object being rated + type: string + enum: + - Order + - Fulfillment + - Item + - Provider + - anything else + id: + description: Id of the object being rated + type: string + + value: + description: Rating value given to the object + type: number + minimum: 0 + feedback_form: + $ref: '#/components/schemas/FeedbackForm' + required: false + feedback_id: + $ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id' + required: false +``` diff --git a/docs/beckn-core/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md b/docs/beckn-core/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md new file mode 100644 index 0000000..2c6984c --- /dev/null +++ b/docs/beckn-core/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md @@ -0,0 +1,209 @@ +# Payments on Beckn-Enabled Networks + + +## ID: +BECKN-RFC-002 + +## Draft ID +Draft-01 + +## Title: +Payments on Beckn-Enabled Networks + +## Category: +Payments + +## Status: +Protocol Draft + +## Published on: +December 10, 2021 + +## Expires on: +April 05, 2022 or Date of publication of next draft which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Ravi Prakash : ravi@becknfoundation.org + +## Reviewers: +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + +# Introduction +In beckn-enabled networks, payments are expected to be settled outside the network. Meaning, the implementers of beckn-enabled applications are expected to use existing payment infrastructures in their region(s) of operation to collect, process and settle payments. Since payments is a highly regulated industry across the world, different geo-political regions may choose different standards and modalities to enable digital payments. Therefore, it is left to the implementer to templatize such region-specific payment modalities and dynamically enable them on the respective user applications of both the payer and payee, based on their respective geo-political locations. + + +*it is left to the implementer to templatize such region-specific payment modalities and dynamically enable them on the respective user applications of both the payer and payee, based on their respective geo-political locations...* +== + +# Payment Infrastructure on a Beckn-enabled Network + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Contract-Infrastructure.png) + +# Payment Contract Agreement + +On the protocol layer, only the terms of payment and the proof of payment are exchanged between the BAP and the BPP. Together, the exchange of terms; and the agreement of those terms between the payer and the payee are together known as a **Payment Contract Agreement**. + +It is important to note that beckn protocol only supports the Payment Contract Agreement. The actual act of payment and settlements like charging a card, source bank account debit and destination account remittance are performed asynchronously by integrating with the already established payment infrastructure available in the region of operation like banking APIs, payment gateway / aggregator services, payment processors, open payment protocols etc. + +# Payment Contract Roles +There are two roles that participate in a payment contract agreement on beckn protocol. They are + +- Payer (belongs to BAP): The entity that pays for an order. +- Payee (belongs to BPP): The entity that receives payment for the order + +# Payment Terms + +The money transfer from a Payer to a Payee may go via different channels and modes. For example, a customer may use his credit card to pay the BAP say, at time T=0. The BAP may pay the BPP on T=1 as part of a bulk settlement. The BPP may pay the provider on T=2. And finally the provider may settle the money to the store owner or agent at T=3. At each stage, the intermediary may charge a small transaction fee to process that payment. In beckn protocol, only the settlement terms between the BAP and the BPP are considered. All other payment terms are outside the scope of beckn protocol and are strictly within the scope of the business partnership agreement between the respective parties. + +## BAP Terms +During a transaction, a BAP can inform the BPP its terms and conditions about collecting the payment. +- If it is going to collect the money first + +## BPP Payment Terms +The BPP must send its terms to the BAP . These terms contain the following information: +- The amount that needs to be paid in a specific currency +- The payment endpoint in url format. The supported url schemes are +1. https:// - For payment gateway endpoints +2. payto:// - For all other endpoints as defined in [RFC8095](https://datatracker.ietf.org/doc/html/rfc8905) +- The stage of the order lifecycle when the payment must be made +- When the payment must be settled with the Payee +- Status of the payment + +# Payment Contract Sequence + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-API-Sequence.png) + +# Payment Scenarios on beckn-enabled Networks + +An end-to-end payment flow between a BAP and a BPP comprises of the following activities + +1. Payment collection from buyer: The activity where the money is collected from the buyer +2. Payment settlement with seller: The activity where the money is settled with the seller + +From the buyer to the seller, money may flow through different payment intermediaries. Each intermediary may collect a small transaction fee for processing the transaction. Some common flows are shown below + +## Flow 1: BAP Collects Payment from Buyer + +1. BAP informs BPP that it will be collecting the payment first and then settling it with BPP via beckn protocol APIs +2. BPP agrees to BAP’s terms and allows BAP to collect the payment from the buyer via beckn protocol APIs +3. The BAP shows a payment interface to the buyer and the buyer makes the payment. The money gets deposited into the BAP’s bank account. This is NOT done via any beckn protocol APIs +4. BAP pays BPP : The BAP transfers the amount to the BPP’s bank account +5. BPP pays the Seller + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Settlement-Flow-1.png) + +## Flow 2: BPP collects payment from Buyer + +1. BAP informs BPP that it will NOT be collecting the payment and the BPP should provide the payee details for collection +2. BPP agrees to BAP’s terms and provides the payee details. These details can include a link to the BPP’s payment interface; bank account details or a virtual payment address (in case of UPI) +3. BPP renders the payment interface or other payment details on the BAP’s UI +4. The BAP user makes the payment directly to the BPP +5. BAP queries the BPP for the status of the transaction by providing the proof of payment via beckn protocol APIs +6. BPP periodically checks for transaction success from its Payment Service Provider +7. If payment is successful, the BPP returns the transaction status + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Settlement-Flow-2.png) + +# Invoking the Payment Flow on the BAP app + +Whenever a BAP user wants to checkout an order, the BAP should call the init action on the BPP’s API. The init message contains the final draft of the order that contains the items selected, billing and fulfillment details, or any other information the BPP might need to checkout the order. By calling this action, the BAP should expect the BPP to send the terms of payment along with any additional information needed to make the payment. + +Once the BPP receives the init message, it should send the acknowledgement that it has received the message. The BPP should then send the terms of payment by calling the on_init action on the BAP’s API. Upon receipt of the on_init API call, The BAP must invoke the payment flow on its app to collect the payment from the buyer and asynchronously settle the money with the BPP according to those terms. + +# Payment Object + +| Property | Description | +|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| url | Payment endpoint URL as defined in “BAP Terms” | +| tl_method | Method to call the API URL. supported values are 1. HTTP/GET 2. HTTP/POST 3. PAYTO 4. UPI | +| params | Parameters associated with that URL like 1. amount 2. currency Any other parameters required to authorize the payment like 1. ifsc 2. account 3. vpa (In case of UPI) | +| type | Stage at which the payment should happen. Supported values are: 1. ON-ORDER, 2. PRE-FULFILLMENT, 3. ON-FULFILLMENT, 4. POST-FULFILLMENT | +| time | If the type is “POST_FULFILLMENT”, this field contains the time related information at which the payment must be made | + +# Runtime Payment Object Examples + +## Example 1 +Payment Collection by a BAP and settled at the end of the month to a bank account before 30th of November 2021 + +``` +{ + "collected_by": "bap", + "uri": "payto://bank/98273982749428?amount=$currency:$value&ifsc=$ifsc&message=hello", + "tl_method": "PAYTO", + "type": "POST_FULFILLMENT", + "status": "NOT-PAID", + "params": { + "ifsc": "SBIN0000575", + "value": "200", + "currency": "INR" + }, + "time": { + "range": { + "end": "2021-11-30 00:00:00" + } + } +} +``` + +## Example 2 +Immediate payment on order placement to a UPI Endpoint + +``` +{ + "uri": "payto://upi/example@upi?amount=$currency:$value&message=hello", + "tl_method": "PAYTO", + "type": "ON-ORDER", + "status": "NOT-PAID", + "params": { + "value": "200", + "currency": "INR" + } +} +``` + +## Example 3 +Transfer to a Payment Gateway Endpoint + +``` +{ + "uri": "https://pay.example.com?amount=$value&cur=$currency", + "tl_method": "HTTP/POST", + "type": "ON-ORDER", + "status": "NOT-PAID", + "params": { + "value": "200", + "currency": "INR" + } +} +``` + +## 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&pn=NAME&&tr=123456789&cu=INR&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/docs/beckn-core/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md b/docs/beckn-core/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md new file mode 100644 index 0000000..23a08ea --- /dev/null +++ b/docs/beckn-core/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md @@ -0,0 +1,87 @@ +# Beckn Protocol Communication + +## ID +BECKN-RFC-003 + +## Draft ID +Draft-01 + +## Title +Beckn Protocol Communication + +## Category +Communication + +## Status +Protocol Draft + +## Published on +December 10, 2021 + +## Expires on +December 10, 2021 or Date of publication of next draft which ever is earlier + +## License +CC-BY-ND + +## Authors +1. Ravi Prakash : ravi@becknfoundation.org + +## Reviewers +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + +# Abstract +Communication on beckn enabled networks is server-to-server. Server-to-server means that communication between any two systems on a beckn network does not involve the client application. The client is free to render the data in whatever form chosen by the product. Secondly, all communication is asynchronous. Asynchronous API calls do not block (or wait) for the API call to return from the receiver server in the same session. Instead, an immediate acknowledgment is sent to the sender server in the same session and the actual response from the receiver server is in the form of a callback API call to the sender server. The above two features provide a remarkable advantage as all sorts of innovations are possible in the application layer due to the experience layer being unbundled from the session and presentation layer of the application. + +# Introduction +A beckn enabled network has multiple entities communicating with each other via standard protocol APIs. The following types of communication are possible. + +1. BAP and BG +2. BAP and BPP +3. BG and BPP +4. BAP and Registry +5. BPP and Registry +6. BG and Registry + +All API calls between any two entities on the beckn network are asynchronous. Meaning, an API call from a BAP server (sender) to a BPP server (receiver) does not expect an informational response from a BPP in the same session. The immediate response in the same session is merely an acknowledgement or ACK which basically means, “_Hey, I have received your request and it looks okay during validation of the input. Let me call you back when I have the details you need_”. The actual response is sent later in the form of a standard callback API which the sender is required to implement. + +# Communication Protocol Between 2 Entities + +The sequence diagram of a typical beckn protocol API is shown in Figure 1. For example, let’s say X is the sender and Y is the receiver, and the API being called is **search.** + +In most cases, the sender will call the API first and the receiver will respond immediately with an ACK and close the session. After an arbitrary period of time (which is dependent on the processing of the message), the receiver will respond with an API callback to the sender. The name of the callback API is the name of the sender API with an “on_” prefix. For example, if the request API is called “**search**” then the associated callback API will be “**on_search**”. + +
+ +
Figure 1
+
+ +# Communication Protocol for Search Via Beckn Gateway + +Most communication in a beckn enabled network involves two entities. But sometimes, an intermediate entity like a Beckn Gateway (BG) is involved. In those cases, the flow of communication should be as follows. + +If the address of the BPP is not specified in the context of the API call, then the BAP should call the BG and the BG may multicast this API to multiple BPPs. +The BPPs synchronously respond with ACKs. The BPPs then asynchronously call the **on_search** API which is sent back to the BAP. + +
+ +
Figure 2:
+
+ +# Communication Protocol for Search Via Beckn Gateway with Registry Lookup + +Sometimes the BG may query a Registry via the **lookup** API to get the BPP addresses and then multicast the message to the BPPs. See Figure 3. +
+ +
Figure 3:Search with Registry Lookup
+
+ +# Communication Protocol during status updates + +During the status and on_status calls, the BAP first initiates the transaction by calling **status**. The BAP responds with an **on_status **API call to the BPP just like any other beckn API. However, in the case of the **status** API call, the BPP can asynchronously send multiple **on_status** calls to the BAP after the first call. The BAP does not have to poll the BPP to get an on_status callback. See Figure 4. + +
+ +
Figure 4
+
diff --git a/docs/beckn-core/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md b/docs/beckn-core/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md new file mode 100644 index 0000000..a21f436 --- /dev/null +++ b/docs/beckn-core/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md @@ -0,0 +1,339 @@ +# Policy Administration on Beckn-Enabled Networks + +## ID: +BECKN-RFC-004 + +## Draft ID +Draft-01 + +## Title: +Policy Administration on Beckn-Enabled Networks + +## Category: +Policy + +## Status: +Protocol Draft + +## Published on: +December 10, 2021 + +## Expires on: +December 10, 2022 or Date of publication of next draft which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Ravi Prakash : ravi@becknfoundation.org +2. Sujith Nair : sujith@becknfoundation.org + +## Reviewers: +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + + +# Introduction + +Beckn protocol allows the creation of **Open Commerce Networks**. The primary actors on such networks are BAP, BPP, BG and Registry. Each actor implements an API that enables products and services to be discovered, ordered and fulfilled via a standard API. These API calls correspond to different interactions that happen between a buyer and a seller. + +The messages that are exchanged in these interactions belong to a standard sector-agnostic schema. The schema is very generic but is highly configurable. The configuration is done via the application of constraints and rules on the fields in various schema and subschema. + +Various use cases can be enabled by calling these APIs in different ways. These could be the order in which the APIs are called; the message fields that are mandatory to execute a specific function; the standards and formats that need to be used across all implementors to ensure data interoperability. + +Each network has a logical boundary. This boundary is created by the governance of a network. They will most likely be part of a larger consortium known as a Network Facilitator Organization. The facilitators create the boundary by defining the rules and regulations for various activities that are performed by the network participants starting from implementation to run-time. These rules are published by the creators as part of a document called the **Network Policy**. + +This document contains the methodology to publish, implement and enforce the Network Policy on an Open Commerce Network. The process of publication, implementation and enforcement of network policy is known as **Network Policy Administration**. + +# Network Policy Use Cases + +To get a better understanding of what a network policy outlines, let us take a look at some policy use cases that a network creator might enforce on the participants. + +## Supported Industry Sectors Adaptations + +While the protocol itself is sector agnostic, a network may support only a specific set of industry sectors like “Mobility”, “Retail”, or “Logistics”. These sectors may contain sub-sectors like, say, “On-demand Cab Services”, “Bike Rental”, “Metro services” under the Mobility Sector. Such sectors could be specified by allowing only certain sector codes to be transmitted in the messages. + +## Supported Fulfillment Modes +A network may support various fulfillment flows for various sectors. For example, a retail network may support "STORE-PICKUP" and "HOME-DELIVERY". In the sector of education, a network may support "VIRTUAL-CLASS" and "PHYSICAL-CLASS". These modes may vary with the Industry Sector Adaptations of a network. + +## Catalog Restrictions +A network may place restrictions on a catalog. For example, a network may restrict certain kinds of goods like *illegal items* or *non-essential* items to be listed or searched for. + +## Policy Coverage +A policy may apply to different geo-political regions on the map. It may also apply only during certain time slots. Such spatial and temporal on the policy is called **Policy Coverage** + +## Geo-Spatial Coverage +The network may place geo-spatial constraints on various activities performed on a network. For example, a network may allow certain businesses to operate only within a specific city. This rule may also include exclusion and inclusion zones within a city like containment zones, restricted areas etc. Such restrictions could be implemented by rejecting search requests to exclusion zones. + +## Temporal Coverage +The network may place temporal (time-based) constraints on various activities performed on a network. For example, a network may allow certain businesses to operate only within certain hours of the day, or only on certain days of the week. Sometimes, the network may allow specific platforms to operate for a fixed duration (like a month) as part of a pilot launch. + +# Policy Categories +Policies can be of various categories as shown below + +1. Implementation +2. Registration +3. Subscription +4. Transaction +5. Payment +6. Data Transmission +7. Communication + +# Problem Definition + +How do we set up a digital infrastructure that achieve the following outcomes: +1. Create, view, update and delete network policies for various use cases described above +2. Create, view, update and delete subscriber policies policies of a subscriber +3. Agree or disagree to a network policy +4. View network participants that have agreed / disagreed to specific network policies +5. Dynamically apply network policies as a middleware on protocol implementations +6. Audit network participants for compliance with a network policy + +# Solution Approach + +This section describes the specification to create a digital infrastructure to achieve the above outcomes. It contains +1. Implementation Process +2. Data Model +3. Policy APIs +4. Policy Agreement and Adoption Protocol +5. Reference Architecture +6. Sample Workflow + +# Network Policy Design Principles + +## Ensuring Interoperabililty +The guiding design principle of any network policy is to ensure interoperability at all costs. This can be achieved by publishing sector-specific codes, standards, benchmarks, data exchange mechanisms and supported use cases as Open API files, Policy Registries, Sample Flows and Certification Agencies etc. + +## Avoid Re-imposing Existing Policies +Most sector-specific regulatory policies are already enforced by the authorities of a region and do not need to be re-imposed on a network. For example, if selling unauthorised articles online is an existing policy that has been imposed by a region's authorities, it does not need to be re-imposed as a network policy. The fact that a network participant is on an Open Commerce Network does not change the rules and regulations of the region they are operating in. the Network Facilitators should strive to ensure that the relevant policies are available to the network participants easily without searching for them in various websites and possibly missing some of them. + +## Inclusiveness and Optimal Ignorance +This should be a prime directive of any Network Policy. Before designing a new policy, the policy designers must ask themselves following questions. +1. Is this needed? +2. Is this needed NOW? +3. Does this policy introduce unnecessary regulatory control over the network participants over and above the already established regulations of the industry? +4. Does this policy unnecessarily restrict NPs from registering on a network? + +## API-fication +All policy documents must be available and agreeable via an API. + +## Machine Readability +All policy administrators must strive to encode all policies in a machine readable format. This is of course not mandatory but merely a principle for the administrators to adopt as much as possible. In those cases where policies are subjective and cannot be encoded, they should be present as URLs to pdf documents + +## Non-repudiability +All policies in machine-readable or document format must be accompanied with digital signatures. These signatures must be digitally verifiable by NPs using public keys. + +# Policy Workflow +Policy administrators and network participants can adopt the below workflow. This merely a reference workflow and is not a standard. Networks are free to design their own workflows to ensure better interoperability. + +![Policy Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Workflow-New.png) + +# Policy Framework Roles +1. Policy Adopter (BPPs, BAPs, BGs, Registries) +2. Policy Publisher (SRO or equivalent) +3. Policy Auditor (Monitoring and Reporting) + +# Policy Implementation Architecture + +The below diagram shows a reference policy microservice layered on the transaction layer as a middleware. + +![Policy Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Agreement-Implementation-Architecture.png) + +# Policy Agreement and Adoption Protocol + +The below diagram shows a reference dynamic policy adoption workflow via policy API calls + +![Policy Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Agreement-and-Adoption-Protocol.png) + +# Policy Compliance Audits and Checks + +## Technical Audits +The NFO can engage a testing agency to test policy compliance via an automated test suite + +## Non-technical Audits +### Social Audits by External Agency: +NFO can engage a social audit agency to test compliance of a Subscriber + +### Social Audits by Users: +NFO can mandate that all apps must have a one-click report feature by which users can report any compliance issues with the application to an ODR system. These reports can be viewed by an auditor to fetch any policy compliance violations + +# Policy Layer Data Model +This section describes the minimum schema that must be implemented by any service that enables the above outcomes covering the use cases described above. + +## PolicyCategory + +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|--------|-----------------------------| +| id | string | ID of the policy category | +| name | string | Name of the policy category | + +## SpatialCoverage +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|----------|------------------------------------------| +| id | string | ID of the coverage | +| location | Location | Location of coverage | +| type | string | Enum ( “incl”, “excl” ), Default: “incl” | + +## TemporalCoverage +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|--------|------------------------------------------| +| id | string | ID of the coverage | +| time | Time | Time of coverage | +| type | string | Enum ( “incl”, “excl” ), Default: “incl” | + +## SubscriberCoverage +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|---------------|---------|------------------------------------------| +| id | string | ID of coverage | +| subscriber_id | string | ID of the subscriber | +| type | string | Enum ( “incl”, “excl” ), Default: “incl” | + +## SchemaOverride +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|-----------------|--------|---------------------------------------------| +| id | string | ID of row | +| target_schema | Time | Schema to be overriden | +| override_schema | string | Schema that has to override existing schema | + +## Action +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|--------|-------------------------| +| id | string | ID of protocol action | +| action | string | Name of protocol action | + +## ProtocolVersion +### Description +The protocol version of the specification + +### Type +string + +### Properties + + +## Policy +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|---------------------|--------------------|-------------------------------------| +| id | string | ID of policy | +| category | string | Category ID of policy | +| parent_policy_id | Time | Parent Policy | +| protocol_version | ProtocolVersion | Applicable protocol version | +| action | Action | Applied to action | +| schema_policy | SchemaPolicy | ID of schema policy | +| spatial_coverage | SpatialCoverage | Spatial Coverage of policy | +| temporal_coverage | TemporalCoverage | Temporal Coverage of policy | +| subscriber_coverage | SubscriberCoverage | Subscriber Coverage | +| published_on | DateTime | Date on which this was published | +| applicable_from | DateTime | Date from which this policy applies | +| expires_on | DateTime | Date on which this policy expires | +| signature | string | Digital Signature of publisher | +| attachment | string | URL of attached document | + +## PolicyManifest + +### Description +The complete list of policies published by a Network Subscriber + +### Type +object + +### Properties +| Property | Type | Description | +|-----------|----------------|---------------------| +| id | string | ID of manifest | +| policies | Array (Policy) | Array of policies | +| Meta info | string | Any additional info | + +## PolicyDifference +### Description +This is the diff of the policy files + +### Type +string + +## PolicyConflict +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|-----------|------------------|-----------------------------------------------| +| policy_id | boolean | Indicates if there is a conflict of interest | +| diff | PolicyDifference | A diff between existing and new schema | +| reason | ConflictReason | Reason for the conflict of interest | + +## ConflictReason +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|-------------|-------------| +| code | string enum | Reason code | + +#### Reason Codes Enumeration + +**NETWORK_POLICY_VIOLATION** +The adopter should return this code if the new policy violates the default network policy. + +**SELLER_POLICY_VIOLATION** +The adopter should return this code if the new policy violates the default seller policy, then. + + + + diff --git a/docs/beckn-core/docs/BECKN-005-Error-Codes-Draft-01.md b/docs/beckn-core/docs/BECKN-005-Error-Codes-Draft-01.md new file mode 100644 index 0000000..a720871 --- /dev/null +++ b/docs/beckn-core/docs/BECKN-005-Error-Codes-Draft-01.md @@ -0,0 +1,69 @@ +# Error Codes for BPP + +## ID: +BECKN-005 + +## Draft ID +Draft-01 + +## Title: +Error Codes + +## 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 : ravi@becknfoundation.org + +## 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.* diff --git a/docs/beckn-core/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md b/docs/beckn-core/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md new file mode 100644 index 0000000..0e93d55 --- /dev/null +++ b/docs/beckn-core/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md @@ -0,0 +1,442 @@ +# Signing Beckn APIs in HTTP - Draft 04 + +## Context +When communicating over HTTP using Beckn APIs, the subscribers need to authenticate themselves to perform transactions with other subscribers. Due to the commercial nature of the transactions, every request/callback pair is considered to be a "contract" between two parties. Therefore, it is imperative that all requests and callbacks are digitally signed by the sender and subsequently verified by the receiver. +Furthermore, it is also desirable to ensure that the message was not altered or tampered with during transit. +This document describes a way for network subscribers (BAP/BPPs) and proxy subscribers (BGs) to simultaneously add authentication and message integrity to HTTP messages by using digital signatures. How the signatures are generated and the format of those signatures is out of scope of this document and can be found in this IETF document - [Signing HTTP Messages](https://tools.ietf.org/id/draft-cavage-http-signatures-12.html). +This document specifies the algorithms used in generating the keys, how to construct the signing strings being passed in the headers. Also, it specifies clearly the format of the HTTP headers used for authenticating BAP, BPPs and BGs. + +## Subscriber Authentication + +The BAP and BPP subscriber is expected to send an `Authorization` header (as defined in [RFC 7235](https://tools.ietf.org/id/draft-cavage-http-signatures-12.html#RFC7235), [Section 4.1](https://tools.ietf.org/html/rfc7235#section-2.1)) where the "auth-scheme" is "Signature" and the "auth-param" parameters meet the requirements listed in Section 2 of [this](https://tools.ietf.org/id/draft-cavage-http-signatures-12.html) document. + +The BG subscriber is expected to send a `X-Gateway-Authorization` header where the "auth-scheme" is "Signature" and the "auth-param" parameters meet the requirements listed in Section 2 of [this](https://tools.ietf.org/id/draft-cavage-http-signatures-12.html) document. + +Below is the format of a BAP/BPP Authorization header in the typical HTTP Signature format: + +``` +Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(ed25519_sign(signing string))" +``` + +The BG will send its signature in the `X-Gateway-Authorization` header in the exact same format as shown below. + +``` +X-Gateway-Authorization:Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}", algorithm="ed25519", created="1606970629", expires="1607030629", headers="(created) (expires) digest", signature="Base64(ed25519_sign(signing string))" +``` + +### Signature Attributes + +#### keyID: +The KeyID is a string that uniquely identifies a subscriber's key(s) on the network. It has three components. + +1. `subscriber_id`: It is by default the FQDN of the subscriber endpoint. However, for platforms that do not have an FQDN, a different identifier may be recommended by the network policy. +2. `unique_key_id` : It is an ID generated by the registry when an entry for a subscriber is created in its database. The recommended format for `unique_key_id` is `uuid`. +3. `algorithm` : The signing algorithm used. Its value is same as the value in the `algorithm` attribute as per recommendations in [Signing HTTP Messages](https://tools.ietf.org/id/draft-cavage-http-signatures-12.html) + +#### algorithm: +This is the signing algorithm used for generating the signature. As per current specificaiton, it is recommended to use `ed25519` as its value. + +#### created +Contains the timestamp when the signature was created + +#### expires +Contains the timestamp when the signature will expire + +#### headers +The HTTP headers that will be used in addition to the request body to generate the signing string + +#### signature +The signature of the request + +## Hashing Algorithm + +For computing the digest of the request body, the hashing function will use the BLAKE-512 (2b) hashing algorithm. BLAKE is a cryptographic hashing function based on **Dan Bernstein's ChaCha stream cipher**. For more documentation on the BLAKE-512(2b) algorithm, please go to [RFC7693](https://tools.ietf.org/html/rfc7693). + +Example of a Blake 512 [hash](https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE2b_algorithm) is shown below: + +``` +BLAKE2b-512("The quick brown fox jumps over the lazy dog") = +a8add4bdddfd93e4877d2746e62817b116364a1fa7bc148d95090bc7333b3673f82401cf7aa2e4cb1ecd90296e3f14cb5413f8ed77be73045b13914cdcd6a918 +``` + +The above hex value encoded in base64 is as below : + +``` +qK3Uvd39k+SHfSdG5igXsRY2Sh+nvBSNlQkLxzM7NnP4JAHPeqLkyx7NkCluPxTLVBP47Xe+cwRbE5FM3NapGA== +``` + +## Signing Algorithm +To digitally sign the signing string, the subscribers should use the "ed25519" signature scheme. + +### Example Flow (BAP <=> BG <=> BPP) + +### Step 1 : BAP signs request and calls BG +Let the below be the request body in this example : + +``` +{"context":{"domain":"nic2004:60212","country":"IND","city":"Kochi","action":"search","core_version":"0.9.1","bap_id":"bap.stayhalo.in","bap_uri":"https://8f9f-49-207-209-131.ngrok.io/protocol/","transaction_id":"e6d9f908-1d26-4ff3-a6d1-3af3d3721054","message_id":"a2fe6d52-9fe4-4d1a-9d0b-dccb8b48522d","timestamp":"2022-01-04T09:17:55.971Z","ttl":"P1M"},"message":{"intent":{"fulfillment":{"start":{"location":{"gps":"10.108768, 76.347517"}},"end":{"location":{"gps":"10.102997, 76.353480"}}}}}} +``` + +Let BAP’s keys be : + +``` +signing_public_key=awGPjRK6i/Vg/lWr+0xObclVxlwZXvTjWYtlu6NeOHk= +signing_private_key=lP3sHA+9gileOkXYJXh4Jg8tK0gEEMbf9yCPnFpbldhrAY+NErqL9WD+Vav7TE5tyVXGXBle9ONZi2W7o144eQ== +``` + +The BAP performs the following steps to create the Authorization header +1. Generate the digest of the request body using the BLAKE-512 hashing function + +`b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw==` + +2. Generate the created field. The `created` field expresses when the signature was created. The value MUST be a Unix timestamp integer value. A signature with a `created` timestamp value that is in the future MUST NOT be processed. + +``` +(created): 1641287875 +``` + +3. Generate the expires field. The `expires` field expresses when the signature ceases to be valid. The value MUST be a Unix timestamp integer value. A signature with an `expires` timestamp value that is in the past MUST NOT be processed. + +``` +(expires): 1641291475 +``` + +4. Concatenate the three values, i.e the `created`, `expires` and `digest` in the format as shown below. The below string is the signing string which the BAP is going to use to sign the request + +``` +(created): 1641287875 +(expires): 1641291475 +digest: BLAKE-512=b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw== +``` + +5. The BAP will then sign this string using it's registered signing private key via the Ed25519 Signature Scheme + +7. Finally the BAP will generate a base64 encoded string of the signature and insert it into the signature parameter of the Authorization header + +`cjbhP0PFyrlSCNszJM1F/YmHDVAWsZqJUPzojnE/7TJU3fJ/rmIlgaUHEr5E0/2PIyf0tpSnWtT6cyNNlpmoAQ==` + +7. Finally the Authorization header will look like this. (Let's assume subscriber_id = example-bap.com, unique_key_id = bap1234) + +``` +Signature keyId="example-bap.com|ae3ea24b-cfec-495e-81f8-044aaef164ac|ed25519",algorithm="ed25519",created="1641287875",expires="1641291475",headers="(created) (expires) digest",signature="cjbhP0PFyrlSCNszJM1F/YmHDVAWsZqJUPzojnE/7TJU3fJ/rmIlgaUHEr5E0/2PIyf0tpSnWtT6cyNNlpmoAQ==" +``` + +8. Finally the BAP includes the `Authorization` header in the request and calls the BG API + + +**Note:** +The `expires` value should not be more than the expiration time of the key used for signing the request. If the expires value appears to be going beyond the lifespan of the signing key, generate a new key and update it on the registry OR use an existing registered key with an expiry time greater than the `expires` value of the signature. + + +### Step 2 : BG verifies BAP signature + +The BG performs the following steps to authenticate the BAP and also ensure message integrity. + +1. BG gets `keyId` from the `Authorization` header + +`example-bap.com|ae3ea24b-cfec-495e-81f8-044aaef164ac|ed25519` + +2. BG splits the `keyId` string into subscriber ID, Unique Key ID and algorithm using the delimiter "|". +3. The keyId uses the format {subscriber id}|{unique_key_id}|{signing algorithm} . If the signing algorithm extracted from the keyId does not match the value of the algorithm parameter in the Authorization header, then the BG should return an 401 unauthorised error. +4. The keyId also contains a unique_key_id which is used when the BAP has uploaded multiple public keys to a registry +5. The BG will now look up the registry for the public key of the subscriber by sending the subscriber_id and the unique_key_id via the `lookup` API or by retrieving a cached copy of the subscriber's public key matching the subscriber_id and unique_key_id.It will receive the public key of the BAP : + +`awGPjRK6i/Vg/lWr+0xObclVxlwZXvTjWYtlu6NeOHk=` + +6. If no valid key is found, the BPP must return a NACK response with 401 Unauthorised response code. +7. BG will use the BAP's public key to verify the signature. If signature is verified, the BAP is considered to be authenticated. If not BG should return a 401 error. +8. If the signature is not verified, the BG must return a NACK response with 401 Unauthorised response code with a WWW-Authenticate header. For example, for an invalid signature, the BG must return the following: + +**Headers:** + +``` +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Signature realm="example-bg.com",headers="(created) (expires) digest" +... +``` + +**Request Body:** +``` +{ + "message": { + "ack": { + "status": "NACK" + } + } +} +``` + +**NOTE : If the network policy does not allow more than one key-pair per subscriber on the registry, then the `unique_key_id` component is NOT NEEDED in the `keyId` attribure. In such a case, the Authorization header will look like this. + + +### Step 3 : BG signs request before forwarding request to BPP +Let the BG’s keys be : + +``` +signing_public_key=7YRZXVeIJ0/Va56vYgzT1Uirg6mnq3FY0MBZY9DJft0= +signing_private_key=hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q== +``` + +Before forwarding the request to the BPP, the BG performs the following steps to create the X-Gateway-Authorization header. + +1. Generate the digest of the request body using the BLAKE-512 hashing function + +`b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw==` + +2. Generate the `created` field. The `created` field expresses when the signature was created. The value MUST be a Unix timestamp integer value. A signature with a `created` timestamp value that is in the future MUST NOT be processed. + +`(created): 1641287885` + +3. Generate the `expires` field. The `expires` field expresses when the signature ceases to be valid. The value MUST be a Unix timestamp integer value. A signature with an `expires` timestamp value that is in the past MUST NOT be processed. + +`(expires): 1641291485` + +4. Concatenate the three values, i.e the `created`, `expires` and `digest` in the format as shown below. The below string is the signing string which the BG is going to use to sign the request + +``` +(created): 1641287885 +(expires): 1641291485 +digest: BLAKE-512=b6lf6lRgOweajukcvcLsagQ2T60+85kRh/Rd2bdS+TG/5ALebOEgDJfyCrre/1+BMu5nA94o4DT3pTFXuUg7sw== +``` + +5. The BG will then sign this string using its registered signing private key via the Ed25519 Signature Scheme +6. Finally the BG will generate a base64 encoded string of the signature and insert it into the signature parameter of the X-Gateway-Authorization header + +`hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q==` + +7. Finally the `X-Gateway-Authorization` header will look like this. (Let's assume `subscriber_id` = example-bg.com, `unique_key_id` = ae3ea24b-cfec-495e-81f8-044aaef164ac) + +``` +Signature keyId="example-bg.com|dfb974ea-9113-4089-9a2d-77552b50624e|ed25519",algorithm="ed25519",created="1641287885",expires="1641287885",headers="(created) (expires) digest",signature="hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q==" +``` + +8. Finally the BG includes the X-Gateway-Authorization header in the request and calls the BPP search API + +**Note:** +3. The difference between the `created` and the `expires` field should be equal to the TTL of the request. +4. Also, the `expires` value should not be more than the expiration time of the key used for signing the request. If the expires value appears to be going beyond the lifespan of the signing key, generate a new key and update it on the registry via subscribe API OR use an existing registered key with an expiry time greater than the `expires` value of the signature + + + +### Step 4 : BPP verifies BG signature +The BPP performs the following steps to authenticate the BAP and the BG and also ensure message integrity. + +1. Get keyId from the X-Gateway-Authorization header + +`example-bg.com|bg3456|ed25519` + +2. Split the keyID string using the delimiter `|`. +3. The keyID uses the format {subscriber id}|{unique_public_key_id}|{signing algorithm} . If the signing algorithm extracted from the keyId does not match the value of the algorithm field in the X-Gateway-Authorization header, then the BPP should return an error. +4. The keyID also contains a unique_public_key_id which is used when the BG has uploaded multiple public keys to a registry OR when the same domain is being used for implementing multiple subscribers. +5. The BG will now look up the registry for the public key of the subscriber by sending the subscriber_id and the unique_key_id via the `lookup` API or from a _cached copy_ of the registry + +6. If no valid key is found, the BPP must return a NACK response with 401 Unauthorised response code. +7. BPP will use the BG's public key to verify the signature. If the signature is verified, the BG is considered to be authenticated. +8. If the signature is not verified, the BPP must return a NACK response with 401 Unauthorised response code with a Proxy-Authenticate header. For example, for an invalid BG signature, the BPP must return the following: + +**Headers:** + +``` +HTTP/1.1 401 Unauthorized +Proxy-Authenticate: Signature realm="example-bpp.com",headers="(created) (expires) digest" +... +``` + +**Request Body:** + +``` +{ + "message": { + "ack": { + "status": "NACK" + } + } +} +``` + + + +### Step 5 : BPP verifies BAP signature +The BPP performs the following steps to authenticate the BAP and also ensure message integrity during transit. + +1. BPP gets keyId from the Authorization header. +2. BPP splits the keyID string using the delimiter `|`. +3. The keyID uses the format {subscriber id}|{unique_key_id}|{signing algorithm}. If the signing algorithm extracted from the keyId does not match the value of the algorithm field in the Authorization header, then the BPP should return an error. +4. The keyId also contains a unique_public_key_id which is used when the BAP has uploaded multiple public keys to a registry OR when the same domain is being used for implementing multiple types of subscribers. +5. The BPP will now look up the registry for the public key of the BAP by sending the subscriber_id and the unique_key_id via the lookup API or by retrieving a cached copy of the BAP's public key matching the subscriber_id and unique_key_id. +6. BG will use the BAP's public key to verify the signature. If signature is verified, the BAP is considered to be authenticated. If not BG should return a 401 error. +7. If the signature is not verified, the BG must return a NACK response with 401 Unauthorised response code with a WWW-Authenticate header. For example, for an invalid signature, the BPP must return the following: + +**Headers** + +``` +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Signature realm="example-bpp.com",headers="(created) (expires) digest" +... +``` + +**Request Body** + +``` +{ + "message": { + "ack": { + "status": "NACK" + } + } +} +``` + + + +### Step 6 : BPP signs callback and calls BG +The BPP performs the following steps to create the Authorization header + +1. Generate the digest of the request body using the BLAKE-512 hashing function. +2. Generate the created field. The `created` field expresses when the signature was created. The value MUST be a Unix timestamp integer value. A signature with a `created` timestamp value that is in the future MUST NOT be processed. +3. Generate the expires field. The `expires` field expresses when the signature ceases to be valid. The value MUST be a Unix timestamp integer value. A signature with an `expires` timestamp value that is in the past MUST NOT be processed. +4. Concatenate the three values, i.e the `created`, `expires` and `digest` in the format as shown below. The below string is the signing string which the BPP is going to use to sign the request. + +``` +(created): 1402170695 +(expires): 1402170995 +digest: BLAKE-512=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= +``` + +5. Sign this string using it's registered signing private key via the ed25519 Signature Scheme. +6. Generate a base64 encoded string of the signature and insert it into the signature parameter of the Authorization header. +7. The final Authorization header will look like this. (Let's assume subscriber_id = example-bpp.com, unique_key_id = bpp5678). + +``` +Signature keyId="example-bpp.com|74b43deb-236e-4498-8f5a-ca75d6c67b9d|ed25519",algorithm="ed25519",created="1641287885",expires="1641287885",headers="(created) (expires) digest",signature="hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q==" +``` + +9. Finally the BPP includes the Authorization header in the request and calls the BG API. + + + +### Step 7 : BG verifies BPP signature +The BG performs the following steps to authenticate the BPP and also ensure message integrity. + +1. BG gets keyId from the Authorization header. +2. BG splits the keyId string into subscriber ID, Unique Key ID and algorithm using the delimiter "|". +3. The keyId uses the format {subscriber id}|{unique_key_id}|{signing algorithm} . If the signing algorithm extracted from the keyId does not match the value of the algorithm parameter in the Authorization header, then the BG should return an 401 unauthorised error. +4. The keyId also contains a unique_key_id which is used when the BPP has uploaded multiple public keys to a registry OR when the same domain is being used for implementing multiple types of subscribers. +5. The BG will now look up the registry for the public key of the BPP by sending the subscriber_id and the unique_key_id via the lookup API or by retrieving a cached copy of the BPP's public key matching the subscriber_id and unique_key_id. +6. BG will use the BPP's public key to verify the signature. If signature is verified, the BPP is considered to be authenticated. If not BG should return a 401 error +7. If the signature is not verified, the BG must return a NACK response with 401 Unauthorised response code with a WWW-Authenticate header. For example, for an invalid signature, the BG must return the following: + +**Headers** + +``` +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Signature realm="example-bg.com",headers="(created) (expires) digest" +... +``` + +**Request Body** + +``` +{ + "message": { + "ack": { + "status": "NACK" + } + } +} +``` + + +### Step 8 : BG signs callback before calling BAP +Before forwarding the request to the BAP, the BG performs the following steps to create the X-Gateway-Authorization header + +1. Generate the digest of the request body using the BLAKE-512 hashing function. +2. Generate the `created` field. The `created` field expresses when the signature was created. The value MUST be a Unix timestamp integer value. A signature with a `created` timestamp value that is in the future MUST NOT be processed. +3. Generate the `expires` field. The `expires` field expresses when the signature ceases to be valid. The value MUST be a Unix timestamp integer value. A signature with an `expires` timestamp value that is in the past MUST NOT be processed. +4. Concatenate the three values, i.e the `created`, `expires` and `digest` in the format as shown below. The below string is the signing string which the BG is going to use to sign the request. + +``` +(created): 1402170695 +(expires): 1402170995 +digest: BLAKE-512=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE= +``` + +5. The BG will then sign this string using it's registered signing private key via the ed25519 Signature Scheme. +6. Finally the BG will generate a base64 encoded string of the signature and insert it into the signature parameter of the X-Gateway-Authorization header. +7. Finally the X-Gateway-Authorization header will look like this. (Let's assume subscriber_id = example-bg.com, unique_key_id = bg3456). + +``` +Signature keyId="example-bg.com|dfb974ea-9113-4089-9a2d-77552b50624e|ed25519",algorithm="ed25519",created="1641287885",expires="1641287885",headers="(created) (expires) digest",signature="hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q==" +``` + +8. Finally the BG includes the X-Gateway-Authorization header in the request and calls the BAP API. + +**Note:** + +1. The difference between the `created` and the `expires` field should be equal to the TTL of the request. +2. Also, the `expires` value should not be more than the expiration time of the key used for signing the request. If the expires value appears to be going beyond the lifespan of the signing key, generate a new key and update it on the registry via subscribe API OR use an existing registered key with an expiry time greater than the `expires` value of the signature. + + +### Step 9 : BAP verifies BG signature +The BAP performs the following steps to authenticate the BAP and the BG and also ensure message integrity. + +1. Get keyId from the X-Gateway-Authorization header +2. Split the keyID string using the delimiter `|`. +3. The keyID uses the format {subscriber id}|{unique_public_key_id}|{signing algorithm} . If the signing algorithm extracted from the keyId does not match the value of the algorithm field in the X-Gateway-Authorization header, then the BPP should return an error. +4. The keyID also contains a unique_public_key_id which is used when the BG has uploaded multiple public keys to a registry OR when the same domain is being used for implementing multiple subscribers +5. The BAP will now look up the registry for the public key of the subscriber by sending the subscriber_id and the unique_key_id via the lookup API or by retrieving a cached copy of the subscriber's public key matching the subscriber_id and unique_key_id. If no valid key is found, the BPP must return +6. BPP will use the BG's public key to verify the signature. If signature is verified, the BG is considered to be authenticated. +7. If the signature is not verified, the BPP must return a NACK response with 401 Unauthorised response code with a Proxy-Authenticate header. For example, for an invalid BG signature, the BAP must return the following: + +**Headers** + +``` +HTTP/1.1 401 Unauthorized +/Proxy-Authenticate: Signature realm="example-bap.com",headers="(created) (expires) digest" +... +``` + +**Request Body** + +``` +{ + "message": { + "ack": { + "status": "NACK" + } + } +} +``` + + +### Step 10 : BAP verifies BPP signature +The BAP performs the following steps to authenticate the BAP and also ensure message integrity during transit. + +1. BAP gets keyId from the Authorization header +2. BAP splits the keyID string using the delimiter `|`. +3. The keyID uses the format {subscriber id}|{unique_public_key_id}|{signing algorithm} . If the signing algorithm extracted from the keyId does not match the value of the algorithm field in the Authorization header, then the BAP should return an error. +4. The keyId also contains a unique_public_key_id which is used when the BPP has uploaded multiple public keys to a registry OR when the same domain is being used for implementing multiple types of subscribers +5. The BAP will now look up the registry for the public key of the BPP by sending the subscriber_id and the unique_key_id via the lookup API or by retrieving a cached copy of the BPP's public key matching the subscriber_id and unique_key_id +6. BAP will use the BPP's public key to verify the signature. If signature is verified, the BPP is considered to be authenticated. +7. If the signature is not verified, the BAP must return a NACK response with 401 Unauthorised response code with a WWW-Authenticate header. For example, for an invalid BPP signature, the BAP must return the following: + +**Headers** + +``` +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Signature realm="example-bap.com",headers="(created) (expires) digest" +... +``` + + +**Request Body:** + +``` +{ + "message": { + "ack": { + "status": "NACK" + } + } +} +``` diff --git a/docs/beckn-core/docs/BECKN-007-The-XInput-Schema.md b/docs/beckn-core/docs/BECKN-007-The-XInput-Schema.md new file mode 100644 index 0000000..e0e9012 --- /dev/null +++ b/docs/beckn-core/docs/BECKN-007-The-XInput-Schema.md @@ -0,0 +1,474 @@ +# The XInput Schema +#### CWG Working Draft - November 08, 2022 + +## Document Details +### This version +https://github.com/beckn/protocol-specifications/blob/release-1.x/docs/BECKN-007-The-XInput-Schema.md + +### Latest published version +TODO + +### Latest editor's draft +TODO + +### Implementation report +TODO + +### Editors +Ravi Prakash (Beckn Foundation) + +### Authors +Ravi Prakash (Beckn Foundation) + + +### Feedback + +Issues: TODO +Discussions: TODO +PRs: TODO + + +### Errata +No Errata exists as of now + + +## Context +Beckn protocol defines a domain-agnostic specification that can be used to represent any customer- provider transaction by implementing a standard set of APIs and schema. Creating a transaction ideally involves the customer discovering products and services offered by various providers, selecting the desired products or services, obtaining the terms of service and payment, and then finally confirming the order. But sometimes, the provider might require additional metadata in order to confirm a transaction. This requirement may be due to legal requirements imposed by the regulatory authorities, or business requirements to allow better serviceability. + +For example, a logistics service provider might require additional information from the logistics customer (like a restaurant) like the dimensions of the package, category of items (food, flammable, fragile etc), approximate weight of the package, the order Number etc, + +to confirm the order. All of this information needs to be transmitted to the person availing the logistics service. + +Similarly, a healthcare service might want the patient to provide information like, their medical history, a description of their symptoms, details of the insurance, etc, before confirming the order. + +The nature of additional information required could vary significantly across sectors. These fields could be varied and many, and adding them as protocol attributes would make the protocol bulky and cluttered. + + +## Problem + +We require an object that captures additional information (over and above what has been published in the catalog) from the customer regarding the item being ordered without extending the core transaction protocol. + + +## Solution + +It is probably not such a good idea to transmit such required data fields as first class citizens of the transaction protocol, rather transmit them in some sort of a custom form object. This form could be a simple HTML form hosted on a url endpoint or transmitted as a whole as per standard form specifications like [XForms 2.0](https://www.w3.org/TR/xforms20/). + +The proposed design of this feature is as follows. + +It starts with a schema called `XInput` of type `Form`. The definition of `Form` is also shown here among other relevant schemas. + +``` + XInput: + type: object + properties: + form: + $ref: Form + required: + description: Indicates whether the form data is mandatorily required by the BPP to confirm the order. + type: boolean + default: true + + Form: + description: Describes a form that needs to be rendered to the BAP user before the confirmation of an order. + type: object + properties: + url: + description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. The BAP can choose to render the form as-is as an embeddable element, or process it further to blend it with the style of the application. In case the interface is non-visual, the BAP can process the form data and reproduce it as per the UI requirements. + type: string + format: uri + mime_type: + description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. If the mime_type is text/html, the application must render it inside a web view. If the mime_type is application/xml, then the application must consider it as an xForms 2.0 object and render it as per the XForms 2.0 specification. + type: string + enum: + - text/html + - application/xml + submission_id: + type: string + format: uuid + + FormResponse: + description: Describes the response to a form submission + type: object + properties: + status: + description: Contains the status of form submission. + type: boolean + default: true + submission_id: + description: This contains a UUID generated by the BPP on successful submission of the form. + type: string + format: uuid + errors: + type: array + items: + $ref: Error + + Error: + description: Describes an error object returned by the API in case of an exception scenario. The exception may be a technical one like a schema or a signature verification error; or business-related like an item not found, or an agent not available. + type: object + properties: + code: + type: string + description: For full list of error codes, refer to docs/protocol-drafts/BECKN-RFC-005-ERROR-CODES-DRAFT-01.md of this repo + path: + type: string + description: Path to json schema generating the error. Used only during json schema validation errors + message: + type: string + description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user. + required: + - code + - path +``` + +### Usage +The `XInput` object can be found in the following schemas +1. Item +2. Order +3. Feedback +4. CancellationTerm + +#### Usage in the `Item` schema +``` +Item: + type: object + properties: + xinput: + $ref: '#/components/schemas/XInput' + ... +``` +This usage means that the BAP user is expected to provide additional information over and above the ID of +#### Usage in the `Order` schema +``` +Order: + type: object + properties: + xinput: + $ref: '#/components/schemas/XInput' + ... +``` + +``` + +#### Usage in the `CancellationTerm` schema +``` +CancellationTerm: + type: object + properties: + xinput: + $ref: '#/components/schemas/XInput' + ... +``` +### Recommendations for BPPs + +The following recommendations are for BPPs who will create the form to be rendered on BAPs and receive the submissions from it. + + +#### Declaring the form + +- BPPs that require additional information pertaining to individual items being ordered to confirm an order, must send the `xinput` object in the `Item` schema with a form object containing a link to the form with item-specific fields. For example, a person buying an airline ticket containing two flights - an onward Journey by Etihad and a return journey by Lufthansa might have to provide his Etihad membership code for his onward journey. For his return journey, Lufthansa might require them to declare their luggage dimensions, and upload a Covid-19 vaccination certificate. +- If BPPs require additional information pertaining to the order as a whole, they must send the xinput object in the Order schema containing a link to the form with order-specific information. For example, a cash on delivery grocery order from a store might require the store owner to declare the amount to be collected, the number of items, package category, and the weight of the package before placing the order. +- If the form is cacheable, then it is recommended for BPPs to send the form link during `on_search` itself. +- If the form is dynamic, then it is recommended for BPPs to send the form link during `on_select`, or `on_init` wherever applicable. + + +#### Modeling the form + +- BPPs can model the form in two ways namely, a) using HTML5 Forms, or b) xForms 2.0 objects +- For creating HTML Forms, please refer to [this](https://www.w3schools.com/html/html_forms.asp) tutorial +- For creating xForms 2.0 Forms, please refer to [this](https://www.w3.org/TR/xforms20/) specification +- Networks can mandate only one, or both types of form specification. (For new networks, it is recommended to start with HTML forms) +- For HTML forms the submission url will be present in the action attribute of the form tag as highlighted in the example below +``` +
…
+``` +- For xForms 2.0 forms, the submission url will be present in the action attribute of the xform:submissions tag as highlighted in the example below +``` + +``` +- It is _not recommended_ for BPPs to send `script` tags along with HTML forms as it will pose a security concern for BAPs +- It is _not recommended_ for BPPs to send `style` tags along with HTML forms as BAPs may re-render the form as per their UI +- It is _not recommended_ for BPPs to send `button` tags along with HTML forms as BAPs may render the CTA for form submission according to their UI +- For XForms 2.0 submissions, the BPP can send the <xforms:submission /> tag to specify submission URL, but it will not be rendered at the BAP. + + +#### Handling form requests + +- The form must be hosted on a trusted url, preferably with the same domain name as the BPP’s subscriber_id to avoid security-related errors thrown by BAPs. +- When requested on HTTP, the BPPs must return Content-type: text/html or application/xml in the response body headers. +- It is _recommended_ to send a unique nonce value in UUID format whenever it receives a form request from a BAP and persist it until a submission matches the nonce or the form expires + + +#### Handling form submissions + +- The form submission method must always be a HTTP/POST when using HTTP as a transport layer. Example: `
` +- The form submission API must also be on the same domain name as the BPP subscriber_id to avoid security-related errors thrown by BAPs +- Form submission request should be digitally signed by the BAP +- The following algorithm must be executed at the BPP when the form is submitted on HTTP/POST, +- Check if signature is valid +- Check if the nonce value exists and is not expired +- If the nonce value exists and is not expired + * Validate the form inputs + * Generate a **FormResponse** object and return it as an `application/json` response +- BPPs must persist this UUID at their ends so that they can match each submission with the corresponding confirm API call + + +#### Linking form submission to existing transactions + +* After successful form submissions, the BPP should ideally receive a confirm API call containing references to the submissions. +* The form submission references can be found in Order.items[ ].xinput_required.form.submission_id, and Order.xinput_required.form.submission_id fields. + + +#### Discarding Form Submissions +* The BPP can choose to discard the form submissions if the confirm API call does not arrive within a specified time window after the form has been submitted + + +### Recommendations for BAPs +The following recommendations are for BAPs who will render the form to its users and send the submissions to the BPPs. + + +#### Identifying form declarations +* BAPs can identify required item-specific form inputs by parsing the Item schema received in on_search callbacks. +* BAPs must also check for required order-specific form inputs by parsing the Order schema received in on_select, and on_init callbacks. +* The BAP may choose to cache the form by calling the `{Item}.xinput.form.url` endpoint from its API endpoint. +* It should expect either an HTML or an Xforms 2.0 object as a response. If the response body header has Content-type: text/html, then it should expect an HTML form object. If it is application/xml, it should expect an xForms 2.0 model object. + + +#### Rendering the form +* BAPs should render their forms typically any time before confirming the order +* For item-specific inputs, BAPs should typically render the form when the user selects the item for ordering +* For order-specific inputs, BAPs should typically render the form +* BAPs should remove any script, style, and button tags when rendering the form inside their own UI + + +#### Submitting the form +* BAPs should submit the form data on the submission url specified in the form object via a HTTP/POST request. +* For HTML forms the submission url will be present in the action attribute of the form tag as highlighted in the example below +``` + …
+``` + +* For xForms 2.0 forms, the submission url will be present in the action attribute of the xform:submissions tag as highlighted in the example below + +``` + +``` + +* When submitting the form, the BAPs must _digitally sign_ the request body in the request header +* All form submissions must be digitally signed by the BAP + + +#### Handling form submission responses + +* Form responses are received in the **FormResponse** object +* The FormResponse object contains status, submission_id and an error array +* After receiving the form response, the BAP should execute the following algorithm + +``` + If FormResponse.status is true + save the submission_id + Else + throw an exception based on the data inside the error object +``` + +#### Post-Form Submission +After successful submission of the form, the BAP must ideally, send the submission_id received in the previous submission and send it in the corresponding item’s xinput.form.submission_id field, in the confirm API. + +### Recommendations for Network Facilitators +- Network Faciliators should publish a list of supported fields with their datatypes that can be used to create forms. This is to reduce form misuse through over-collection of data, and privacy protection. +- These fields can be the same as supported `Tags` list published by networks +- The IDs of the inputs are the codes + +## Examples +The following examples show how XInput can be used by BPPs to collect additional information from the user before confirming the order. + +### Example 1 : A logistics provider wants additional information on the nature of the package just before placing the order + +In this example, the Logistics BPP can create a XInput object containing a link the the following form + +``` +
+ + + + + + + + + + +
+``` + +Let us assume this form is hosted at - https://api.example-bpp.com/getForm?id=t8923y4ryu328473y4 + +The BPP can choose to send this form at an Item level or at an order level. To keep things simple, let us send this form at an order level. + +Let us assume, the Logistics BAP has already declared the intent (via search), received the catalogs (via on_search), selected a specific item ( via select), and has received a quote(via on_select). + + +#### Form identification + +When the BAP calls init, the Logistics BPP sends the following order object + +``` +{ + "context" : { + "action" : "on_init", + ...// other context details + }, + "message" : { + "order" : { + "items" : [ + { + "id" : "4aa3feca-96b5-47dd-a233-f7fd2525922c", + "descriptor" : { + "name" : "Hyperlocal delivery" + }, + "price" : { + "value" : "50", + "currency" : "INR" + } + } + ], + "xinput" : { + "form" : { + "url" : "https://api.example-bpp.com/getForm?id=t8923y4ryu328473y4", + "mime_type" : "text/html" + } + }, + "billing" : { + ...// billing details + }, + "fulfillment" : { + ...// fulfillment details + }, + ...// other order level details + } + } +} +``` + + + +#### Form Fetching from BPP + +When the Logistics BAP receives this object via on_init, it must pull the form data from the order.xinput.form.url field and render the form on the UI. It is recommended that the Logistics BAP keeps watching for the xinput field at the item and order level. + + +#### Form Rendering on the BAP + +Once pulled the BAP can render the form as-is on its UI, but it is not recommended, as doing so would result in a sub-optimal user experience. This is how the form will look if the BAP renders the form as-is using an HTML parser. + +![](https://user-images.githubusercontent.com/52468749/188610013-a97b6332-be73-4331-8edf-1cee807cf304.png) + + +However, the BAP application can apply any styling framework (like css) on the form and render it as per the style guide of the application. + +This form must be rendered just before firing the confirm API. This is typically just before checkout, when the BAP invokes the payment flow. + +The BAP must render the submit button for this form. This submit button functionality can be merged with the final checkout button or placed exclusively for this form as part of a two-step process. + +For example, in the case of a two step process, the flow might look like this + +* Step 1: + * 1.1 Render form with the first button + * 1.2 Capture form data and submit it to BPP + * 1.3 Save submission_id if submission is successful + +* Step 2: + * 2.1 Render the final confirmation screen with final checkout button + * 2.2 Fire confirm along with the submission_id reference in the order object + +In the case of a one step process, the BAP can collect all the data on a single form and then fire two consecutive API calls, one to submit the form, and the other to confirm the order. + +In any case, the form submission id must be transmitted along with the confirm API call. + +The BPP will receive the confirm call with the submission_id as reference. It will verify the submission against the submission_id and link that data along with the confirm API. + +Now the BPP has all the information required to confirm the order. It can either go ahead with the confirmation or reject the request if applicable. + +### Example 2: A health & wellness service provider wants additional information about the patient's symptoms before confirming a teleconsultation appointment. The provider and customer are on apps that are DHP-enabled (beckn protocol for health and wellness). + +[TODO] + +### Example 3: A recruitment agency wants additional information about the candidate before confirming a job application. The provider and customer are on apps that are DSEP-enabled (beckn protocol for education and skilling). + +``` +
+ + + + + +
+``` + +### Example 4: A flight booking system wants the passenger to declare his Covid vaccination status before confirming the booking. + +``` +
+ +  +  +  + + + + + +
+``` + +### Example 5: A mentor can seek additional information about a mentee before accepting the mentee's request for enrollment into the session(1-1 session as well as 1-many sessions). The provider and customer are on apps that are DSEP-enabled (Beckn protocol for education and skilling). + +In this case, the on_init BPP passes the form URL to BAP, which is rendered and filled by the mentee on BAP. The BAP then sends the acknowledgment ID received after the submission of the form in the confirm API call to BPP. + +An example of a form can be as below:- +``` +
+ + + + + + + + + +
+``` + +## Acknowledgements + +The authors would like to thank the following people for their support and contributions to this document. + +* Venkataramanan Mahadevan (Humbhionline) +* Pramod Varma (Beckn Foundation) +* Sujith Nair (Beckn Foundation) +* Akash Shah (Shikshalokam) +* Sankarshan Mukhopadyay (Dhiway Networks) \ No newline at end of file diff --git a/docs/beckn-core/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md b/docs/beckn-core/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md new file mode 100644 index 0000000..c39c4f7 --- /dev/null +++ b/docs/beckn-core/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md @@ -0,0 +1,171 @@ +# Rating and Reputation on Beckn Protocol + +*Draft 01* + +Author: +======= + +Ravi Prakash (ravi@becknfoundation.org) + +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 + + +
+ +
+ +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 |``| +|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/beckn-core/docs/BECKN-009-Tags-the-Edge-of-Beckn.md b/docs/beckn-core/docs/BECKN-009-Tags-the-Edge-of-Beckn.md new file mode 100644 index 0000000..a509ef2 --- /dev/null +++ b/docs/beckn-core/docs/BECKN-009-Tags-the-Edge-of-Beckn.md @@ -0,0 +1,286 @@ +# Document Details +## Supported Protocol Version + +TODO + + +## This version + +TODO + + +## Latest published version + +TODO + + +## Latest editor's draft + +TODO + +## Stress Test report + +TODO + +## Implementation report + +TODO + + +## Editors +Ravi Prakash (Beckn Foundation) + + +## Authors +Ravi Prakash (Beckn Foundation) + + +## Feedback + +Issues: TODO + +Discussions : TODO + +PRs : TODO + + +## Errata + +No Errata exists as of now + + +# Context + +Beckn protocol is a generic transaction protocol that allows any producer and consumer to interact and perform digitally signed transactions via a standard set of APIs. The schema of beckn has been abstracted to a level that allows any real-world entity to be represented as a generic object. + +Fundamentally, all transactions are the same according to beckn protocol. But practically, things are somewhat different. Sometimes, interacting entities (a.k.a Network Participants) need to send additional information related to various real-world entities to comply with policies and conventions governing the domain, network or the region of operation. Strictly speaking, this information may not be necessary to perform a transaction, but to allow an element of trust and convenience to be associated with a transaction. + +A retailer selling fast moving consumer goods might be legally obligated to send nutritional information, manufacturer details, food certification details, and other relevant information related to the products they are selling. On the other hand, consumers might want to narrow their search by sending specific information about the product they want. + +A car rental provider might want to send additional information on the make, model, variant, and other features of a car that might be useful to the customer to make a decision. It is also useful to the provider to provide faster and better search results if this additional information was sent by the customer while searching for the right car to rent. + +Similarly, a hospitality service provider may want to transmit additional information related to a room like AC/Non-AC, WiFi availability, Breakfast included, etc to allow the customer to choose the right room for themselves. + +As you can see from the above examples, the above information is not strictly necessary for an order to be created. But rather as metadata for display purposes, grouping, and filtering at the consumer’s end; and for enabling search optimization at the provider’s end. + + +# Problem + +How to transmit extended metadata related to a transaction in beckn protocol without breaking interoperability across implementations. + + +# Solution + +Beckn protocol defines three schemas, namely, **Tags, TagGroup **and** Tag**, that allow groups of key-value pairs to be transmitted between network participants as metadata. Let us look at them in more detail. + + +## The **Tags** schema + +The Tags schema is an array of TagGroup objects. This contains all the extended metadata about the container object. The schema is represented below + + +``` +components: + schemas: + Tags: + description: An array of tag groups. This object contains all the extended metadata about the container object. This can be added to any schema to carry extended metadata. + type: array + items: + $ref: "#/components/schemas/TagGroup" +``` + + +The Tags schema is explicitly referenced in the following schemas. + +* Category.tags +* Contact.tags +* Fulfillment.tags +* Intent.tags +* Intent.tags +* Item.tags +* Person.tags +* Provider.tags +* Order.tags + +However, this can be added to _any_ schema to carry extended metadata under the reserved keyname “tags”. + + +## The **TagGroup** Schema + +The TagGroup schema defines a key-value set that can be listed under a common heading. Examples of key-value sets are Nutritional Information, Technical Specifications, Manufacturer Information, etc. Each of these headings contain a set of key-value pairs that contain additional metadata specific to that heading. For example, the Tag Group named “Nutritional Content” might contain a key-value set containing _kcal = 100, carbohydrates = 11g, protein = 0.2g, fat = 0.11g,_ etc. Similarly, a Tag group named “Technical Specifications” for a mobile phone product may contain a key-value set containing _RAM = 12GB, Display Size = 6.5in, Weight = 128g, Processor = Snapdragon 855,_ and so on. + +The TagGroup schema is represented as shown below, + +``` + components: + schemas: + TagGroup: + description: A collection of tag objects with group level attributes + type: object + properties: + code: + description: The machine-readable name of the tag group + display: + description: Indicates the display properties of the Tag Group. If display is set to none, then the group will not be displayed. If it is set to block, it should be displayed as a separate block. + type: string + enum: + - none + - block + default: + - block + name: + description: A human-readable string describing the heading under which the tags are to be displayed. + type: string + list: + description: An array of Tag objects listed under this group + type: array + items: + $ref: "#/components/schemas/Tag" +``` + + +As you can see, the TagGroup is of type “object” contains four properties, + + +1. **code**: This contains a machine-readable name of the group. +2. **display**: This indicates whether a particular TagGroup is for display purposes. It has been modeled after the CSS “display” property. If it is equal to block, then the respective tag group has to be rendered as a block of key-value pairs. If it is none, then this block should not be rendered and is for internal consumption between platforms only. +3. **name**: This contains the name of the group like “Product Information”, “Technical Specifications”, etc +4. **list** : this is an array of Tag objects. (see next section) + +## The **Tag** Schema + +The tag schema contains a key-value pair containing the actual extended metadata to be communicated. + +The Tag schema is shown below. + + +``` + components: + schemas: + Tag: + description: A simple read-only key-value store which is used to contain extended metadata for search optimization, recommendations, and general information display purposes. Tags are read-only can cannot be changed once set. + type: object + properties: + code: + description: The machine-readable name of the tag. Beckn protocol will reserve certain keywords from being re-defined in any namespaces. + type: string + name: + description: The human-readable name of the tag. This set by the BPP and rendered as-is by the BAP + type: string + value: + description: The value of the tag + type: string +``` + + +As you can see, the Tag schema has the following properties + + + +1. **key** : The machine-readable name of the tag. This is generally a standard value that must be mutually agreed at a network level. +2. **name**: The display name of the key. This is non-standard and can be set by the creator. For example, there could be two providers who sell mobile phones. One of them +3. **value** : This contains the associated value of the key + +The **Tag** schema is referenced in the **TagGroup** schema in its property - “list”. + + +# Recommendations + +This section contains recommendations for entities using the Tag schema. + + +### For BPPs + +1. BPPs must group various key-value pairs under a common +2. BPPs must mandatorily send the tags that have been mandated by the network policy +3. The value of the “key” field is recommended to be in the snake-case format. +4. Non-standard tags must be prefixed by a namespace defined by the creator of the tags. To ensure namespace uniqueness, it is recommended that the namespace contain the FQDN of the creator of the tag. +5. BPPs are recommended index their catalog, carts and order books using these tags to allow better searchability + + +### For BAPs + +1. BAPs must render or not render the tags according to the “display” property of its parent tag group. +2. BAPs must render the tags that have been mandated by the network policy +3. BAPs can also use these tags to create recommendations or allow comparisons between items basis a specific property +4. It is recommended that BAPs have a “Report” feature that allows a user to report missing attributes. + + +### For Network Facilitators + +1. Certain Tag keys can be mandated to be sent by BPPs to enable compliance to statutory laws +2. Certain Tag names can also be standardized to enable BAPs to provide consistent customer experience. +3. Certain Tag groups can be mandated to be hidden or rendered by BAPs +4. Network facilitators should refer to standard supported tags maintained by domain-specific working groups when creating tag lists. +5. Tags not found in lists maintained by domain-specific working groups, should be namespaced with a unique network level identifier, usually the FQDN of the network facilitator. + + +### For Domain-specific Working Groups + +1. Domain-specific working groups should aggressively create and actively maintain an exhaustive list of standard keywords under various categories and subcategories that can be referenced by network facilitators + + +## Reserved Keywords + +Beckn protocol reserves some values for the “key” property of the Tag schema. These values are + +1. **seo** : This indicates the corresponding value is for search optimization. BAPs frequently send this as part of the Intent object +2. **url**: This indicates that that corresponding value is a clickable URL +3. **lang**: Contains a spoken language code + + +## Recommendations + +### For BPPs + +* In the Item.tags array, BPPs must send all the read-only metadata associated with an Item in the tags array. +* Any network-level category codes must be sent in the tags array +* BPPs can use network-level standard tags to index their order book +* BPPs can use network-level standard tags to index their product catalog database + + +### For BAPs + +* BAPs can send tags in the Intent object during search to allow BPPs to search through their catalog faster +* BAPs can use the Item.tags array to display additional information about the item like statutory fields. + + +### For Network Facilitators + +* Network Facilitators should publish a list of supported Tags with their namespace, key, and hidden properties that BAPs and BPPs can use + + +# Concrete Examples + +### Example 1: A retail domain-specific working group wants to publish a set of standard tags for various categories of product. +TODO + +### Example 2: A network facilitator with domain as examplenetwork.org wanted to mandate a retail-specific tag called country_of_mfg (Country of manufacture) to be sent as part of the Item. The network facilitator’s domain name is mynetwork.org. The following fields are mandated to be shown whenever packaged goods are being sold. +TODO + +It will first check with the tag list maintained by the local retail working group. If it finds the tag listed, it will simply publish that tag with a link to the source tag list. If it doesn’t find the desired tag listed, it will simply namespace and publish it as @examplenetwork/org/country_of_origin + +### Example 3: A packaged food product needs to be sent in response to a search request. The network policy states that product information displayed on a BAP app must be in compliance with the statutory laws of the region. + +* nutritional_info +* additives +* ingredients +* brand_owner +* brand_owner_address + +For example, if the FQDN of a network facilitator is mynetwork.org, and the key name is “fssai_license_number” then the namespace will be equal to “@mynetwork.org/fssai_license_number”. + + +### Example 4: Searching for teleconsulatation services by providing symptoms and language as hindi +TODO + + +# Acknowledgements + +The author would like to thank the following people for their support and contributions to this document. + + + +1. Venkataramanan Mahadevan +2. Pramod Varma +3. Sujith Nair \ No newline at end of file diff --git a/docs/beckn-core/docs/README.md b/docs/beckn-core/docs/README.md new file mode 100644 index 0000000..e05935f --- /dev/null +++ b/docs/beckn-core/docs/README.md @@ -0,0 +1,5 @@ +# Protocol Drafts + +These files contain specifications that have been selected from the proposals submitted to the beckn protocol specifications. The are currently under review by different working groups in the various categories supported beckn protocol governance. + +After sufficient deliberation, these drafts may be published as a Protocol Standard. \ No newline at end of file diff --git a/docs/beckn-core/docs/images/Async-Communication.png b/docs/beckn-core/docs/images/Async-Communication.png new file mode 100644 index 0000000..1cbd0e9 Binary files /dev/null and b/docs/beckn-core/docs/images/Async-Communication.png differ diff --git a/docs/beckn-core/docs/images/Payment-API-Sequence.png b/docs/beckn-core/docs/images/Payment-API-Sequence.png new file mode 100644 index 0000000..67987c0 Binary files /dev/null and b/docs/beckn-core/docs/images/Payment-API-Sequence.png differ diff --git a/docs/beckn-core/docs/images/Payment-Contract-Infrastructure.png b/docs/beckn-core/docs/images/Payment-Contract-Infrastructure.png new file mode 100644 index 0000000..70376bb Binary files /dev/null and b/docs/beckn-core/docs/images/Payment-Contract-Infrastructure.png differ diff --git a/docs/beckn-core/docs/images/Payment-Contract.png b/docs/beckn-core/docs/images/Payment-Contract.png new file mode 100644 index 0000000..2faa858 Binary files /dev/null and b/docs/beckn-core/docs/images/Payment-Contract.png differ diff --git a/docs/beckn-core/docs/images/Payment-Settlement-Flow-1.png b/docs/beckn-core/docs/images/Payment-Settlement-Flow-1.png new file mode 100644 index 0000000..abe5ff3 Binary files /dev/null and b/docs/beckn-core/docs/images/Payment-Settlement-Flow-1.png differ diff --git a/docs/beckn-core/docs/images/Payment-Settlement-Flow-2.png b/docs/beckn-core/docs/images/Payment-Settlement-Flow-2.png new file mode 100644 index 0000000..fb6ae8b Binary files /dev/null and b/docs/beckn-core/docs/images/Payment-Settlement-Flow-2.png differ diff --git a/docs/beckn-core/docs/images/Payment-Settlement-Flow-3.png b/docs/beckn-core/docs/images/Payment-Settlement-Flow-3.png new file mode 100644 index 0000000..9426345 Binary files /dev/null and b/docs/beckn-core/docs/images/Payment-Settlement-Flow-3.png differ diff --git a/docs/beckn-core/docs/images/Payment-Settlement-Flow-4.png b/docs/beckn-core/docs/images/Payment-Settlement-Flow-4.png new file mode 100644 index 0000000..44b95b6 Binary files /dev/null and b/docs/beckn-core/docs/images/Payment-Settlement-Flow-4.png differ diff --git a/docs/beckn-core/docs/images/Policy API.png b/docs/beckn-core/docs/images/Policy API.png new file mode 100644 index 0000000..4f0204e Binary files /dev/null and b/docs/beckn-core/docs/images/Policy API.png differ diff --git a/docs/beckn-core/docs/images/Policy Agreement Protocol.png b/docs/beckn-core/docs/images/Policy Agreement Protocol.png new file mode 100644 index 0000000..2ad22c2 Binary files /dev/null and b/docs/beckn-core/docs/images/Policy Agreement Protocol.png differ diff --git a/docs/beckn-core/docs/images/Policy Infrastructure Architecture.png b/docs/beckn-core/docs/images/Policy Infrastructure Architecture.png new file mode 100644 index 0000000..5dba2aa Binary files /dev/null and b/docs/beckn-core/docs/images/Policy Infrastructure Architecture.png differ diff --git a/docs/beckn-core/docs/images/Policy Workflow.png b/docs/beckn-core/docs/images/Policy Workflow.png new file mode 100644 index 0000000..aca536f Binary files /dev/null and b/docs/beckn-core/docs/images/Policy Workflow.png differ diff --git a/docs/beckn-core/docs/images/Policy-Agreement-Implementation-Architecture.png b/docs/beckn-core/docs/images/Policy-Agreement-Implementation-Architecture.png new file mode 100644 index 0000000..e3a3889 Binary files /dev/null and b/docs/beckn-core/docs/images/Policy-Agreement-Implementation-Architecture.png differ diff --git a/docs/beckn-core/docs/images/Policy-Agreement-and-Adoption-Protocol.png b/docs/beckn-core/docs/images/Policy-Agreement-and-Adoption-Protocol.png new file mode 100644 index 0000000..c1bdaba Binary files /dev/null and b/docs/beckn-core/docs/images/Policy-Agreement-and-Adoption-Protocol.png differ diff --git a/docs/beckn-core/docs/images/Policy-Workflow-New.png b/docs/beckn-core/docs/images/Policy-Workflow-New.png new file mode 100644 index 0000000..b0d8237 Binary files /dev/null and b/docs/beckn-core/docs/images/Policy-Workflow-New.png differ diff --git a/docs/beckn-core/docs/images/Search-Multicast-with-Reg.png b/docs/beckn-core/docs/images/Search-Multicast-with-Reg.png new file mode 100644 index 0000000..17e8bd9 Binary files /dev/null and b/docs/beckn-core/docs/images/Search-Multicast-with-Reg.png differ diff --git a/docs/beckn-core/docs/images/Search-Multicast.png b/docs/beckn-core/docs/images/Search-Multicast.png new file mode 100644 index 0000000..70ac434 Binary files /dev/null and b/docs/beckn-core/docs/images/Search-Multicast.png differ diff --git a/docs/beckn-core/docs/images/Status.png b/docs/beckn-core/docs/images/Status.png new file mode 100644 index 0000000..0ac0a99 Binary files /dev/null and b/docs/beckn-core/docs/images/Status.png differ diff --git a/docs/beckn-core/docs/images/rating handshake.png b/docs/beckn-core/docs/images/rating handshake.png new file mode 100644 index 0000000..374c88d Binary files /dev/null and b/docs/beckn-core/docs/images/rating handshake.png differ diff --git a/docs/beckn-core/docs/images/sample.png b/docs/beckn-core/docs/images/sample.png new file mode 100644 index 0000000..97b5266 Binary files /dev/null and b/docs/beckn-core/docs/images/sample.png differ diff --git a/docs/beckn-core/protocol-specifications.iml b/docs/beckn-core/protocol-specifications.iml new file mode 100644 index 0000000..8021953 --- /dev/null +++ b/docs/beckn-core/protocol-specifications.iml @@ -0,0 +1,9 @@ + + + + + + + + + \ No newline at end of file diff --git a/docs/beckn-core/schema/Ack.yaml b/docs/beckn-core/schema/Ack.yaml new file mode 100644 index 0000000..8b15308 --- /dev/null +++ b/docs/beckn-core/schema/Ack.yaml @@ -0,0 +1,15 @@ +description: Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack must be returned in the same session. Every API call to a BPP must be responded to with an Ack whether the BPP intends to respond with a callback or not. This has one property called `status` that indicates the status of the Acknowledgement. +type: object +additionalProperties: false +properties: + status: + type: string + description: The status of the acknowledgement. If the request passes the validation criteria of the BPP, then this is set to ACK. If a BPP responds with status = `ACK` to a request, it is required to respond with a callback. If the request fails the validation criteria, then this is set to NACK. Additionally, if a BPP does not intend to respond with a callback even after the request meets the validation criteria, it should set this value to `NACK`. + enum: + - ACK + - NACK + tags: + description: A list of tags containing any additional information sent along with the Acknowledgement. + type: array + items: + $ref: "./TagGroup.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/AddOn.yaml b/docs/beckn-core/schema/AddOn.yaml new file mode 100644 index 0000000..e767253 --- /dev/null +++ b/docs/beckn-core/schema/AddOn.yaml @@ -0,0 +1,13 @@ +description: Describes an additional item offered as a value-addition to a product or service. This does not exist independently in a catalog and is always associated with an item. +type: object +additionalProperties: false +properties: + id: + description: Provider-defined ID of the add-on + type: string + descriptor: + $ref: "./Descriptor.yaml" + price: + $ref: "./Price.yaml" + quantity: + $ref: "./ItemQuantity.yaml" diff --git a/docs/beckn-core/schema/Address.yaml b/docs/beckn-core/schema/Address.yaml new file mode 100644 index 0000000..5028d97 --- /dev/null +++ b/docs/beckn-core/schema/Address.yaml @@ -0,0 +1,2 @@ +description: Describes a postal address. +type: string \ No newline at end of file diff --git a/docs/beckn-core/schema/Agent.yaml b/docs/beckn-core/schema/Agent.yaml new file mode 100644 index 0000000..b145cfd --- /dev/null +++ b/docs/beckn-core/schema/Agent.yaml @@ -0,0 +1,12 @@ +description: Describes the direct performer, driver or executor that fulfills an order. It is usually a person. But in some rare cases, it could be a non-living entity like a drone, or a bot. Some examples of agents are Doctor in the healthcare sector, a driver in the mobility sector, or a delivery person in the logistics sector. This object can be set at any stage of the order lifecycle. This can be set at the discovery stage when the BPP wants to provide details on the agent fulfilling the order, like in healthcare, where the doctor's name appears during search. This object can also used to search for a particular person that the customer wants fulfilling an order. Sometimes, this object gets instantiated after the order is confirmed, like in the case of on-demand taxis, where the driver is assigned after the user confirms the ride. +type: object +additionalProperties: false +properties: + person: + $ref: "./Person.yaml" + contact: + $ref: "./Contact.yaml" + organization: + $ref: "./Organization.yaml" + rating: + $ref: "./Rating.yaml#/properties/value" diff --git a/docs/beckn-core/schema/Authorization.yaml b/docs/beckn-core/schema/Authorization.yaml new file mode 100644 index 0000000..5989bfb --- /dev/null +++ b/docs/beckn-core/schema/Authorization.yaml @@ -0,0 +1,21 @@ +description: Describes an authorization mechanism used to start or end the fulfillment of an order. For example, in the mobility sector, the driver may require a one-time password to initiate the ride. In the healthcare sector, a patient may need to provide a password to open a video conference link during a teleconsultation. +type: object +additionalProperties: false +properties: + type: + description: Type of authorization mechanism used. The allowed values for this field can be published as part of the network policy. + type: string + token: + description: Token used for authorization. This is typically generated at the BPP. The BAP can send this value to the user via any channel that it uses to authenticate the user like SMS, Email, Push notification, or in-app rendering. + type: string + valid_from: + description: Timestamp in RFC3339 format from which token is valid + type: string + format: date-time + valid_to: + description: Timestamp in RFC3339 format until which token is valid + type: string + format: date-time + status: + description: Status of the token + type: string diff --git a/docs/beckn-core/schema/Billing.yaml b/docs/beckn-core/schema/Billing.yaml new file mode 100644 index 0000000..c403082 --- /dev/null +++ b/docs/beckn-core/schema/Billing.yaml @@ -0,0 +1,37 @@ +description: Describes the billing details of an entity.
This has properties like name,organization,address,email,phone,time,tax_number, created_at,updated_at +type: object +additionalProperties: false +properties: + name: + description: Name of the billable entity + type: string + organization: + description: Details of the organization being billed. + allOf: + - $ref: "./Organization.yaml" + address: + description: The address of the billable entity + allOf: + - $ref: "./Address.yaml" + state: + description: The state where the billable entity resides. This is important for state-level tax calculation + allOf: + - $ref: "./State.yaml" + city: + description: The city where the billable entity resides. + allOf: + - $ref: "./City.yaml" + email: + description: Email address where the bill is sent to + type: string + format: email + phone: + description: Phone number of the billable entity + type: string + time: + description: Details regarding the billing period + allOf: + - $ref: "./Time.yaml" + tax_id: + description: ID of the billable entity as recognized by the taxation authority + type: string diff --git a/docs/beckn-core/schema/Cancellation.yaml b/docs/beckn-core/schema/Cancellation.yaml new file mode 100644 index 0000000..b443b46 --- /dev/null +++ b/docs/beckn-core/schema/Cancellation.yaml @@ -0,0 +1,22 @@ +description: Describes a cancellation event +type: object +additionalProperties: false +properties: + time: + description: Date-time when the order was cancelled by the buyer + type: string + format: date-time + cancelled_by: + type: string + enum: + - CONSUMER + - PROVIDER + reason: + description: The reason for cancellation + allOf: + - $ref: "./Option.yaml" + additional_description: + description: Any additional information regarding the nature of cancellation + allOf: + - $ref: "./Descriptor.yaml" + diff --git a/docs/beckn-core/schema/CancellationTerm.yaml b/docs/beckn-core/schema/CancellationTerm.yaml new file mode 100644 index 0000000..30eaf0b --- /dev/null +++ b/docs/beckn-core/schema/CancellationTerm.yaml @@ -0,0 +1,24 @@ +description: Describes the cancellation terms of an item or an order. This can be referenced at an item or order level. Item-level cancellation terms can override the terms at the order level. +type: object +additionalProperties: false +properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: "./FulfillmentState.yaml" + reason_required: + description: Indicates whether a reason is required to cancel the order + type: boolean + cancel_by: + description: Information related to the time of cancellation. + allOf: + - $ref: "./Time.yaml" + cancellation_fee: + $ref: "./Fee.yaml" + xinput: + $ref: "./XInput.yaml" + external_ref: + $ref: "./MediaFile.yaml" + + + \ No newline at end of file diff --git a/docs/beckn-core/schema/Catalog.yaml b/docs/beckn-core/schema/Catalog.yaml new file mode 100644 index 0000000..f7d453f --- /dev/null +++ b/docs/beckn-core/schema/Catalog.yaml @@ -0,0 +1,33 @@ +description: Describes the products or services offered by a BPP. This is typically sent as the response to a search intent from a BAP. The payment terms, offers and terms of fulfillment supported by the BPP can also be included here. The BPP can show hierarchical nature of products/services in its catalog using the parent_category_id in categories. The BPP can also send a ttl (time to live) in the context which is the duration for which a BAP can cache the catalog and use the cached catalog.
This has properties like bbp/descriptor,bbp/categories,bbp/fulfillments,bbp/payments,bbp/offers,bbp/providers and exp
This is used in the following situations.
  • This is typically used in the discovery stage when the BPP sends the details of the products and services it offers as response to a search intent from the BAP.
+type: object +additionalProperties: false +properties: + descriptor: + $ref: "./Descriptor.yaml" + fulfillments: + description: Fulfillment modes offered at the BPP level. This is used when a BPP itself offers fulfillments on behalf of the providers it has onboarded. + type: array + items: + $ref: "./Fulfillment.yaml" + payments: + description: Payment terms offered by the BPP for all transactions. This can be overriden at the provider level. + type: array + items: + $ref: "./Payment.yaml" + offers: + description: Offers at the BPP-level. This is common across all providers onboarded by the BPP. + type: array + items: + $ref: "./Offer.yaml" + providers: + type: array + items: + $ref: "./Provider.yaml" + exp: + description: Timestamp after which catalog will expire + type: string + format: date-time + ttl: + description: Duration in seconds after which this catalog will expire + type: string + diff --git a/docs/beckn-core/schema/Category.yaml b/docs/beckn-core/schema/Category.yaml new file mode 100644 index 0000000..b854b61 --- /dev/null +++ b/docs/beckn-core/schema/Category.yaml @@ -0,0 +1,20 @@ +description: A label under which a collection of items can be grouped. +type: object +additionalProperties: false +properties: + id: + description: ID of the category + type: string + parent_category_id: + $ref: "#/properties/id" + descriptor: + $ref: "./Descriptor.yaml" + time: + $ref: "./Time.yaml" + ttl: + description: Time to live for an instance of this schema + tags: + type: array + items: + $ref: "./TagGroup.yaml" + diff --git a/docs/beckn-core/schema/Circle.yaml b/docs/beckn-core/schema/Circle.yaml new file mode 100644 index 0000000..4df6ffa --- /dev/null +++ b/docs/beckn-core/schema/Circle.yaml @@ -0,0 +1,9 @@ +description: Describes a circular region of a specified radius centered at a specified GPS coordinate. +type: object +additionalProperties: false +properties: + gps: + $ref: "./Gps.yaml" + radius: + $ref: "./Scalar.yaml" + diff --git a/docs/beckn-core/schema/City.yaml b/docs/beckn-core/schema/City.yaml new file mode 100644 index 0000000..6fe87fd --- /dev/null +++ b/docs/beckn-core/schema/City.yaml @@ -0,0 +1,10 @@ +description: Describes a city +type: object +additionalProperties: false +properties: + name: + description: Name of the city + type: string + code: + description: City code + type: string \ No newline at end of file diff --git a/docs/beckn-core/schema/Contact.yaml b/docs/beckn-core/schema/Contact.yaml new file mode 100644 index 0000000..eabda2e --- /dev/null +++ b/docs/beckn-core/schema/Contact.yaml @@ -0,0 +1,13 @@ +description: Describes the contact information of an entity +type: object +additionalProperties: false +properties: + phone: + type: string + email: + type: string + jcard: + type: object + additionalProperties: false + description: A Jcard object as per draft-ietf-jcardcal-jcard-03 specification + diff --git a/docs/beckn-core/schema/Context.yaml b/docs/beckn-core/schema/Context.yaml new file mode 100644 index 0000000..be1d7d6 --- /dev/null +++ b/docs/beckn-core/schema/Context.yaml @@ -0,0 +1,54 @@ +description: Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the BAP that sets the transaction context based on the consumer's location and action on their UI. But sometimes, during unsolicited callbacks, the BPP also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the BAP and the BPP. The context object contains four types of fields.
  1. Demographic information about the transaction using fields like `domain`, `country`, and `region`.
  2. Addressing details like the sending and receiving platform's ID and API URL.
  3. Interoperability information like the protocol version that implemented by the sender and,
  4. Transaction details like the method being called at the receiver's endpoint, the transaction_id that represents an end-to-end user session at the BAP, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.
This object must be passed in every interaction between a BAP and a BPP. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions, +type: object +additionalProperties: false +properties: + domain: + description: Domain code that is relevant to this transaction context + allOf: + - $ref: "./Domain.yaml#/properties/code" + type: string + location: + description: The location where the transaction is intended to be fulfilled. + allOf: + - $ref: "./Location.yaml" + action: + description: The Beckn protocol method being called by the sender and executed at the receiver. + type: string + version: + type: string + description: Version of transaction protocol being used by the sender. + bap_id: + description: Subscriber ID of the BAP + allOf: + - $ref: "./Subscriber.yaml#/properties/subscriber_id" + bap_uri: + description: Subscriber URL of the BAP for accepting callbacks from BPPs. + allOf: + - $ref: "./Subscriber.yaml#/properties/url" + bpp_id: + description: Subscriber ID of the BPP + allOf: + - $ref: "./Subscriber.yaml#/properties/subscriber_id" + bpp_uri: + description: Subscriber URL of the BPP for accepting calls from BAPs. + allOf: + - $ref: "./Subscriber.yaml#/properties/url" + transaction_id: + description: This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The BPPs can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the BAP. + type: string + format: uuid + message_id: + description: This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, BAPs need a common value to match an incoming callback from a BPP to an earlier call. This value can also be used to ignore duplicate messages coming from the BPP. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, BPPs must generate a new message_id. + type: string + format: uuid + timestamp: + description: Time of request generation in RFC3339 format + type: string + format: date-time + key: + description: The encryption public key of the sender + type: string + ttl: + description: The duration in ISO8601 format after timestamp for which this message holds valid + type: string + diff --git a/docs/beckn-core/schema/Country.yaml b/docs/beckn-core/schema/Country.yaml new file mode 100644 index 0000000..78a2628 --- /dev/null +++ b/docs/beckn-core/schema/Country.yaml @@ -0,0 +1,10 @@ +description: Describes a country +type: object +additionalProperties: false +properties: + name: + type: string + description: Name of the country + code: + type: string + description: Country code as per ISO 3166-1 and ISO 3166-2 format diff --git a/docs/beckn-core/schema/Credential.yaml b/docs/beckn-core/schema/Credential.yaml new file mode 100644 index 0000000..0119984 --- /dev/null +++ b/docs/beckn-core/schema/Credential.yaml @@ -0,0 +1,14 @@ +description: Describes a credential of an entity - Person or Organization +type: object +additionalProperties: false +properties: + id: + type: string + type: + type: string + default: "VerifiableCredential" + url: + description: URL of the credential + type: string + format: uri + diff --git a/docs/beckn-core/schema/Customer.yaml b/docs/beckn-core/schema/Customer.yaml new file mode 100644 index 0000000..c17a02d --- /dev/null +++ b/docs/beckn-core/schema/Customer.yaml @@ -0,0 +1,8 @@ +description: Describes a customer buying/availing a product or a service +type: object +additionalProperties: false +properties: + person: + $ref: "./Person.yaml" + contact: + $ref: "./Contact.yaml" diff --git a/docs/beckn-core/schema/DecimalValue.yaml b/docs/beckn-core/schema/DecimalValue.yaml new file mode 100644 index 0000000..008d701 --- /dev/null +++ b/docs/beckn-core/schema/DecimalValue.yaml @@ -0,0 +1,4 @@ +description: Describes a numerical value in decimal form +type: string +pattern: "[+-]?([0-9]*[.])?[0-9]+" + diff --git a/docs/beckn-core/schema/Descriptor.yaml b/docs/beckn-core/schema/Descriptor.yaml new file mode 100644 index 0000000..7527e96 --- /dev/null +++ b/docs/beckn-core/schema/Descriptor.yaml @@ -0,0 +1,33 @@ +description: Physical description of something. +type: object +additionalProperties: false +properties: + name: + type: string + code: + type: string + short_desc: + type: string + long_desc: + type: string + additional_desc: + type: object + additionalProperties: false + properties: + url: + type: string + content_type: + type: string + enum: + - text/plain + - text/html + - application/json + media: + type: array + items: + $ref: "./MediaFile.yaml" + images: + type: array + items: + $ref: "./Image.yaml" + diff --git a/docs/beckn-core/schema/Document.yaml b/docs/beckn-core/schema/Document.yaml new file mode 100644 index 0000000..c57c859 --- /dev/null +++ b/docs/beckn-core/schema/Document.yaml @@ -0,0 +1,19 @@ +description: Documnents associated to the order +type: object +additionalProperties: false +properties: + descriptor: + $ref: "./Descriptor.yaml" + mime_type: + description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. + type: string + enum: + - text/html + - application/html + - application/xml + - application/pdf + url: + description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. + type: string + format: uri + \ No newline at end of file diff --git a/docs/beckn-core/schema/Domain.yaml b/docs/beckn-core/schema/Domain.yaml new file mode 100644 index 0000000..10bc9c3 --- /dev/null +++ b/docs/beckn-core/schema/Domain.yaml @@ -0,0 +1,14 @@ +description: Described the industry sector or sub-sector. The network policy should contain codes for all the industry sectors supported by the network. Domains can be created in varying levels of granularity. The granularity of a domain can be decided by the participants of the network. Too broad domains will result in irrelevant search broadcast calls to BPPs that don't have services supporting the domain. Too narrow domains will result in a large number of registry entries for each BPP. It is recommended that network facilitators actively collaborate with various working groups and network participants to carefully choose domain codes keeping in mind relevance, performance, and opportunity cost. It is recommended that networks choose broad domains like mobility, logistics, healthcare etc, and progressively granularize them as and when the number of network participants for each domain grows large. +type: object +additionalProperties: false +properties: + name: + description: Name of the domain + type: string + code: + description: Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network. + additional_info: + description: A url that contains addtional information about that domain. + allOf: + - $ref: "./MediaFile.yaml" + diff --git a/docs/beckn-core/schema/Duration.yaml b/docs/beckn-core/schema/Duration.yaml new file mode 100644 index 0000000..67e4686 --- /dev/null +++ b/docs/beckn-core/schema/Duration.yaml @@ -0,0 +1,3 @@ +description: Describes duration as per ISO8601 format +type: string + diff --git a/docs/beckn-core/schema/Error.yaml b/docs/beckn-core/schema/Error.yaml new file mode 100644 index 0000000..a15967d --- /dev/null +++ b/docs/beckn-core/schema/Error.yaml @@ -0,0 +1,13 @@ +description: Describes an error object that is returned by a BAP, BPP or BG as a response or callback to an action by another network participant. This object is sent when any request received by a network participant is unacceptable. This object can be sent either during Ack or with the callback. +type: object +additionalProperties: false +properties: + code: + type: string + description: Standard error code. For full list of error codes, refer to docs/protocol-drafts/BECKN-005-ERROR-CODES-DRAFT-01.md of this repo" + paths: + type: string + description: Path to json schema generating the error. Used only during json schema validation errors + message: + type: string + description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user. diff --git a/docs/beckn-core/schema/Fee.yaml b/docs/beckn-core/schema/Fee.yaml new file mode 100644 index 0000000..ed6bcfe --- /dev/null +++ b/docs/beckn-core/schema/Fee.yaml @@ -0,0 +1,13 @@ +description: A fee applied on a particular entity +type: object +additionalProperties: false +properties: + percentage: + description: Percentage of a value + allOf: + - $ref: "./DecimalValue.yaml" + amount: + description: A fixed value + allOf: + - $ref: "./Price.yaml" + diff --git a/docs/beckn-core/schema/Form.yaml b/docs/beckn-core/schema/Form.yaml new file mode 100644 index 0000000..d97a369 --- /dev/null +++ b/docs/beckn-core/schema/Form.yaml @@ -0,0 +1,27 @@ +description: Describes a form +type: object +additionalProperties: false +properties: + id: + description: The form identifier. + type: string + url: + description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form. + type: string + format: uri + data: + description: The form submission data + type: object + additionalProperties: + type: string + mime_type: + description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. + type: string + enum: + - text/html + - application/html + - application/xml + resubmit: + type: boolean + multiple_sumbissions: + type: boolean \ No newline at end of file diff --git a/docs/beckn-core/schema/FormResponse.yaml b/docs/beckn-core/schema/FormResponse.yaml new file mode 100644 index 0000000..95fafc2 --- /dev/null +++ b/docs/beckn-core/schema/FormResponse.yaml @@ -0,0 +1,16 @@ +description: Describes the response to a form submission +type: object +additionalProperties: false +properties: + status: + description: Contains the status of form submission. + type: string + signature: + type: string + submission_id: + type: string + #format: uuid + errors: + type: array + items: + $ref: "./Error.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/Fulfillment.yaml b/docs/beckn-core/schema/Fulfillment.yaml new file mode 100644 index 0000000..b3e4819 --- /dev/null +++ b/docs/beckn-core/schema/Fulfillment.yaml @@ -0,0 +1,49 @@ +description: Describes how a an order will be rendered/fulfilled to the end-customer +type: object +additionalProperties: false +properties: + id: + description: Unique reference ID to the fulfillment of an order + type: string + type: + description: A code that describes the mode of fulfillment. This is typically set when there are multiple ways an order can be fulfilled. For example, a retail order can be fulfilled either via store pickup or a home delivery. Similarly, a medical consultation can be provided either in-person or via tele-consultation. The network policy must publish standard fulfillment type codes for the different modes of fulfillment. + type: string + rateable: + description: Whether the fulfillment can be rated or not + type: boolean + rating: + description: The rating value of the fulfullment service. + allOf: + - $ref: "./Rating.yaml#/properties/value" + state: + description: The current state of fulfillment. The BPP must set this value whenever the state of the order fulfillment changes and fire an unsolicited `on_status` call. + allOf: + - $ref: "./FulfillmentState.yaml" + tracking: + type: boolean + description: Indicates whether the fulfillment allows tracking + default: false + customer: + description: The person that will ultimately receive the order + allOf: + - $ref: "./Customer.yaml" + agent: + description: The agent that is currently handling the fulfillment of the order + allOf: + - $ref: "./Agent.yaml" + contact: + $ref: "./Contact.yaml" + vehicle: + $ref: "./Vehicle.yaml" + stops: + description: The list of logical stops encountered during the fulfillment of an order. + type: array + items: + $ref: "./Stop.yaml" + path: + description: The physical path taken by the agent that can be rendered on a map. The allowed format of this property can be set by the network. + type: string + tags: + type: array + items: + $ref: "./TagGroup.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/FulfillmentState.yaml b/docs/beckn-core/schema/FulfillmentState.yaml new file mode 100644 index 0000000..8f8c401 --- /dev/null +++ b/docs/beckn-core/schema/FulfillmentState.yaml @@ -0,0 +1,13 @@ +description: Describes the state of fulfillment +type: object +additionalProperties: false +properties: + descriptor: + $ref: "./Descriptor.yaml" + updated_at: + type: string + format: date-time + updated_by: + type: string + description: ID of entity which changed the state + diff --git a/docs/beckn-core/schema/Gps.yaml b/docs/beckn-core/schema/Gps.yaml new file mode 100644 index 0000000..6e89b26 --- /dev/null +++ b/docs/beckn-core/schema/Gps.yaml @@ -0,0 +1,4 @@ +description: Describes a GPS coordinate +type: string +pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$' + diff --git a/docs/beckn-core/schema/Image.yaml b/docs/beckn-core/schema/Image.yaml new file mode 100644 index 0000000..bdf9cc0 --- /dev/null +++ b/docs/beckn-core/schema/Image.yaml @@ -0,0 +1,26 @@ +description: Describes an image +type: object +additionalProperties: false +properties: + url: + description: URL to the image. This can be a data url or an remote url + type: string + format: uri + size_type: + description: The size of the image. The network policy can define the default dimensions of each type + type: string + enum: + - xs + - sm + - md + - lg + - xl + - custom + width: + description: Width of the image in pixels + type: string + height: + description: Height of the image in pixels + type: string + + diff --git a/docs/beckn-core/schema/Intent.yaml b/docs/beckn-core/schema/Intent.yaml new file mode 100644 index 0000000..f9ee946 --- /dev/null +++ b/docs/beckn-core/schema/Intent.yaml @@ -0,0 +1,37 @@ +description: The intent to buy or avail a product or a service. The BAP can declare the intent of the consumer containing
  • What they want (A product, service, offer)
  • Who they want (A seller, service provider, agent etc)
  • Where they want it and where they want it from
  • When they want it (start and end time of fulfillment
  • How they want to pay for it

This has properties like descriptor,provider,fulfillment,payment,category,offer,item,tags
This is typically used by the BAP to send the purpose of the user's search to the BPP. This will be used by the BPP to find products or services it offers that may match the user's intent.
For example, in Mobility, the mobility consumer declares a mobility intent. In this case, the mobility consumer declares information that describes various aspects of their journey like,
  • Where would they like to begin their journey (intent.fulfillment.start.location)
  • Where would they like to end their journey (intent.fulfillment.end.location)
  • When would they like to begin their journey (intent.fulfillment.start.time)
  • When would they like to end their journey (intent.fulfillment.end.time)
  • Who is the transport service provider they would like to avail services from (intent.provider)
  • Who is traveling (This is not recommended in public networks) (intent.fulfillment.customer)
  • What kind of fare product would they like to purchase (intent.item)
  • What add-on services would they like to avail
  • What offers would they like to apply on their booking (intent.offer)
  • What category of services would they like to avail (intent.category)
  • What additional luggage are they carrying
  • How would they like to pay for their journey (intent.payment)

For example, in health domain, a consumer declares the intent for a lab booking the describes various aspects of their booking like,
  • Where would they like to get their scan/test done (intent.fulfillment.start.location)
  • When would they like to get their scan/test done (intent.fulfillment.start.time)
  • When would they like to get the results of their test/scan (intent.fulfillment.end.time)
  • Who is the service provider they would like to avail services from (intent.provider)
  • Who is getting the test/scan (intent.fulfillment.customer)
  • What kind of test/scan would they like to purchase (intent.item)
  • What category of services would they like to avail (intent.category)
  • How would they like to pay for their journey (intent.payment)
+type: object +additionalProperties: false +properties: + descriptor: + description: A raw description of the search intent. Free text search strings, raw audio, etc can be sent in this object. + allOf: + - $ref: "./Descriptor.yaml" + provider: + description: The provider from which the customer wants to place to the order from + allOf: + - $ref: "./Provider.yaml" + fulfillment: + description: Details on how the customer wants their order fulfilled + allOf: + - $ref: "./Fulfillment.yaml" + payment: + description: Details on how the customer wants to pay for the order + allOf: + - $ref: "./Payment.yaml" + category: + description: Details on the item category + allOf: + - $ref: "./Category.yaml" + offer: + description: details on the offer the customer wants to avail + allOf: + - $ref: "./Offer.yaml" + item: + description: Details of the item that the consumer wants to order + allOf: + - $ref: "./Item.yaml" + tags: + type: array + items: + $ref: "./TagGroup.yaml" + diff --git a/docs/beckn-core/schema/Item.yaml b/docs/beckn-core/schema/Item.yaml new file mode 100644 index 0000000..a3ac256 --- /dev/null +++ b/docs/beckn-core/schema/Item.yaml @@ -0,0 +1,111 @@ +description: Describes a product or a service offered to the end consumer by the provider. In the mobility sector, it can represent a fare product like one way journey. In the logistics sector, it can represent the delivery service offering. In the retail domain it can represent a product like a grocery item. +type: object +additionalProperties: false +properties: + id: + description: ID of the item. + type: string + parent_item_id: + description: ID of the item, this item is a variant of + allOf: + - $ref: "./Item.yaml#/properties/id" + parent_item_quantity: + description: The number of units of the parent item this item is a multiple of + allOf: + - $ref: "./ItemQuantity.yaml" + descriptor: + description: Physical description of the item + allOf: + - $ref: "./Descriptor.yaml" + creator: + description: The creator of this item + allOf: + - $ref: "./Organization.yaml" + price: + description: The price of this item, if it has intrinsic value + allOf: + - $ref: "./Price.yaml" + quantity: + description: The selling quantity of the item + allOf: + - $ref: "./ItemQuantity.yaml" + category_ids: + description: Categories this item can be listed under + type: array + items: + allOf: + - $ref: "./Category.yaml#/properties/id" + fulfillment_ids: + description: Modes through which this item can be fulfilled + type: array + items: + allOf: + - $ref: "./Fulfillment.yaml#/properties/id" + location_ids: + description: Provider Locations this item is available in + type: array + items: + allOf: + - $ref: "./Location.yaml#/properties/id" + payment_ids: + description: Payment modalities through which this item can be ordered + type: array + items: + allOf: + - $ref: "./Payment.yaml#/properties/id" + add_ons: + type: array + items: + $ref: "./AddOn.yaml" + cancellation_terms: + description: Cancellation terms of this item + type: array + items: + $ref: "./CancellationTerm.yaml" + refund_terms: + description: Refund terms of this item + type: array + items: + $ref: "./RefundTerm.yaml" + replacement_terms: + description: Terms that are applicable be met when this item is replaced + type: array + items: + $ref: "./ReplacementTerm.yaml" + return_terms: + description: Terms that are applicable when this item is returned + type: array + items: + $ref: "./ReturnTerm.yaml" + xinput: + description: Additional input required from the customer to purchase / avail this item + allOf: + - $ref: "./XInput.yaml" + time: + description: Temporal attributes of this item. This property is used when the item exists on the catalog only for a limited period of time. + allOf: + - $ref: "./Time.yaml" + rateable: + description: Whether this item can be rated + type: boolean + rating: + description: The rating of the item + allOf: + - $ref: "./Rating.yaml#/properties/value" + matched: + description: Whether this item is an exact match of the request + type: boolean + related: + description: Whether this item is a related item to the exactly matched item + type: boolean + recommended: + description: Whether this item is a recommended item to a response + type: boolean + ttl: + description: Time to live in seconds for an instance of this schema + type: string + tags: + type: array + items: + $ref: "./TagGroup.yaml" + diff --git a/docs/beckn-core/schema/ItemQuantity.yaml b/docs/beckn-core/schema/ItemQuantity.yaml new file mode 100644 index 0000000..66d3363 --- /dev/null +++ b/docs/beckn-core/schema/ItemQuantity.yaml @@ -0,0 +1,66 @@ +description: Describes the count or amount of an item +type: object +additionalProperties: false +properties: + allocated: + description: This represents the exact quantity allocated for purchase of the item. + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: "./Scalar.yaml" + available: + description: This represents the exact quantity available for purchase of the item. The buyer can only purchase multiples of this + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: "./Scalar.yaml" + maximum: + description: This represents the maximum quantity allowed for purchase of the item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 1 + measure: + $ref: "./Scalar.yaml" + minimum: + description: This represents the minimum quantity allowed for purchase of the item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: "./Scalar.yaml" + selected: + description: This represents the quantity selected for purchase of the item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 0 + measure: + $ref: "./Scalar.yaml" + unitized: + description: This represents the quantity available in a single unit of the item + type: object + additionalProperties: false + properties: + count: + type: integer + minimum: 1 + maximum: 1 + measure: + $ref: "./Scalar.yaml" + diff --git a/docs/beckn-core/schema/Language.yaml b/docs/beckn-core/schema/Language.yaml new file mode 100644 index 0000000..08fedd8 --- /dev/null +++ b/docs/beckn-core/schema/Language.yaml @@ -0,0 +1,9 @@ +description: Describes a language known to the person. +type: object +additionalProperties: false +properties: + code: + type: string + name: + type: string + diff --git a/docs/beckn-core/schema/Location.yaml b/docs/beckn-core/schema/Location.yaml new file mode 100644 index 0000000..766c066 --- /dev/null +++ b/docs/beckn-core/schema/Location.yaml @@ -0,0 +1,53 @@ +description: The physical location of something +type: object +additionalProperties: false +properties: + id: + type: string + descriptor: + $ref: "./Descriptor.yaml" + map_url: + description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy. + type: string + format: uri + gps: + description: The GPS co-ordinates of this location. + allOf: + - $ref: "./Gps.yaml" + updated_at: + type: string + format: date-time + address: + description: The address of this location. + allOf: + - $ref: "./Address.yaml" + city: + description: The city this location is, or is located within + allOf: + - $ref: "./City.yaml" + district: + description: The state this location is, or is located within + type: string + state: + description: The state this location is, or is located within + allOf: + - $ref: "./State.yaml" + country: + description: The country this location is, or is located within + allOf: + - $ref: "./Country.yaml" + area_code: + type: string + circle: + $ref: "./Circle.yaml" + polygon: + description: The boundary polygon of this location + type: string + 3dspace: + description: The three dimensional region describing this location + type: string + rating: + description: The rating of this location + allOf: + - $ref: "./Rating.yaml#/properties/value" + \ No newline at end of file diff --git a/docs/beckn-core/schema/MediaFile.yaml b/docs/beckn-core/schema/MediaFile.yaml new file mode 100644 index 0000000..22e5b99 --- /dev/null +++ b/docs/beckn-core/schema/MediaFile.yaml @@ -0,0 +1,18 @@ +description: This object contains a url to a media file. +type: object +additionalProperties: false +properties: + mimetype: + description: indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF's RFC 6838 + type: string + url: + description: The URL of the file + type: string + format: uri + signature: + description: The digital signature of the file signed by the sender + type: string + dsa: + description: The signing algorithm used by the sender + type: string + diff --git a/docs/beckn-core/schema/Offer.yaml b/docs/beckn-core/schema/Offer.yaml new file mode 100644 index 0000000..6fc7ccf --- /dev/null +++ b/docs/beckn-core/schema/Offer.yaml @@ -0,0 +1,26 @@ +description: An offer associated with a catalog. This is typically used to promote a particular product and enable more purchases. +type: object +additionalProperties: false +properties: + id: + type: string + descriptor: + $ref: "./Descriptor.yaml" + location_ids: + type: array + items: + $ref: "./Location.yaml#/properties/id" + category_ids: + type: array + items: + $ref: "./Category.yaml#/properties/id" + item_ids: + type: array + items: + $ref: "./Item.yaml#/properties/id" + time: + $ref: "./Time.yaml" + tags: + type: array + items: + $ref: "./TagGroup.yaml" diff --git a/docs/beckn-core/schema/Option.yaml b/docs/beckn-core/schema/Option.yaml new file mode 100644 index 0000000..421a482 --- /dev/null +++ b/docs/beckn-core/schema/Option.yaml @@ -0,0 +1,9 @@ +description: Describes a selectable option +type: object +additionalProperties: false +properties: + id: + type: string + descriptor: + $ref: "./Descriptor.yaml" + diff --git a/docs/beckn-core/schema/Order.yaml b/docs/beckn-core/schema/Order.yaml new file mode 100644 index 0000000..d58a00f --- /dev/null +++ b/docs/beckn-core/schema/Order.yaml @@ -0,0 +1,108 @@ +description: Describes a legal purchase order. It contains the complete details of the legal contract created between the buyer and the seller. +type: object +additionalProperties: false +properties: + id: + type: string + description: Human-readable ID of the order. This is generated at the BPP layer. The BPP can either generate order id within its system or forward the order ID created at the provider level. + ref_order_ids: + description: A list of order IDs to link this order to previous orders. + type: array + items: + type: string + description: ID of a previous order + status: + description: Status of the order. Allowed values can be defined by the network policy + type: string + # enum: + # - ACTIVE + # - COMPLETE + # - CANCELLED + type: + description: This is used to indicate the type of order being created to BPPs. Sometimes orders can be linked to previous orders, like a replacement order in a retail domain. A follow-up consultation in healthcare domain. A single order part of a subscription order. The list of order types can be standardized at the network level. + type: string + default: DEFAULT + enum: + - DRAFT + - DEFAULT + provider: + description: Details of the provider whose catalog items have been selected. + allOf: + - $ref: "./Provider.yaml" + items: + description: The items purchased / availed in this order + type: array + items: + $ref: "./Item.yaml" + add_ons: + description: The add-ons purchased / availed in this order + type: array + items: + $ref: "./AddOn.yaml" + offers: + description: The offers applied in this order + type: array + items: + $ref: "./Offer.yaml" + billing: + description: The billing details of this order + allOf: + - $ref: "./Billing.yaml" + fulfillments: + description: The fulfillments involved in completing this order + type: array + items: + $ref: "./Fulfillment.yaml" + cancellation: + description: The cancellation details of this order + allOf: + - $ref: "./Cancellation.yaml" + cancellation_terms: + description: Cancellation terms of this item + type: array + items: + $ref: "./CancellationTerm.yaml" + documents: + type: array + items: + $ref: "./Document.yaml" + refund_terms: + description: Refund terms of this item + type: array + items: + $ref: "./RefundTerm.yaml" + replacement_terms: + description: Replacement terms of this item + type: array + items: + $ref: "./ReplacementTerm.yaml" + return_terms: + description: Return terms of this item + type: array + items: + $ref: "./ReturnTerm.yaml" + quote: + description: The mutually agreed upon quotation for this order. + allOf: + - $ref: "./Quotation.yaml" + payments: + description: The terms of settlement for this order + type: array + items: + $ref: "./Payment.yaml" + created_at: + description: The date-time of creation of this order + type: string + format: date-time + updated_at: + description: The date-time of updated of this order + type: string + format: date-time + xinput: + description: Additional input required from the customer to confirm this order + allOf: + - $ref: "./XInput.yaml" + tags: + type: array + items: + $ref: "./TagGroup.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/Organization.yaml b/docs/beckn-core/schema/Organization.yaml new file mode 100644 index 0000000..0b29cee --- /dev/null +++ b/docs/beckn-core/schema/Organization.yaml @@ -0,0 +1,20 @@ +description: An organization. Usually a recognized business entity. +type: object +additionalProperties: false +properties: + descriptor: + $ref: "./Descriptor.yaml" + address: + description: The postal address of the organization + allOf: + - $ref: "./Address.yaml" + state: + description: The state where the organization's address is registered + allOf: + - $ref: "./State.yaml" + city: + description: The city where the the organization's address is registered + allOf: + - $ref: "./City.yaml" + contact: + $ref: "./Contact.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/Payment.yaml b/docs/beckn-core/schema/Payment.yaml new file mode 100644 index 0000000..9257e32 --- /dev/null +++ b/docs/beckn-core/schema/Payment.yaml @@ -0,0 +1,60 @@ +description: Describes the terms of settlement between the BAP and the BPP for a single transaction. When instantiated, this object contains
  1. the amount that has to be settled,
  2. The payment destination destination details
  3. When the settlement should happen, and
  4. A transaction reference ID
. During a transaction, the BPP reserves the right to decide the terms of payment. However, the BAP can send its terms to the BPP first. If the BPP does not agree to those terms, it must overwrite the terms and return them to the BAP. If overridden, the BAP must either agree to the terms sent by the BPP in order to preserve the provider's autonomy, or abort the transaction. In case of such disagreements, the BAP and the BPP can perform offline negotiations on the payment terms. Once an agreement is reached, the BAP and BPP can resume transactions. +type: object +additionalProperties: false +properties: + id: + description: ID of the payment term that can be referred at an item or an order level in a catalog + type: string + collected_by: + description: This field indicates who is the collector of payment. The BAP can set this value to 'bap' if it wants to collect the payment first and settle it to the BPP. If the BPP agrees to those terms, the BPP should not send the payment url. Alternatively, the BPP can set this field with the value 'bpp' if it wants the payment to be made directly. + type: string + url: + type: string + description: A payment url to be called by the BAP. If empty, then the payment is to be done offline. The details of payment should be present in the params object. If tl_method = http/get, then the payment details will be sent as url params. Two url param values, ```$transaction_id``` and ```$amount``` are mandatory. + format: uri + tl_method: + type: string + params: + type: object + additionalProperties: false + properties: + transaction_id: + type: string + description: The reference transaction ID associated with a payment activity + amount: + type: string + currency: + type: string + bank_code: + type: string + bank_account_number: + type: string + virtual_payment_address: + type: string + source_bank_code: + type: string + source_bank_account_number: + type: string + source_virtual_payment_address: + type: string + type: + type: string + enum: + - PRE-ORDER + - PRE-FULFILLMENT + - ON-FULFILLMENT + - POST-FULFILLMENT + - ON-ORDER + - PART-PAYMENT + status: + type: string + enum: + - PAID + - NOT-PAID + time: + $ref: "./Time.yaml" + tags: + type: array + items: + $ref: "./TagGroup.yaml" + diff --git a/docs/beckn-core/schema/Person.yaml b/docs/beckn-core/schema/Person.yaml new file mode 100644 index 0000000..b177094 --- /dev/null +++ b/docs/beckn-core/schema/Person.yaml @@ -0,0 +1,44 @@ +description: Describes a person as any individual +type: object +additionalProperties: false +properties: + id: + type: string + description: Describes the identity of the person + url: + description: Profile url of the person + type: string + format: uri + name: + description: the name of the person + type: string + image: + $ref: "./Image.yaml" + age: + description: Age of the person + allOf: + - $ref: "./Duration.yaml" + dob: + description: Date of birth of the person + type: string + format: date + gender: + type: string + description: Gender of something, typically a Person, but possibly also fictional characters, animals, etc. While Male and Female may be used, text strings are also acceptable for people who do not identify as a binary gender.Allowed values for this field can be published in the network policy + creds: + type: array + items: + $ref: "./Credential.yaml" + languages: + type: array + items: + $ref: "./Language.yaml" + skills: + type: array + items: + $ref: "./Skill.yaml" + tags: + type: array + items: + $ref: "./TagGroup.yaml" + diff --git a/docs/beckn-core/schema/Price.yaml b/docs/beckn-core/schema/Price.yaml new file mode 100644 index 0000000..58bbda3 --- /dev/null +++ b/docs/beckn-core/schema/Price.yaml @@ -0,0 +1,21 @@ +description: Describes the price of a product or service +type: object +additionalProperties: false +properties: + currency: + type: string + value: + $ref: "./DecimalValue.yaml" + estimated_value: + $ref: "./DecimalValue.yaml" + computed_value: + $ref: "./DecimalValue.yaml" + listed_value: + $ref: "./DecimalValue.yaml" + offered_value: + $ref: "./DecimalValue.yaml" + minimum_value: + $ref: "./DecimalValue.yaml" + maximum_value: + $ref: "./DecimalValue.yaml" + diff --git a/docs/beckn-core/schema/Provider.yaml b/docs/beckn-core/schema/Provider.yaml new file mode 100644 index 0000000..494d3f3 --- /dev/null +++ b/docs/beckn-core/schema/Provider.yaml @@ -0,0 +1,54 @@ +description: Describes the catalog of a business. +type: object +additionalProperties: false +properties: + id: + type: string + description: Id of the provider + descriptor: + $ref: "./Descriptor.yaml" + category_id: + type: string + description: Category Id of the provider at the BPP-level catalog + rating: + $ref: "./Rating.yaml#/properties/value" + time: + $ref: "./Time.yaml" + categories: + type: array + items: + $ref: "./Category.yaml" + fulfillments: + type: array + items: + $ref: "./Fulfillment.yaml" + payments: + type: array + items: + $ref: "./Payment.yaml" + locations: + type: array + items: + $ref: "./Location.yaml" + offers: + type: array + items: + $ref: "./Offer.yaml" + items: + type: array + items: + $ref: "./Item.yaml" + exp: + type: string + description: Time after which catalog has to be refreshed + format: date-time + rateable: + description: Whether this provider can be rated or not + type: boolean + ttl: + description: The time-to-live in seconds, for this object. This can be overriden at deeper levels. A value of -1 indicates that this object is not cacheable. + type: string + tags: + type: array + items: + $ref: "./TagGroup.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/Quotation.yaml b/docs/beckn-core/schema/Quotation.yaml new file mode 100644 index 0000000..5799a2e --- /dev/null +++ b/docs/beckn-core/schema/Quotation.yaml @@ -0,0 +1,28 @@ +description: Describes a quote. It is the estimated price of products or services from the BPP.
This has properties like price, breakup, ttl +type: object +additionalProperties: false +properties: + id: + description: ID of the quote. + type: string + format: uuid + price: + description: The total quoted price + allOf: + - $ref: "./Price.yaml" + breakup: + description: the breakup of the total quoted price + type: array + items: + type: object + additionalProperties: false + properties: + item: + $ref: "./Item.yaml" + title: + type: string + price: + $ref: "./Price.yaml" + ttl: + $ref: "./Duration.yaml" + diff --git a/docs/beckn-core/schema/README.md b/docs/beckn-core/schema/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/beckn-core/schema/Rating.yaml b/docs/beckn-core/schema/Rating.yaml new file mode 100644 index 0000000..8f02710 --- /dev/null +++ b/docs/beckn-core/schema/Rating.yaml @@ -0,0 +1,21 @@ +description: Describes the rating of an entity +type: object +additionalProperties: false +properties: + rating_category: + description: Category of the entity being rated + type: string + enum: + - Item + - Order + - Fulfillment + - Provider + - Agent + - Support + id: + description: Id of the object being rated + type: string + value: + description: Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||. + type: string + diff --git a/docs/beckn-core/schema/RefundTerm.yaml b/docs/beckn-core/schema/RefundTerm.yaml new file mode 100644 index 0000000..8315297 --- /dev/null +++ b/docs/beckn-core/schema/RefundTerm.yaml @@ -0,0 +1,17 @@ +description: Refund term of an item or an order +type: object +additionalProperties: false +properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: "./State.yaml" + refund_eligible: + description: Indicates if cancellation will result in a refund + type: boolean + refund_within: + description: Time within which refund will be processed after successful cancellation. + allOf: + - $ref: "./Time.yaml" + refund_amount: + $ref: "./Price.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/Region.yaml b/docs/beckn-core/schema/Region.yaml new file mode 100644 index 0000000..51751c6 --- /dev/null +++ b/docs/beckn-core/schema/Region.yaml @@ -0,0 +1,26 @@ +description: Describes an arbitrary region of space. The network policy should contain a published list of supported regions by the network. +type: object +additionalProperties: false +properties: + dimensions: + description: The number of dimensions that are used to describe any point inside that region. The most common dimensionality of a region is 2, that represents an area on a map. There are regions on the map that can be approximated to one-dimensional regions like roads, railway lines, or shipping lines. 3 dimensional regions are rarer, but are gaining popularity as flying drones are being adopted for various fulfillment services. + type: string + enum: + - "1" + - "2" + - "3" + type: + description: The type of region. This is used to specify the granularity of the region represented by this object. Various examples of two-dimensional region types are city, country, state, district, and so on. The network policy should contain a list of all possible region types supported by the network. + type: string + name: + type: string + description: Name of the region as specified on the map where that region exists. + code: + type: string + description: A standard code representing the region. This should be interpreted in the same way by all network participants. + boundary: + type: string + description: A string representing the boundary of the region. One-dimensional regions are represented by polylines. Two-dimensional regions are represented by polygons, and three-dimensional regions can represented by polyhedra. + map_url: + type: string + description: The url to the map of the region. This can be a globally recognized map or the one specified by the network policy. \ No newline at end of file diff --git a/docs/beckn-core/schema/ReplacementTerm.yaml b/docs/beckn-core/schema/ReplacementTerm.yaml new file mode 100644 index 0000000..2b725bb --- /dev/null +++ b/docs/beckn-core/schema/ReplacementTerm.yaml @@ -0,0 +1,15 @@ +description: The replacement policy of an item or an order +type: object +additionalProperties: false +properties: + fulfillment_state: + description: The state of fulfillment during which this term is applicable. + allOf: + - $ref: "./State.yaml" + replace_within: + description: Applicable only for buyer managed returns where the buyer has to replace the item before a certain date-time, failing which they will not be eligible for replacement + allOf: + - $ref: "./Time.yaml" + external_ref: + $ref: "./MediaFile.yaml" + diff --git a/docs/beckn-core/schema/ReturnTerm.yaml b/docs/beckn-core/schema/ReturnTerm.yaml new file mode 100644 index 0000000..9450c6a --- /dev/null +++ b/docs/beckn-core/schema/ReturnTerm.yaml @@ -0,0 +1,25 @@ +description: Describes the return policy of an item or an order +type: object +additionalProperties: false +properties: + fulfillment_state: + description: The state of fulfillment during which this term IETF''s applicable. + allOf: + - $ref: "./State.yaml" + return_eligible: + description: Indicates whether the item is eligible for return + type: boolean + return_time: + description: Applicable only for buyer managed returns where the buyer has to return the item to the origin before a certain date-time, failing which they will not be eligible for refund. + allOf: + - $ref: "./Time.yaml" + return_location: + description: The location where the item or order must / will be returned to + allOf: + - $ref: "./Location.yaml" + fulfillment_managed_by: + description: The entity that will perform the return + type: string + enum: + - CONSUMER + - PROVIDER \ No newline at end of file diff --git a/docs/beckn-core/schema/Scalar.yaml b/docs/beckn-core/schema/Scalar.yaml new file mode 100644 index 0000000..33edb46 --- /dev/null +++ b/docs/beckn-core/schema/Scalar.yaml @@ -0,0 +1,25 @@ +description: Describes a scalar +type: object +additionalProperties: false +properties: + type: + type: string + enum: + - CONSTANT + - VARIABLE + value: + $ref: "./DecimalValue.yaml" + estimated_value: + $ref: "./DecimalValue.yaml" + computed_value: + $ref: "./DecimalValue.yaml" + range: + type: object + additionalProperties: false + properties: + min: + $ref: "./DecimalValue.yaml" + max: + $ref: "./DecimalValue.yaml" + unit: + type: string diff --git a/docs/beckn-core/schema/Schedule.yaml b/docs/beckn-core/schema/Schedule.yaml new file mode 100644 index 0000000..ed6d1c1 --- /dev/null +++ b/docs/beckn-core/schema/Schedule.yaml @@ -0,0 +1,17 @@ +description: Describes schedule as a repeating time period used to describe a regularly recurring event. At a minimum a schedule will specify frequency which describes the interval between occurrences of the event. Additional information can be provided to specify the schedule more precisely. This includes identifying the timestamps(s) of when the event will take place. Schedules may also have holidays to exclude a specific day from the schedule.
This has properties like frequency, holidays, times +type: object +additionalProperties: false +properties: + frequency: + $ref: "./Duration.yaml" + holidays: + type: array + items: + type: string + format: date-time + times: + type: array + items: + type: string + format: date-time + diff --git a/docs/beckn-core/schema/Settlement.yaml b/docs/beckn-core/schema/Settlement.yaml new file mode 100644 index 0000000..7d76406 --- /dev/null +++ b/docs/beckn-core/schema/Settlement.yaml @@ -0,0 +1,33 @@ +description: Describes a settlement. +type: object +additionalProperties: false +properties: + settlement_counterparty: + type: string + settlement_phase: + type: string + settlement_type: + type: string + upi_address: + type: string + settlement_bank_account_no: + type: string + settlement_ifsc_code: + type: string + beneficiary_name: + type: string + bank_name: + type: string + branch_name: + type: string + settlement_reference: + type: string + settlement_status: + type: string + settlement_timestamp: + type: string + + + + + diff --git a/docs/beckn-core/schema/Skill.yaml b/docs/beckn-core/schema/Skill.yaml new file mode 100644 index 0000000..060abca --- /dev/null +++ b/docs/beckn-core/schema/Skill.yaml @@ -0,0 +1,9 @@ +description: Describes a skill of the person. +type: object +additionalProperties: false +properties: + code: + type: string + name: + type: string + diff --git a/docs/beckn-core/schema/State.yaml b/docs/beckn-core/schema/State.yaml new file mode 100644 index 0000000..51b3374 --- /dev/null +++ b/docs/beckn-core/schema/State.yaml @@ -0,0 +1,11 @@ +description: A bounded geopolitical region of governance inside a country. +type: object +additionalProperties: false +properties: + name: + type: string + description: Name of the state + code: + type: string + description: State code as per country or international standards + diff --git a/docs/beckn-core/schema/Stop.yaml b/docs/beckn-core/schema/Stop.yaml new file mode 100644 index 0000000..c486148 --- /dev/null +++ b/docs/beckn-core/schema/Stop.yaml @@ -0,0 +1,33 @@ +description: A logical point in space and time during the fulfillment of an order. +type: object +additionalProperties: false +properties: + id: + type: string + parent_stop_id: + type: string + location: + description: Location of the stop + allOf: + - $ref: "./Location.yaml" + type: + description: The type of stop. Allowed values of this property can be defined by the network policy. + type: string + time: + description: Timings applicable at the stop. + allOf: + - $ref: "./Time.yaml" + instructions: + description: Instructions that need to be followed at the stop + allOf: + - $ref: "./Descriptor.yaml" + contact: + description: Contact details of the stop + allOf: + - $ref: "./Contact.yaml" + person: + description: The details of the person present at the stop + allOf: + - $ref: "./Person.yaml" + authorization: + $ref: "./Authorization.yaml" diff --git a/docs/beckn-core/schema/Subscriber.yaml b/docs/beckn-core/schema/Subscriber.yaml new file mode 100644 index 0000000..84d86c9 --- /dev/null +++ b/docs/beckn-core/schema/Subscriber.yaml @@ -0,0 +1,26 @@ +description: A unique operational configuration of a trusted platform on a network. +type: object +additionalProperties: false +properties: + subscriber_id: + description: A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform. + type: string + url: + description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``. + type: string + format: uri + type: + description: The role of subscriber on the network + type: string + enum: + - BAP + - BPP + - BG + domain: + description: Operating industry domain that this subscriber offers its products or services in. A single subscriber can operate in multiple domains. Each operating domain must have a unique subscriber object entry in the req + allOf: + - $ref: "./Domain.yaml#/properties/code" + location: + description: The region of operation of this subscriber + allOf: + - $ref: "./Location.yaml" diff --git a/docs/beckn-core/schema/Subscription.yaml b/docs/beckn-core/schema/Subscription.yaml new file mode 100644 index 0000000..53da959 --- /dev/null +++ b/docs/beckn-core/schema/Subscription.yaml @@ -0,0 +1,38 @@ +description: Subscription details of a Network Participant. +allOf: + - $ref: "./Subscriber.yaml" + - properties: + key_id: + description: A unique ID of the subscription entry in a registry. + type: string + format: uuid + signing_public_key: + description: The signing public key of the subscriber + type: string + encr_public_key: + description: The encryption public key of the subscriber + type: string + valid_from: + description: Date-time which the signing and encryption keys are valid from + type: string + format: date-time + valid_until: + description: Time till which the signing and encryption keys are valid + type: string + format: date-time + status: + description: Status of the subscription + type: string + enum: + - INITIATED + - UNDER_SUBSCRIPTION + - SUBSCRIBED + - EXPIRED + - UNSUBSCRIBED + - INVALID_SSL + created: + type: string + format: date-time + updated: + type: string + format: date-time diff --git a/docs/beckn-core/schema/Support.yaml b/docs/beckn-core/schema/Support.yaml new file mode 100644 index 0000000..706b8e3 --- /dev/null +++ b/docs/beckn-core/schema/Support.yaml @@ -0,0 +1,18 @@ +description: Details of customer support +type: object +additionalProperties: false +properties: + ref_id: + type: string + callback_phone: + type: string + format: phone + phone: + type: string + format: phone + email: + type: string + format: email + url: + type: string + format: uri \ No newline at end of file diff --git a/docs/beckn-core/schema/Tag.yaml b/docs/beckn-core/schema/Tag.yaml new file mode 100644 index 0000000..b46596d --- /dev/null +++ b/docs/beckn-core/schema/Tag.yaml @@ -0,0 +1,15 @@ +description: Describes a tag. This is used to contain extended metadata. This object can be added as a property to any schema to describe extended attributes. For BAPs, tags can be sent during search to optimize and filter search results. BPPs can use tags to index their catalog to allow better search functionality. Tags are sent by the BPP as part of the catalog response in the `on_search` callback. Tags are also meant for display purposes. Upon receiving a tag, BAPs are meant to render them as name-value pairs. This is particularly useful when rendering tabular information about a product or service. +type: object +additionalProperties: false +properties: + descriptor: + description: Description of the Tag, can be used to store detailed information. + allOf: + - $ref: "./Descriptor.yaml" + value: + description: The value of the tag. This set by the BPP and rendered as-is by the BAP. + type: string + display: + description: This value indicates if the tag is intended for display purposes. If set to `true`, then this tag must be displayed. If it is set to `false`, it should not be displayed. This value can override the group display value. + type: boolean + diff --git a/docs/beckn-core/schema/TagGroup.yaml b/docs/beckn-core/schema/TagGroup.yaml new file mode 100644 index 0000000..a71d94c --- /dev/null +++ b/docs/beckn-core/schema/TagGroup.yaml @@ -0,0 +1,17 @@ +description: A collection of tag objects with group level attributes. For detailed documentation on the Tags and Tag Groups schema go to https://github.com/beckn/protocol-specifications/discussions/316 +type: object +additionalProperties: false +properties: + display: + description: Indicates the display properties of the tag group. If display is set to false, then the group will not be displayed. If it is set to true, it should be displayed. However, group-level display properties can be overriden by individual tag-level display property. As this schema is purely for catalog display purposes, it is not recommended to send this value during search. + type: boolean + default: true + descriptor: + description: Description of the TagGroup, can be used to store detailed information. + allOf: + - $ref: "./Descriptor.yaml" + list: + description: An array of Tag objects listed under this group. This property can be set by BAPs during search to narrow the `search` and achieve more relevant results. When received during `on_search`, BAPs must render this list under the heading described by the `name` property of this schema. + type: array + items: + $ref: "./Tag.yaml" \ No newline at end of file diff --git a/docs/beckn-core/schema/Time.yaml b/docs/beckn-core/schema/Time.yaml new file mode 100644 index 0000000..e3c332c --- /dev/null +++ b/docs/beckn-core/schema/Time.yaml @@ -0,0 +1,27 @@ +description: Describes time in its various forms. It can be a single point in time; duration; or a structured timetable of operations
This has properties like label, time stamp,duration,range, days, schedule +type: object +additionalProperties: false +properties: + label: + type: string + timestamp: + type: string + format: date-time + duration: + $ref: "./Duration.yaml" + range: + type: object + additionalProperties: false + properties: + start: + type: string + format: date-time + end: + type: string + format: date-time + days: + type: string + description: comma separated values representing days of the week + schedule: + $ref: "./Schedule.yaml" + diff --git a/docs/beckn-core/schema/TimeToLive.yaml b/docs/beckn-core/schema/TimeToLive.yaml new file mode 100644 index 0000000..af641c7 --- /dev/null +++ b/docs/beckn-core/schema/TimeToLive.yaml @@ -0,0 +1,3 @@ + description: The time-to-live in seconds, for this object. This can be overriden at deeper levels. A value of -1 indicates that the associated object is valid only once. + type: integer + minimum: -1 \ No newline at end of file diff --git a/docs/beckn-core/schema/Tracking.yaml b/docs/beckn-core/schema/Tracking.yaml new file mode 100644 index 0000000..384ad57 --- /dev/null +++ b/docs/beckn-core/schema/Tracking.yaml @@ -0,0 +1,21 @@ +description: Contains tracking information that can be used by the BAP to track the fulfillment of an order in real-time. which is useful for knowing the location of time sensitive deliveries. +type: object +additionalProperties: false +properties: + id: + description: A unique tracking reference number + type: string + url: + description: A URL to the tracking endpoint. This can be a link to a tracking webpage, a webhook URL created by the BAP where BPP can push the tracking data, or a GET url creaed by the BPP which the BAP can poll to get the tracking data. It can also be a websocket URL where the BPP can push real-time tracking data. + type: string + format: uri + location: + description: In case there is no real-time tracking endpoint available, this field will contain the latest location of the entity being tracked. The BPP will update this value everytime the BAP calls the track API. + allOf: + - $ref: "./Location.yaml" + status: + description: This value indicates if the tracking is currently active or not. If this value is `active`, then the BAP can begin tracking the order. If this value is `inactive`, the tracking URL is considered to be expired and the BAP should stop tracking the order. + type: string + enum: + - active + - inactive \ No newline at end of file diff --git a/docs/beckn-core/schema/Vehicle.yaml b/docs/beckn-core/schema/Vehicle.yaml new file mode 100644 index 0000000..b723091 --- /dev/null +++ b/docs/beckn-core/schema/Vehicle.yaml @@ -0,0 +1,33 @@ +description: Describes a vehicle is a device that is designed or used to transport people or cargo over land, water, air, or through space.
This has properties like category, capacity, make, model, size,variant,color,energy_type,registration +type: object +additionalProperties: false +properties: + category: + type: string + capacity: + type: integer + make: + type: string + model: + type: string + size: + type: string + variant: + type: string + color: + type: string + energy_type: + type: string + registration: + type: string + wheels_count: + type: string + cargo_volumne: + type: string + wheelchair_access: + type: string + code: + type: string + emission_standard: + type: string + diff --git a/docs/beckn-core/schema/XInput.yaml b/docs/beckn-core/schema/XInput.yaml new file mode 100644 index 0000000..c227887 --- /dev/null +++ b/docs/beckn-core/schema/XInput.yaml @@ -0,0 +1,33 @@ +description: Contains any additional or extended inputs required to confirm an order. This is typically a Form Input. Sometimes, selection of catalog elements is not enough for the BPP to confirm an order. For example, to confirm a flight ticket, the airline requires details of the passengers along with information on baggage, identity, in addition to the class of ticket. Similarly, a logistics company may require details on the nature of shipment in order to confirm the shipping. A recruiting firm may require additional details on the applicant in order to confirm a job application. For all such purposes, the BPP can choose to send this object attached to any object in the catalog that is required to be sent while placing the order. This object can typically be sent at an item level or at the order level. The item level XInput will override the Order level XInput as it indicates a special requirement of information for that particular item. Hence the BAP must render a separate form for the Item and another form at the Order level before confirmation. +type: object +additionalProperties: false +properties: + head: + description: Provides the header information for the xinput. + type: object + additionalProperties: false + properties: + descriptor: + $ref: "./Descriptor.yaml" + index: + type: object + additionalProperties: false + properties: + min: + type: integer + cur: + type: integer + max: + type: integer + headings: + type: array + items: + type: string + description: The heading names of the forms + form: + $ref: "./Form.yaml" + form_response: + $ref: "./FormResponse.yaml" + required: + description: Indicates whether the form data is mandatorily required by the BPP to confirm the order. + type: boolean diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..0d8b862 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,381 @@ + + + + + ONDC Mobility + + + + + + +
+
+ + +
+

ONDC Financial Services Developer Guide

+
+
+
+
+
+
+ +
+
+
+ + + + + +
Example Set + +
+
+
+
+
+
+ + + + + +
Flow Set + +
+
+
+
+

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ + + + + + +
Attribute Set + + + +
+
+ + + + + + + + + +
Attribute PathRequiredUsageOwnerTypeDescription
+
+
+
+ + + + +
+
Error Set
+
+ BPP = Seller AppBAP = Buyer App +
+
+
+ + + + + + + +
CodeFromEventDescription
+
+
+
+
+
+
+
+
+
Enum
+ + + + + + + + + + + + + +
API + +
Field + +
Enum + +
+
+
+
+
+
+
Tags
+ + + + + + + + + + + + + + + + + +
API + +
Field + +
TagGroup + +
Tag + +
+
+
+
+
+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/mobility-core/.gitmodules b/docs/mobility-core/.gitmodules new file mode 100644 index 0000000..758ce21 --- /dev/null +++ b/docs/mobility-core/.gitmodules @@ -0,0 +1,4 @@ +[submodule "api/core-0.9.x-lts"] + path = api/core-0.9.x-lts + url = https://github.com/beckn/protocol-specifications + branch = core-0.9.x-lts diff --git a/docs/mobility-core/LICENSE.md b/docs/mobility-core/LICENSE.md new file mode 100644 index 0000000..c1c3390 --- /dev/null +++ b/docs/mobility-core/LICENSE.md @@ -0,0 +1,177 @@ +## creative commons + +# Attribution-NonCommercial-ShareAlike 4.0 International + +Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. + +### Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. + +* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors). + +* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). + +## Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. + +### Section 1 – Definitions. + +a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. + +b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. + +c. __BY-NC-SA Compatible License__ means a license listed at [creativecommons.org/compatiblelicenses](http://creativecommons.org/compatiblelicenses), approved by Creative Commons as essentially the equivalent of this Public License. + +d. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. + +e. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. + +f. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. + +g. __License Elements__ means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution, NonCommercial, and ShareAlike. + +h. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. + +i. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. + +h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. + +i. __NonCommercial__ means not primarily intended for or directed towards commercial advantage or monetary compensation. For purposes of this Public License, the exchange of the Licensed Material for other material subject to Copyright and Similar Rights by digital file-sharing or similar means is NonCommercial provided there is no payment of monetary compensation in connection with the exchange. + +j. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. + +k. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. + +l. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. + +### Section 2 – Scope. + +a. ___License grant.___ + + 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: + + A. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and + + B. produce, reproduce, and Share Adapted Material for NonCommercial purposes only. + + 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + + 3. __Term.__ The term of this Public License is specified in Section 6(a). + + 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + + 5. __Downstream recipients.__ + + A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. + + B. __Additional offer from the Licensor – Adapted Material.__ Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. + + C. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. + + 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + +b. ___Other rights.___ + + 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this Public License. + + 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Licensed Material is used other than for NonCommercial purposes. + +### Section 3 – License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the following conditions. + +a. ___Attribution.___ + + 1. If You Share the Licensed Material (including in modified form), You must: + + A. retain the following if it is supplied by the Licensor with the Licensed Material: + + i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of warranties; + + v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + + B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and + + C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. + + 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. + +b. ___ShareAlike.___ + +In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. + + 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-NC-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. + +### Section 4 – Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: + +a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database for NonCommercial purposes only; + +b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and + +c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. + +### Section 5 – Disclaimer of Warranties and Limitation of Liability. + +a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__ + +b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__ + +c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. + +### Section 6 – Term and Termination. + +a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. + +b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + + 2. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + + For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. + +c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. + +d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. + +### Section 7 – Other Terms and Conditions. + +a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. + +b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. + +### Section 8 – Interpretation. + +a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. + +b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. + +c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. + +d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. + +``` +Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. + +Creative Commons may be contacted at [creativecommons.org](http://creativecommons.org/). +``` diff --git a/docs/mobility-core/README.md b/docs/mobility-core/README.md new file mode 100644 index 0000000..04fa741 --- /dev/null +++ b/docs/mobility-core/README.md @@ -0,0 +1,54 @@ +# Beckn Protocol Mobility Specification +Recommendations for beckn protocol-enabled mobiity application developers + +## Latest Version + +0.8.0 + +This version is an adaptation of beckn protocol [core version 0.9.4 LTS](https://github.com/beckn/protocol-specifications/tree/core-0.9.4) + +## Earlier Versions + +The earlier versions of beckn protocol for mobility was in-sync with core. Hence, the version number for mobility was equal to the version number of core, To visit these versions, visit the core protocol specification repository. + +| Version | Release Date | Core Version | Author | Comments | +|---------|--------------------|--------------|--------------|----------------------------------------------------------------------------------------| +| 0.8.0 | April 4th, 2023 | 0.9.4 | Ravi Prakash | Compatible with LTS version of core | +| 0.7.0 | November14th, 2022 | 0.9.3 | Ravi Prakash | Re-initialized Mobility Adaptation specification with independent versioning from core | + +## Earlier Versions (Deprecated) + +The earlier versions of beckn protocol for mobility was in-sync with core. Hence, the version number for mobility was equal to the version number of core, To visit these versions, visit the core protocol specification repository. + +| Version | Release Date | +|-----------|---------------------------------| +| 0.9.2 | August 03, 2021 (Active) | +| 0.8.2 | August 28, 2020 (Active) | +| 0.8.0 | August 23, 2020 (deprecated) | +| 0.7.1 | April 27, 2020 (deprecated) | + + +## Introduction + +Beckn protocol is a collection of open specifications consisting of protocol APIs, message formats, network design and reference architectures to allow any two entities to execute commercial transactions without being on the same platform. The core protocol specifications are industry-sector-agnostic by design and allow sector-specific policies to be layered as machine readable code. + +This server-to-server communication protocol allows any consumer facing online platform to discover and transact with any business with minimal implementation overhead. The server-to-server nature of the protocol allows rich user experiences to be built by bundling services from multiple independent platforms. + +**Beckn protocol mobility specification** is an adaptation of the [core protocol specification](https://github.com/beckn/protocol-specifications) for the mobility sector and applies mobility specific rules and policies on its API and architecture to allow the creation of Open Mobility Networks. A reference mobility ecosystem created using beckn mobility specification can be found [here](https://github.com/beckn/mobility/blob/main/docs/images/Ecosystem%20Architecture.png) + +## Evolution + +The evolution of the beckn protocol mobility specification is guided by the recommendations of the **Mobillty Working Group**. It consistes of volunteers from the **Beckn Open Collective**, a thriving community of volunteers that actively contribute to beckn protocol, its adaptations, and its implementations across various sectors. + +To know more about how the specification evolves, visit the GOVERNANCE document in this repository. + +To follow discussions related to the mobiilty specification please visit the [Discussions Forum](https://github.com/beckn/mobility/discussions) on GitHub + +To connect with members of the mobility working group and other members of the Beckn Open Collective, please join the [Beckn Open Collective Discord Server](https://discord.gg/vxNjTzsgcP) + +## Contributing to the Specification + +Anyone can contribute to the specification. Contributors must follow the contribution guidelines as mentioned in the CONTRiBUTION document in this repository. + + +Each contribution will be peer-reviewed by the Mobility Working Group members. If approved, this contribution will be merged with the applicable versions of the mobility specification. diff --git a/docs/mobility-core/api/core-0.9.x-lts/.gitignore b/docs/mobility-core/api/core-0.9.x-lts/.gitignore new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/docs/mobility-core/api/core-0.9.x-lts/CHANGELOG.md b/docs/mobility-core/api/core-0.9.x-lts/CHANGELOG.md new file mode 100644 index 0000000..0e99ae2 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/CHANGELOG.md @@ -0,0 +1,162 @@ +# Changelog + +## Core v0.9.3 + +### 13 July, 2021 + +**Changes in Context schema object** +- Removed ack from action +- Changed feedback to rating in action enum +- Updated description for bap_id, bpp_id, bap_uri, bpp_uri, transaction_id, message_id +- changed ttl as type string and updated description + +**Removed context object from acknowledgement responses** + +**Changes to Intent schema object** +- removed query_string +- removed purpose + +**The following were changed to message.order** +- select request's message.selected +- on_select request's message.selected +- on_init request's message.initialized + +**Changes to Fulfillment schema object** +- Added provider_id +- Removed purpose + +**Updated description of Provider.id** + +**Removed tl_method from Tracking schema object** + +**Removed type and ref_id from Quotation schema object** + +**Added category_id to the following** +- Provider schema object +- Intent.provider + +**Changes to Payment schema object** +- Added property transaction_status +- Added property currency + +### 10 August, 2021 + +**Fixed inconsistencies in the required properties** +Provider was removed from required in the following places : +- Order property in /select +- Order property in /init +- Order schema object + +In the following places message was made the only required property : +- /on_search +- /on_select +- /on_init +- /on_confirm +- /on_track +- /on_cancel +- /on_update +- /on_status +- /on_rating +- /on_support + +### 12 August, 2021 + +**Added rating property to the following schema objects** +- Item +- Provider +- Fulfillment + +**Fulfillment and Provider have been referenced directly in the Intent schema object** + +**Security schemes cleanup** +- Added Gateway Subscriber Auth at top level security definition. +- Removed security from individual paths. +- Removed Signature headers +- Updated the format of the authorization headers + +### 19 August, 2021 + +**Added schedule to Time schema object** +Schedule schema object was added to Time + +### 19 August, 2021 + +**Updated the rating flow** + +**Added/Edited the following schema objects :** +- **Rating** - Edited so that the rating_category, rating value and id is present +- **RatingAck** - Newly created to send acknowledgement of receival of rating and feedback +- **FeedbackForm** - Newly created object to represent feedback form +- **FeedbackFormElement** - Newly created object to represent an element in a feedback form +- **FeedbackUrl** - Newly created object to represent feedback URL sent by a BPP +- **Feedback** - Object edited to hold feedback form or feedback URL + +**API endpoints edited/created :** +- **/get_rating_categories** : Returns the allowed categories that can be rated +- **/get_feedback_categories** : Returns the allowed categories that can have a feedback +- **/get_feedback_form** : Request the BPP to get a feedback form +- **/feedback_form** : Get a feedback form from the BPP. Callback response of /get_feedback_form +- **/rating** : Uses Rating object as message +- **/on_rating** : Used RatingAck as message + +**Made all the meta APIs async. Created the following new meta BAP APIs :** +- POST /cancellation_reasons +- POST ​/return_reasons +- POST /rating_categories +- POST ​/feedback_categories + +**Added Rateable property** +A new schema object Rateable of type boolean was added. +The same was added to the following : +- Agent +- Fulfillment +- Item +- Provider +- Location array inside Provider + +### October 8, 2021 + +**Added descriptor to Intent schema object** + +### October 11, 2021 + +**Removed enum in rating_category** + +### October 12, 2021 + +**Removed required** +- Removed intent required from /search +- Removed required id and location from provider object in /select +- Removed required quantity from items in /select +- Removed required items from order object in /select +- Removed required id and location from provider object in /init +- Removed required quantity from items in /init +- Removed required items and billing from order object in /init +- Removed cancellation_reason_id from /cancel +- Removed required cred from Agent schema object +- Removed required name and phone from Billing schema object +- Removed required items, billing, quote and payment from Order schema object +- Removed required quantity from items property in Order schema object +- Removed required id and location from provider property in Order schema object + +### November 24, 2021 + +**Added fulfillment_id in Item schema object** + +### December 10, 2021 + +**Added new Gateway Authentication scheme with deprecation notice** + +### December 13, 2021 + +**Changed the order object in select and init call** + +### December 14, 2021 + +**Authorization object in fulfillment start and end** +- New schema object Authorization added +- New property authorization added to Fulfillment schema object and refers to the newly created Authorization object. + +### December 22, 2021 + +**Added document object array in order** \ No newline at end of file diff --git a/docs/mobility-core/api/core-0.9.x-lts/CONTRIBUTION.md b/docs/mobility-core/api/core-0.9.x-lts/CONTRIBUTION.md new file mode 100644 index 0000000..80043e4 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/CONTRIBUTION.md @@ -0,0 +1,243 @@ +# Contributing to the Specification + + +## Draft 01 + + +# Authors + +1. Ravi Prakash - ravi@becknfoundation.org + + +# Latest Version + +Draft 01 + + +# Previous Versions + +None + + +# Scope + +This document intends to establish transparent and open processes and guidelines to contribute to the beckn protocol specification. It contains design principles and guidelines and considerations that should be adopted by anyone wishing to propose changes to the specification. + +This document is intended for the following audience. + + + +1. Any person or organization who wants to propose a change in the specification + + +# Prerequisites + + + +1. Readers must have knowledge and hands-on experience in **git** and **GitHub**. +2. Readers must have knowledge of beckn protocol specification + + +# Context + +Beckn protocol specification exists as a set of public repositories on Github at https://github.com/beckn. Like all version controlled open-source repositories, there are guidelines that must be followed; design principles to be considered in order to propose changes to the files present in these repositories. These pull requests will then be reviewed by the maintainers of the repository and subsequently merged with the main / master branch of that repository. The governing body and repository maintainer of the beckn protocol specification is the **Core Working Group**. + + +# Abstract + +The evolution of beckn protocol specification should be use-case driven. The working group can specify support for hypothetical use cases as they see fit, but specifications should be backed by realistic scenarios. Management of an open-source specification like beckn protocol should be governed by well defined policies and processes. Proposing any change to an open-source repository starts by raising an Issue against a repository. After an Issue is raised, a Pull Request must be created and linked to that issue. These pull requests must be reviewed and merged by the relevant working groups and repository maintainers via a standard governance model. + + +# Terminology + + + +1. **Git:** A decentralized version control software +2. **Github:** An online platform for managing shared repositories via git +3. **Pull Request:** A request to merge a change to an existing version of the repository +4. **Core Working Group:** Current maintainer and governing authority of the specification + + +# Expected Outcomes After Reading This Document + +After reading this document, the reader should be able to understand how to contribute to the specification. + + +# Introduction + +The current process for evolution of beckn protocol specification is described in the **Contribution Guidelines** section of the document. Development of the next version of the specification is guided by the **Core Working Group (CWG)**. This working group contains members that bring their API expertise, industry knowledge, incorporate feedback from the community, and expand the group of committers as and when appropriate. All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. + +The CWG holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. + +The beckn protocol governance principles encourage participation from individuals and companies alike. + + +# Contribution Guidelines + +Contributing to the specification involves active participation by the contributor in the beckn open community. The following guidelines ensure a higher chance of a proposal being accepted by the community. + + + +1. Knowledge of the specification +2. Initiating healthy discussions on Github and Slack +3. Helping other community members with Issues +4. Providing sufficient documentation and in-depth analysis +5. Following a code of conduct in the discussion forums + +Not all feedback can be accommodated as a change and there may be solid arguments for or against a change being appropriate for the specification. + + +# Contribution Process + + +![Flow](http://13.235.139.60/dev-docs-images/PR%20Flowchart.png) + + + +## 1. Review the specification + +All contributors are expected to review the specification before submitting a proposal. If there is anything that a contributor does not understand, they are free to pose questions to the beckn open community of developers. + + +## 2. Join the Beckn Open Community on Slack + +Joining the open community on Slack is a simple process. Click [here](https://join.slack.com/t/beckn/shared_invite/zt-ucfhmyow-5XuHdRpFrqO2sh4gzcnuQw) to join the developer community on Slack. This is useful to have quick real-time interactions with the developers in the community. + + +## 3. Initiate / participate in discussion threads on Github + +Before proposing a change to the specification, visit the discussion threads on Github [here](https://github.com/beckn/protocol-specifications/discussions) + + +## 4. Subscribe to existing Issues or Pull Requests + +Check the [issues](https://github.com/beckn/protocol-specifications/issues) and [pull requests](https://github.com/beckn/protocol-specifications/pulls) to see if someone has already documented your idea or feedback on the specification. If you find something relevant to your proposal, subscribe to the discussions around Issues and PRs. + + +## 5. Raise an Issue (Feature Requests or Enhancements) + +Create an issue to describe a new concern. If possible, propose a solution. + + +## 6. Create a Pull Request + +Submit a Pull Request against that Issue. + + +# Specification Change Criteria + +The specification will evolve over time. Changes may be made when any of the following criteria are met: + + + +1. **Clarity**. The current "way" something is done doesn't make sense, is complicated, or not clear. +2. **Consistency**. A portion of the specification is not consistent with the rest, or with the industry standard terminology. +3. **Necessary functionality**. We are missing functionality because of a certain design of the specification. +4. **Forward-looking** **Designs**. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. +5. **Impact**. A change will provide an impact on a large number of use cases. We should not be forced to accommodate every use case. Maintainers should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec. Evolution cannot be edge-case driven. + + +# Considerations before Proposing a Change + +For each change in the specification we should always consider the following: + + + +1. **Migration Impact : **Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change +2. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. +3. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface [Needs Edit] + +**Note:** Spec change proposals will be approved by the CWG. Approval will be given via a comment on the issue itself, for example, "_Approved by @cwg-admin_". No change will be approved until there is documentation for it, supplied in an accompanying PR. + + +# Change Tracking and Management on GitHub + +**GitHub** is the medium of record for all spec designs, use cases, and so on. + +All the specification related repositories are present on the official beckn protocol Github account [here](https://github.com/beckn). + + +## Sources of Truth + + + +1. The **protocol-specifications** repository is the source of truth for the core transaction API specification. +2. The **registry** repository is the source of truth for implementing the registry infrastructure +3. The **specification-files** repository is the source of truth for all human readable specification files + + +## Branch Structure + +At any given time, there would be _at most_ 4 working branches. The branches would exist if work has started on them. For example, assume a current version of **0.9.2** in the protocol-specifications repository. + + + +1. **master** - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted. +2. **core-0.9.3-draft** - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications. +3. **core-0.10.0-draft** - The next MINOR version of the specification. This would include backward compatible changes to the specification like attributes to existing schema. +4. **core-1.0.0-draft** - The next MAJOR version of the specification. + +The master branch shall remain the current, released beckn protocol specification. The will describe and link the working branch(es) on the default README.md on main. + +Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. + +New features should be done in feature branches/forks which, upon approval, will be merged into the proper work branch. + + +## Raising an Issue in the Specification + +Any change to the specification must begin with the creation of a Github Issue. The process for raising an issue on GitHub is detailed [here](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue). + + +## Creating a Pull Request + +All PRs to a specific version of the specification must be made to the **draft** branch of the next upcoming version. For example, All patch changes to version **0.9.2** must be made to the** 0.9.3-draft **branch. + + +# Adding Features to the Core Schema + +Wherever and whenever suitable, new features will be introduced inside the core protocol schema in accordance with the beckn protocol design principles. New features should be _namespaced_ by standard prefixes to indicate their deviation from the standard schema. This namespacing approach enables new features to be designed, documented and then implemented by platforms that are interested in the feature, without putting the burden of implementation on all platforms. If the feature is successfully implemented by a majority of platforms and there is demonstrable value added by the feature, it will become a candidate for inclusion inside the Core Schema in a future release of the specification, at which point all implementations will be expected to support the feature. + + +## Feature evolution stages + +All new features have a life cycle starting from a proposal to a required standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. + + +![Feature Stages](http://13.235.139.60/dev-docs-images/Feature%20Stages.drawio.png) + +## Namespacing Non-Standard Properties + +The name of any new property in the core schema must be namespaced using the below format indicating that it is a **Non-Standard Property **of a schema. + + +`"./{namespace-id}.{feature-name}.{feature-stage}"` + +### Non-standard Property Components + +1. **The dot slash ( ./ )** : This symbol in the context of core specification represents a non-standard property in the core schema. If this property is being developed by a network, all platforms must be able to recognize that this attribute is currently not part of the core specification and use / ignore it appropriately. +2. **namespace-id **: This is a unique id linked to a feature being submitted for inclusion in the specification by a unique entity. The format of the ID varies with the proposer of the feature. + 1. **For Individuals** : Individuals submitting new features must namespace the property with their **Github username**.For example, if Alice is a developer (_username : @alice-dev_) wants to add a feature called `"direction"` in core schema, she must submit her proposal with the new property **"./@alice-dev.direction.proposed" + 2. For Organizations: Organizations submitting new features must namespace the property with their Github orgname. For example, if Beckn Foundation (username : @beckn-foundation) wants to add a feature called “speed” in core schema, she must submit her proposal with the new property "./@beckn-foundation.speed.proposed" +3. feature-name : This is the name of the feature. While creating the feature-name, proposers are recommended to use the following guidelines before submitting the proposal. Please note that these are more like guidelines than rules. + - The English language must be used to propose any new features. + - Standard programming jargon can be used as long as it is widely accepted by the developer community. For example "const" is an acceptable keyword. + - The feature name must be generic and not specific to a limited region or domain +4. feature-stage : For a new feature this value will always be “proposed”. The other values are draft, recommended and required. These values are reserved for CWG committers and will be described in detail in the Specification Governance document. + +## Identifying a new feature in the Schema + +New features under discussion should be identified by the prefixed **“./”** in the property of the json schema. If the feature is deemed appropriate for inclusion in the specification, the namespace will be removed and the feature will be moved inside the Core Schema. Implementations that support new features should plan for the future removal of the prefix. When implementations add support for a later version of beckn protocol that includes the final implementation of the feature, they MUST NOT support the use of the prefix for that feature. New features will only be promoted into minor or major releases of the specification and therefore will be transparent to specification description writers and reference implementation providers who choose not to use the feature while in its draft state. This versioning schema does not apply to V0.x features. In 0.x features, even patch versions can contain bug fixes and enhancements rather than just text changes. + + +## Identifying a new feature in Issues + +New features in Github Issues will be **labeled** with the **feature-stage** label and will be initially labelled as **proposed, draft, recommended, required or not-recommended**. When the proposal is considered sufficiently stable for pilot implementation, it will be labeled **recommended**. If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the “draft” feature-stage name itself may be versioned with a version suffix. e.g. draft-02. When a draft feature becomes part of a future update to the specification any version suffix will be removed. Draft features that are deemed not appropriate for inclusion MUST be marked with the **not-recommended** label. Draft-features that are considered suitably specified and have had successful pilot implementations will be marked with the **recommended** label. If a draft feature is considered to be a required feature in ALL implementations, it will be marked with a **required** label. + +Not all future new features will be introduced in this way. Some new features impact the specification in ways that cannot be encapsulated in this way. However, where a new feature can be introduced in this way, it should be. + + +# Participation + +While governance of the specification is the role of the CWG, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. + diff --git a/docs/mobility-core/api/core-0.9.x-lts/CONTRIBUTORS.md b/docs/mobility-core/api/core-0.9.x-lts/CONTRIBUTORS.md new file mode 100644 index 0000000..a24aa59 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/CONTRIBUTORS.md @@ -0,0 +1,17 @@ +# Ravi Prakash +* __Github__ : [core-wg-admin](https://github.com/core-wg-admin) + +# Pramod Varma +* __Github__ : [pramodkvarma](https://github.com/pramodkvarma) + +# Nirmal Rajeevan +* __Github__ : [techframewirk](https://github.com/techframewirk) + +# Sujith Nair +* __Github__ : [sjthnrk](https://github.com/sjthnrk) + +# Paul Kapustin +* __Github__ : [pkapustin](https://github.com/pkapustin) + +# Venky Mahadevan +* __Github__ : [venkatramanm](https://github.com/venkatramanm) diff --git a/docs/mobility-core/api/core-0.9.x-lts/GOVERNANCE.md b/docs/mobility-core/api/core-0.9.x-lts/GOVERNANCE.md new file mode 100644 index 0000000..c42a95a --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/GOVERNANCE.md @@ -0,0 +1,325 @@ +# Specification Governance +## Draft 02 + +# Authors + +1. Ravi Prakash : ravi@becknfoundation.org + +# Latest Version + +Draft 02 + +# Previous Versions + +Draft 01 | Deprecated + +# Scope + +This document intends to establish processes and guidelines which build a transparent, open mechanism for deciding how to manage contributions to the beckn protocol specification. The Core Working Group will initially follow these processes when merging changes from external contributors or from the CWG itself. This guideline document will be adjusted as practicality dictates. + +This document is intended for the following audience. + +1. Anyone who wants to understand how contributions are reviewed and merged by the Core Working Group + + +# Prerequisites + +1. Readers must have a working knowledge of git +2. Readers should also know how open-source repositories are managed on Github. +3. Readers must have knowledge and understanding of beckn protocol specification + +# Context + +Beckn protocol exists as a set of public repositories on Github at https://github.com/beckn. These repositories contain specification documents, reference implementations, tools and utilities. Like all version controlled open-source repositories, there are processes that must be adopted to manage changes to the files present in these repositories. The most common way a change is proposed to the specification is via an Issue linked to that repository which ultimately gets converted to a Pull Request linked to that Issue. These pull requests must then be reviewed by the maintainers of the repository and subsequently merged with the main / master branch of that repository. + + +# Abstract + +The evolution of beckn protocol specification is always use-case driven. The Core Working Group can specify support for hypothetical use cases as they see fit, but the specifications should be backed by realistic scenarios. Management of contributions towards an open-source specification like beckn protocol are governed by well defined policies and processes. These processes will evolve just like the specification does, based on use cases. Given beckn is designed to be a global protocol, maintainers and committers must be aware any change committed to the specification has a global impact on implementation. Therefore, the governance model of beckn protocol specification is based on strict and unambiguous design principles described in this document. Anyone reviewing pull requests must apply these principles on each suggested change and decide if a change is deemed worthy of inclusion into the specification. The methodologies, guidelines and processes of conducting working group meetings to review contributions made to the specification is described in this document. + + +# Terminology + +1. **Git:** A decentralized version control software +2. **Github:** An online platform for managing shared repositories via git +3. **Pull Request:** A request to merge a change to an existing version of the repository +4. **Core Working Group:** Current maintainer and governing authority of the specification + + +# Expected Outcomes after reading this document + +After reading this document, the reader should be able to + +1. Understand how to review and merge changes to the specification + +# Introduction + +The Beckn protocol is maintained via an open community-driven governance model. The community comprises multiple businesses and organizations that actively contribute to the specification to fuel their digital acceleration. This collaboration across domains, technologies and expertises will bring in new ideas which need to be part of the protocol. Hence there is a need for a standardised process for making relevant changes to the specification as well and for a retrospective understanding of the specification. The governance model for beckn protocol has been created using some of the best practices of globally recognized governance models. + +Evolution of beckn protocol specification is guided by the **Core Working Group**. This working group contains members that bring their API expertise, industry knowledge, incorporate feedback from the community, and expand the group of committers as and when appropriate. All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. + +The Core Working Group holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. + +This governance model is inspired from the [OpenAPI specification governance model](https://www.openapis.org/participate/how-to-contribute/governance). + + +# The Beckn Credo + +The Beckn community is an open community. So, no registrations. No memberships. No partnerships. Just a minimal footprint of an open and equally accessible Beckn Protocol that anyone can use. Multiple businesses and organizations have started using beckn protocol to fuel their digital acceleration. The credo of being an open protocol creates a level-playing field for any market player, small or large. + + +## Motivation + +To make the internet small-business friendly. be a force multiplier with minimal footprint. + +## Guiding Lights + +Open specs, equal access. retain agency of small businesses. non-rivalrous, non-exclusive networks + +## Community Driven + +Increase value for all participants. be a network weaver in your own way. be a contributor of specs and best practices + +The Beckn Protocol is an open commerce protocol with an abstract core, which is enabling market players to reimagine building seamless digital experiences and networks. This is very similar to how HTTP, while being a simple and open protocol has fueled seamless interaction between multiple systems and led to an explosive growth in internet adoption. + +## Open Community Contributions + +The Beckn Protocol has been accepting community contributions to the specification since May 2020. + +# Design Principles + +To allow open contributions from the community, a governance model is required to apply some basic design principles while reviewing or proposing changes to the specification. They are: + +## Interoperability via Abstraction: +Any feature included in the specification must be abstracted so as to allow it to be consumed across a global range of use cases. That means no feature should be linked to a specific domain, region or use case. + +## Optimal ignorance: +Before including any feature in the specification, reviewers should ask the following questions: a) _Do we need it?_ And, b) _Do we need it now? If the answer to both these questions is “Yes” then this criteria will have been met. + +## Privacy and Security +Any feature being included in the specification must be tested for any security or privacy vulnerabilities. Free text fields, loosely-typed fields and any fields that may be used to implicitly capture Personally Identifiable Information should not be accepted. + +## Scalability + +Any feature being included in the specification must be tested for scalability. String fields with unlimited size; arrays with unlimited size etc, must be discouraged. Any feature that is included must work at scale. + +## Reusability +Any new feature must be checked if it can reuse components from the existing schema before inclusion into the specification. + +## Unification over Standardization +Not all features across the globe can be standardized. Standard values vary with domain, region and adoption. In case multiple standards are being adopted for a single feature, it is recommended that both the standards are included in the feature instead of proposing a new standard. For example, if a Location schema is defined using gps and address, then the feature should include both gps and address instead of choosing one over the other. Standardization should occur as a natural consequence of market adoption rather than a forced adoption. + +There will be exceptions to the above principles. The objective of the Core Working Group is to address such exceptions and define the most logical way forward to include such exceptions. + +# Need for Governance + +Since the core specification is essentially abstracted, the implementers of the specification must use instances of the core specification for various domains, regions and scope. Moreover, the Beckn Protocol specification is built by applying policies on the core specification. Hence, there is a need for a strong and inclusive governance model that adheres to the basic design principles while simultaneously being inclusive in its approach to evolution as opposed to a foundation-controlled evolution. + + +# Areas That Require Specification Governance + +There are many independently governable specification elements in the Beckn Protocol. These elements are called areas. Each area will have multiple working groups under it. The following are the areas currently identified : + + +* **API** : Core API and schema definitions +* **Taxonomy** : Domain-specific repositories for organization of taxonomies and taxonomy element definitions +* **Certification** : Certification and compliance rules and specifications +* **Architecture** : High level architecture definition and definitions of the various components in the network +* **Network Security** : Network security protocols and best practices +* **Policy** : Governance structures, licences and copyrights +* **Missions** : Specific implementation related working groups + + +# Area Director (AD) + +Each area will have an Area Director who will be responsible for the functioning and creation of the Working Groups (WG) under it and appointing the WG chair(s). The AD will be a volunteer from the community who will adhere to the design principles while reviewing any proposal submitted by a contributor. + +# Working Groups (WG) + +A Working Group is a collection of people who collaborate on, and are responsible for managing evolution of the specification. + +## Working Group Structure + +Each WG has the following structure + +1. WG Administrators +2. WG Committers +3. WG Members + +### Working Group Administrators + +Each WG will have an Administrator (Admin). The Admin will be responsible for declaring a rough consensus on any decision the group has to make. Having full consensus is preferred but not required. During a decision process if the Admin decides that the issues brought forward have been discussed enough and the group has made an informed decision, the Admin can declare that there is rough consensus to go ahead with the decision. For assets (github repository, document collections, group email id etc) coming under each WG, the Admin will have access to modify it. + +### Working Group Committers + +Each WG will have at least one committer. The purpose of the committer is to review PRs against WG guidelines and design principles and post comments on Github regarding the status of the PR. + +### Working Group Members + +Anyone can send a request to be added to the WG to attend meetings and weigh in with opinions about any decision or through mails. To become part of a WG, one must send an email to the WG Admin. WG members can participate in discussions on Issues and Pull Requests, and respond to comments in the discussion forums. However, the approval of a working group member will not be decisiove in merging PRs to the specification. + +# Managing Specification Evolution + +The specification will evolve over time. Changes may be made when any of the following criteria are met: + +1. **Clarity**. The current "way" something is done doesn't make sense, is complicated, or not clear. +2. **Consistency**. A portion of the specification is not consistent with the rest, or with the industry standard terminology. +3. **Necessary functionality**. We are missing functionality because of a certain design of the specification. +4. **Forward-looking Designs**. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be. +5. **Impact**. A change will have an impact on a large number of use cases. We should not be forced to accommodate every use case. Maintainers should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven. + +# Specification Review Guidelines + +While reviewing each change in the specification committers should always consider the following: + +1. **Migration Impact**: Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change +2. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. +3. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface + +Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @cwgadmin" however at least one formal GitHub-based flow approval must be given. After the voting criteria is met, the WG Admin can merge or assign a member to merge the PR. No change should be approved until there is documentation for it, supplied in an accompanying PR. + +# Feature Evolution + +All new features have a life cycle starting from a proposal to a required standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. + + +All proposals to the specification are submitted as namespaced properties as mentioned in CONTRIBUTIONS.md. The working group has the responsibility of reviewing these proposals and classify them accordingly as draft, recommended, required or not-recommended features. Once classified, the WGs must rename the namespace with the appropriate feature stage component after review. + + +## Proposal + +All proposals will have the following namespace + + +``` +"./@alice-dev.direction.proposed" +``` + + + +## Draft Features + +All draft features will have the following namespace structure + + +``` +"./@proposer.feature.draft" +``` + + + +## Recommended Standard + +All recommended standards will have the following namespace structure + + +``` +"./@proposer.feature.recommended" +``` + + + +## Required Standard + +All recommended standards will have the following namespace structure on the draft branch. All namespaces from required standards have to be replaced with the feature names before merging them to master. + + +``` +"./@proposer.feature.required" +``` + + + +### Not Recommended + + +``` +"./@proposer.direction.not-recommended" +``` + +# Working Group Weekly Meetings + +To review change requests to the specification, Working Groups should review and discuss their inclusion in weekly meetings. The meeting consists of four major agenda items. + +1. **Bugs:** This involves discussing all Issues that have been raised as bugs. These will have the highest priority in terms of consideration and will have to be acknowledged and resolved within one week of submission. +2. **Proposed Enhancements:** This involves listing all the new features that have been proposed in the form of Pull Requests to the draft branches. As there are four types of branches, there is an order of priority with which proposals to each branch should be reviewed. The order of priority is recommended as follows + 1. Minor Version Draft Branch + 2. Patch Version Draft Branch + 3. Major Version Draft Branch + +As the master branch cannot accept any proposals, any proposal to the master branch must be explicitly rejected by the committers. + +3. **Draft features:** This agenda involves all the proposals that have been accepted and have been classified as draft features in the previous working group meeting. In this agenda, the working group will decide whether to classify it as a **Recommended** or a **Not Recommended** standard. +4. **Recommended Standard:** This agenda involves all the draft features that have been accepted as a **Recommended Standard**. The outcome of this agenda is to classify whether a Recommended Standard can be classified as a **Required Standard**. +5. **Final Decision and Commit Approvals**: This is the final agenda of the meeting and contains a list of commits that have to be merged to the various branches. + +The duration of the working group meetings can be set by the Working Group Administrator. In case all proposals are not reviewed within the meeting, the WG Admin can propose a second meeting during the week to complete the discussion, + + +# Change Tracking and Management + +**GitHub** is the medium of record for all spec designs, use cases, and so on. + +All the specification documents are present on the official beckn protocol Github account [here](https://github.com/beckn). + + +## Sources of Truth + +1. The **protocol-specifications** repository is the source of truth for the core transaction API specification. +2. The **registry** repository is the source of truth for implementing the registry infrastructure +3. The **specification-files** repository is the source of truth for all human readable specification files + + +## Branch Structure + +At any given time, there should be _at most_ 4 working branches. The branches would exist if implementation has started on them. For example, assume a current version of **0.9.2** in the protocol-specifications repository. + +1. **master** - Current stable version. No PRs should be accepted directly to modify the specification. PRs against supporting files can be accepted. +2. **core-0.9.3-draft** - The next PATCH version of the specification. This should include non-breaking changes such as typo fixes, document fixes, wording clarifications. +3. **core-0.10.0-draft** - The next MINOR version of the specification. This would include backward compatible changes to the specification like attributes to existing schema. +4. **core-1.0.0-draft** - The next MAJOR version of the specification. + +The master branch shall remain the current, released beckn protocol specification. The will describe and link the working branch(es) on the default README.md on main. + +Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal. + +Use labels for the workflow of specification changes. Examples of labels are _proposed_, _draft-*_, _recommended_, _required_-, _not-recommended_, _review_ (candidate for upcoming WG meeting), _rejected_, and _needs-approval_. These labels must be assigned by WG members. Style is lowercase with dashes in place of spaces. + +An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change. + +A PR will be used to describe the _proposed_ solution and linked to the original issue. + +Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel. + +When the work branch is ready and approved, the branch will be merged to main. + + +## Reviewing Pull Requests + +Any Pull Request must have an associated Issue. If an Issue is not present, the reviewer must post a comment on the PR comment section asking the contributor to Raise an Issue and link the PR to it. If an Issue is not raised within 24 hours, the PR should be considered as rejected and must be closed by the reviewer with the comment _“Closing this due to unlinked Issue”_ + + +## Managing Conflicts + +If a Pull Request causes a merge conflict, the reviewer should respond with a comment “Merge conflicts present, kindly resolve and re-submit PR”. If the merge conflict is not resolved within 24 hours, the PR should be considered as rejected and must be closed by the reviewer with the comment “_Closing this due to unresolved merge conflicts_” + + +# Release Process + +A release requires a vote on the release notes by CWG members within the voting period. Major or minor release voting periods will be announced by the CWG admin in the Slack channel and noted on the calendar at least 6 days in advance. During this time, CWG members who have not yet voted must note their approval on the GitHub pull request for the release notes. Patch releases must happen at the first CWG meeting of a calendar month. The CWG admin is responsible for coordinating the actual merge to main with marketing support, if any. + +* Patch-level releases require majority approval by WG members. (Max voting period 3 days) +* Minor: requires approval by 66% of WG members. (Max voting period 7 days) +* Major: requires approval by 66% of WG members. (Max voting period 14 days) + +The above policies apply to the Core Working Group. However, a WG Admin may override the majority and voting period depending on the area and size of the group. + + +# Transparency + +The process should be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. General discussions should happen on the GitHub issues for this project. + + +# Participation + +While governance of the specification is the role of the CWG, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. diff --git a/docs/mobility-core/api/core-0.9.x-lts/LICENSE.md b/docs/mobility-core/api/core-0.9.x-lts/LICENSE.md new file mode 100644 index 0000000..92d3497 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/LICENSE.md @@ -0,0 +1,157 @@ +## creative commons + +# Attribution-NoDerivatives 4.0 International + +Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. + +### Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses. + +* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors). + +* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). + +## Creative Commons Attribution-NoDerivatives 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NoDerivatives 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. + +### Section 1 – Definitions. + +a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. + +b. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. + +c. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. + +d. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. + +e. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. + +f. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. + +g. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. + +h. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. + +i. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. + +j. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. + +### Section 2 – Scope. + +a. ___License grant.___ + + 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: + + A. reproduce and Share the Licensed Material, in whole or in part; and + + B. produce and reproduce, but not Share, Adapted Material. + + 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + + 3. __Term.__ The term of this Public License is specified in Section 6(a). + + 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + + 5. __Downstream recipients.__ + + A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. + + B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. + + 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + +b. ___Other rights.___ + + 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this Public License. + + 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. + +### Section 3 – License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the following conditions. + +a. ___Attribution.___ + + 1. If You Share the Licensed Material, You must: + + A. retain the following if it is supplied by the Licensor with the Licensed Material: + + i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of warranties; + + v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + + B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and + + C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. + + For the avoidance of doubt, You do not have permission under this Public License to Share Adapted Material. + + 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. + + 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. + +### Section 4 – Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: + +a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database, provided You do not Share Adapted Material; + +b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and + +c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights. + +### Section 5 – Disclaimer of Warranties and Limitation of Liability. + +a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__ + +b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__ + +c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. + +### Section 6 – Term and Termination. + +a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically. + +b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. + +c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. + +d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License. + +### Section 7 – Other Terms and Conditions. + +a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed. + +b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License. + +### Section 8 – Interpretation. + +a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License. + +b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions. + +c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor. + +d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. + +> Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. +> +> Creative Commons may be contacted at creativecommons.org diff --git a/docs/mobility-core/api/core-0.9.x-lts/MAINTAINERS.md b/docs/mobility-core/api/core-0.9.x-lts/MAINTAINERS.md new file mode 100644 index 0000000..b2830c8 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/MAINTAINERS.md @@ -0,0 +1,11 @@ +# Ravi Prakash +* __Email__ : ravi@becknfoundation.org +* __Github__ : [core-wg-admin](https://github.com/core-wg-admin) + +# Pramod Varma +* __Email__ : pramod@ekstep.org +* __Github__ : [pramodkvarma](https://github.com/pramodkvarma) + +# Nirmal Rajeevan +* __Email__ : nirmal@framewirk.com +* __Github__ : [techframewirk](https://github.com/techframewirk) diff --git a/docs/mobility-core/api/core-0.9.x-lts/README.md b/docs/mobility-core/api/core-0.9.x-lts/README.md new file mode 100644 index 0000000..fefe5b9 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/README.md @@ -0,0 +1,106 @@ +--- +title: "Beckn Protocol - Core" +metaTitle: "Beckn Protocol Transaction API Core" +metaDescription: "Domain agnostic transaction specification for e-commerce" +--- + +## Specification Evolution + +| Domain | Version | Release Date | Branch | +|-----------------------|-----------|-----------------------|--------| +| Core | 0.9.4 | 03 April, 2022 | 0.9.x-lts | +| Core | 1.0.0 | 31 Dec, 2022 | main | +| Core | 0.9.3 | 22 Dec, 2021 | main | +| Core | 0.9.2 | 27 July, 2021 | main | +| Core | 0.9.1 | 09 November, 2020 | main | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/fd154368c4670218ce6ad0fc8ee4ada5c401b485/final-mile-delivery/v0) | 0.8.3 | 10 October, 2020 | main | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/ba54b53aa341d6d0bc0f65633b0a33ff75b628ab/final-mile-delivery/v0) | 0.8.2 | 21 August, 2020 | main | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/029496c7e969fc322f654e19ee4ae7299c25fdb5/final-mile-delivery/v0) | 0.8.1 | 19 August, 2020 | main | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/v0) | 0.8.0 | 10 August, 2020 | main | +| [Core](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/v0) | 0.8.2 | 10 August, 2020 | main | +| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/archives/schema/0.7.0) | 0.7.0 | 06 July, 2020 | main | +| [Mobility](https://github.com/beckn/protocol-specifications/tree/master/mobility/schema/0.8.0) | 0.8.0 | 02 July, 2020 | main | +| Final Mile Delivery | 0.6.0 (depr) | 02 June, 2020 | main | +| [Food and Beverage](https://github.com/beckn/protocol-specifications/tree/master/food-and-beverage/schema/0.4.0) | 0.4.0 | 02 June, 2020 | main | +| Final Mile Delivery | 0.5.1 (depr) | 21 May, 2020 | main | +| [Core](https://github.com/beckn/protocol-specifications/tree/master/core/schema/0.8.0) | 0.8.0 | 21 May, 2020 | main | +| [Healthcare](https://developers.beckn.org/Healthcare) | 0.5.0 | 02 May, 2020 | main | +| Food and Beverage | 0.3.1 (depr) | 22 April, 2020 | main | +| [Core](https://github.com/beckn/protocol-specifications/tree/master/core/schema/0.7.1) | 0.7.1 | 17 April, 2020 | main | +| [Mobility](https://github.com/beckn/protocol-specifications/tree/master/mobility/schema/0.7.1) | 0.7.1 | 09 December, 2019 | main | + +# Introduction + +**Beckn** is an open protocol that allows local businesses across any industry to be discovered and engaged by any beckn-enabled application. Beckn protocol helps businesses co-create solutions for the masses seamlessly, by combining services of any form or provider. + +**Beckn protocol** is a collection of open specifications consisting of protocol APIs, message formats, network design and reference architectures to allow any two entities to execute commercial transactions without being on the same platform. + +This server-to-server communication protocol allows any consumer facing online platform to discover and transact with any business with minimal implementation overhead. The server-to-server nature of the protocol allows rich user experiences to be built by bundling services from multiple independent platforms. + +Beckn protocol decouples the demand side digital infrastructure in the form of apps and other channels from the supply side service provisioning infrastructure. It does this by making integratedservices available not just on a single platform but potentially on any online consumer interface, (online maps, messaging, wallets, voice assistant apps and devices) that have mainstream adoption in a city. + +Beckn is a protocol, not a platform. It adopts a decentralized architecture that obviates the need for creating a centralised platform in order to integrate services from multiple providers simultaneously ensuring privacy and security by design by enabling secure, encrypted iteractions. + +## Beckn Protocol - Core Specification + +Beckn protocol - core specification defines a generic, abstracted API that when implemented allows domain-agnostic interoperable e-commerce transactions between a buyer and seller irrespective of which platform they are on. An analogy similar to this would be the case of SMTP specification that allows email communication between any two platforms that have implemented the same specification. + +The core specification defines APIs for the following events in e-commerce + +1. Discovery - This involves activities like platform discovery, catalog browsing, filtering and item viewing +2. Ordering - This involves activities like cart building, quote calculation, checkout & payment terms agreement, and ultimately order confirmation +3. Fulfillment - This involves all post-order-creation activities like tracking, order update, cancellation and status updates +4. Post-fulfillment - The involves all post-fulfillment activities like rating, feedback, support, returns and replacements + +## Packet Structure + +All communication using beckn protocol have the following packet structure + +| Field | Description | +|---------------|-----------------------------------------------------------------------------------------------| +| `context` | Contains header information that is used for packet switching, key lookup, and encryption | +| `message` | Contains transaction information that is visible only to the participants of a transaction | + +## Transport Protocol + +While beckn protocol it designed to be transport agnostic, it is conventional to use HTTP as the default transport protocol. Additional layers like security and trust can be layered on top of this protocol using exisiting standards like HTTPS and SSL. It is recommended that any platform implementing beckn protocol use HTTPS to secure its communication. + + +## Communication + +Communication on beckn enabled networks is server-to-server. Server-to-server means that communication between any two systems on a beckn network does not involve the client application. The client is free to render the data in whatever form chosen by the product. Secondly, all communication is asynchronous. Asynchronous API calls do not block (or wait) for the API call to return from the receiver server in the same session. Instead, an immediate acknowledgment is sent to the sender server in the same session and the actual response from the receiver server is in the form of a callback API call to the sender server. The above two features provide a remarkable advantage as all sorts of innovations are possible in the application layer due to the experience layer being unbundled from the session and presentation layer of the application. + +A beckn enabled network has multiple entities (CSF005) communicating with each other via standard protocol APIs. The following types of communication are possible. + +- BAP and BG +- BAP and BPP +- BG and BPP +- BAP and Registry +- BPP and Registry +- BG and Registry + +All API calls between any two entities on the beckn network are asynchronous. Meaning, an API call from a BAP server (sender) to a BPP server (receiver) does not expect an informational response from a BPP in the same session. The immediate response in the same session is merely an acknowledgment or ACK which basically means, “Hey, I have received your request and it looks okay during validation of the input. Let me call you back when I have the details you need”. The actual response is sent later in the form of a standard callback API which the sender is required to implement. + +## Communication Protocol Between 2 Entities +The sequence diagram of a typical beckn protocol API is shown in Figure 1. For example, let’s say X is the sender and Y is the receiver, and the API being called is search. + +In most cases, the sender will call the API first and the receiver will respond immediately with an ACK and close the session. After an arbitrary period of time (which is dependent on the processing of the message), the receiver will respond with an API callback to the sender. The name of the callback API is the name of the sender API with an “on_” prefix. For example, if the request API is called “search” then the associated callback API will be “on_search”. + +## Communication Protocol Via Beckn Gateway + +Most communication in a beckn enabled network involves two entities. But sometimes, an intermediate entity like a Beckn Gateway (BG) is involved. In those cases, the flow of communication should be as follows. + +If the address of the BPP is not specified in the `context` field of the request body, then the BAP should call the BG and the BG may broadcast this API to multiple BPPs. + +The BPPs immediately respond with ACKs. Soon after, the BPPs call the `on_search` API which is sent back to the BAP. + +Sometimes the BG may query a Registry via the `lookup` API to get the BPP addresses and then broadcast the message to the BPPs. + +The transaction via the BG is encrypted and the BG has no visibility into the transaction information contained in the `message` field and only uses the `context` header to perform BPP discovery and routing. + + +# Acknowledgments +The author would like to thank the following individuals for their contributions in creating the this document. (in alphabetical order): + +Pramod Varma, FIDE +Sujith Nair, FIDE diff --git a/docs/mobility-core/api/core-0.9.x-lts/WORKING-GROUPS.md b/docs/mobility-core/api/core-0.9.x-lts/WORKING-GROUPS.md new file mode 100644 index 0000000..4f185ca --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/WORKING-GROUPS.md @@ -0,0 +1,39 @@ +# Core Working Group +* [Ravi Prakash](#TODO) +* [Pramod Varma](#TODO) +* [Sujith Nair](#TODO) +* [Nirmal Rajeevan](#TODO) +* [Venkataraman Mahadevan](#TODO) +* [Paul Kapustin](#TODO) + +# Mobility Working Group +* [Sujith Nair](#TODO) +* [Ravi Prakash](#TODO) +* [Srikanth Chunduri](#TODO) +* [Nirmal Rajeevan](#TODO) +* [Nikith Shetty](#TODO) +* [Paul Kapustin](#TODO) +* [Oleg Romashin](#TODO) + +# Retail Working Group +* [Venkatraman Mahadevan](#TODO) +* [Thejesh GN](#TODO) +* [Ashok Ayengar](#TODO) +* [Akshay Mathur](#TODO) + +# Logistics Working Group +* [Oleg Romashin](#TODO) +* [Paul Kapustin](#TODO) +* [Nikith Shetty](#TODO) + +# Infrastructure Working Group +* [Dhiraj Patorkar](#TODO) +* [Devendra Rane](#TODO) +* [Sujeet Suryavanshi](#TODO) +* [Nikith Shetty](#TODO) +* [Dharmesh Bajpai](#TODO) + +# Network Security Working Group +* [Sasi Kumar Ganesan](#TODO) +* [Venkataraman Mahadevan](#TODO) +* [Ravi Prakash](#TODO) diff --git a/docs/mobility-core/api/core-0.9.x-lts/core/v0/README.md b/docs/mobility-core/api/core-0.9.x-lts/core/v0/README.md new file mode 100644 index 0000000..a533972 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/core/v0/README.md @@ -0,0 +1,101 @@ +# Beckn Protocol API Specification + +This folder contains the Core API specification for Beckn Protocol. It defines interoperable API endpoints for discovery, order, fulfillment and post-fulfillment actions performed between a producer and a consumer. To improve performance and scalability, some Meta APIs are also specified. All these APIs are stateless and asynchronous. + +The current format for representing these endpoints is [Open API 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md) + +# Supported Actions + +## Discovery Actions + +### search +This action describes how a BAP can search for products and services. + +### on_search +This action describes how a BPP can publish the catalogs of its providers. + +## Order Actions + +### select +This action describes how a BAP can request a quote from a BPP + +### on_select +This action describes how a BPP can provide a quote to a BAP + +### init +This action describes how a BAP can request the final payment terms from a BPP + +### on_init +This action describes how a BPP can provide the final payment terms to a BAP + +### confirm +This action describes how a BAP can request the BPP to confirm the transaction + +### on_confirm +This action describes how a BPP can return a confirmed transaction + +## Fulfillment Actions + +### status +This action describes how a BAP can request the latest status of a transaction + +### on_status +This action describes how a BPP can return the latest status of a transaction + +### track +This action describes how a BAP can request tracking information of an order + +### on_track +This action describes how a BPP can return the tracking information of an order + +### update +This action describes how a BAP can request the BPP to update an active order + +### on_update +This action describes how a BPP can return an updated order + +### cancel +This action describes how a BAP can request the BPP to cancel a transaction + +### on_cancel +This action describes how a BPP can return a cancelled order + +## Post-fulfillment Actions + +### support +This action describes how a BAP can request support information for a transaction + +### on_support +This action describes how a BPP can return support information for a transaction + +### rating +This action describes how a BAP can provide rating for a Rateable Entity of a BPP + +### on_rating +This action describes how a BPP can acknowledge the rating provided by a BAP for a Rateable Entity of a BPP + +## Meta Actions + +### get_rating_categories +This action describes how a BAP requests a BPP to provide all the Rateable Entities + +### rating_categories +This action describes how a BPP returns all the Rateable Entities to a BAP + +### get_cancellation_reasons +This action describes how a BAP requests a BPP to provide a list of cancellation reasons + +### cancellation_reasons +This action describes how a BPP returns the list of cancellation reasons to a BAP + +### get_feedback_categories +This action describes how a BAP requests a BPP to provide a list of categories for which feedback can be given + +### feedback_categories +This action describes how a BPP returns the list of categories for which feedback can be given + +### get_feedback_form +This action describes how a BAP requests a BPP to provide a feedback form for a particular rating category and value + +### feedback_form +This action describes how a BPP returns a feedback form for a particular rating category and value diff --git a/docs/mobility-core/api/core-0.9.x-lts/core/v0/api/core.yaml b/docs/mobility-core/api/core-0.9.x-lts/core/v0/api/core.yaml new file mode 100644 index 0000000..f9b7da2 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/core/v0/api/core.yaml @@ -0,0 +1,2429 @@ +openapi: 3.0.0 +info: + title: Beckn Core API + description: Beckn Core API specification + version: 0.9.4 +security: + - SubscriberAuth: [] + - GatewaySubscriberAuth: [] + - GatewaySubscriberAuthNew: [] +paths: + /search: + post: + tags: + - Beckn Provider Platform (BPP) + - Beckn Gateway (BG) + description: Search for services by intent + requestBody: + description: BAP searches for services + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + intent: + $ref: '#/components/schemas/Intent' + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /select: + post: + tags: + - Beckn Provider Platform (BPP) + description: Select items from the catalog and build your order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /init: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /confirm: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /status: + post: + tags: + - Beckn Provider Platform (BPP) + description: Fetch the latest order object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + required: + - order_id + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /track: + post: + tags: + - Beckn Provider Platform (BPP) + description: Track an active order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + callback_url: + type: string + format: uri + required: + - order_id + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /cancel: + post: + tags: + - Beckn Provider Platform (BPP) + description: Cancel an order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + cancellation_reason_id: + $ref: '#/components/schemas/Option/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + required: + - order_id + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /update: + post: + tags: + - Beckn Provider Platform (BPP) + description: Remove object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + update_target: + description: 'Comma separated values of order objects being updated. For example: ```"update_target":"item,billing,fulfillment"```' + type: string + order: + $ref: '#/components/schemas/Order' + required: + - update_target + - order + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /rating: + post: + tags: + - Beckn Provider Platform (BPP) + description: Provide feedback on a service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + $ref: '#/components/schemas/Rating' + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /support: + post: + tags: + - Beckn Provider Platform (BPP) + description: Contact support + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + ref_id: + type: string + description: ID of the element for which support is needed + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_search: + post: + tags: + - Beckn App Platform (BAP) + - Beckn Gateway (BG) + description: Send catalog + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + catalog: + $ref: '#/components/schemas/Catalog' + required: + - catalog + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - context + /on_select: + post: + tags: + - Beckn App Platform (BAP) + description: Send draft order object with quoted price for selected items + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_init: + post: + tags: + - Beckn App Platform (BAP) + description: Send order object with payment details updated + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_confirm: + post: + tags: + - Beckn App Platform (BAP) + description: Send active order object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_track: + post: + tags: + - Beckn App Platform (BAP) + description: Send tracking details of an active order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + tracking: + $ref: '#/components/schemas/Tracking' + required: + - tracking + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_cancel: + post: + tags: + - Beckn App Platform (BAP) + description: Send cancellation request_id with reasons list in case of cancellation request. Else send cancelled order object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_update: + post: + tags: + - Beckn App Platform (BAP) + description: Returns updated service with updated runtime object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_status: + post: + tags: + - Beckn App Platform (BAP) + description: Fetch the status of a Service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_rating: + post: + tags: + - Beckn App Platform (BAP) + description: Provide feedback on a service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + $ref: '#/components/schemas/RatingAck' + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_support: + post: + tags: + - Beckn App Platform (BAP) + description: Contact Support + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + phone: + type: string + format: phone + email: + type: string + format: email + uri: + type: string + format: uri + error: + $ref: '#/components/schemas/Error' + required: + - context + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_cancellation_reasons: + post: + tags: + - BPP Meta APIs + description: Get cancellation reasons from the BPP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /cancellation_reasons: + post: + tags: + - BAP Meta APIs + description: Get cancellation reasons from the BPP + requestBody: + description: List of cancellation reasons + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + cancellation_reasons: + type: array + items: + $ref: '#/components/schemas/Option' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_return_reasons: + post: + tags: + - BPP Meta APIs + description: Get return reasons from the BPP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /return_reasons: + post: + tags: + - BAP Meta APIs + description: Get return reasons from the BPP + requestBody: + description: List of return reasons + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + return_reasons: + type: array + items: + $ref: '#/components/schemas/Option' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_rating_categories: + post: + tags: + - BPP Meta APIs + description: Get a list of categories that can be rated by the BAP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /rating_categories: + post: + tags: + - BAP Meta APIs + description: Get a list of categories that can be rated by the BAP + requestBody: + description: Array of categories which can be rated + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + rating_categories: + type: array + items: + $ref: '#/components/schemas/Rating/properties/rating_category' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_feedback_categories: + post: + tags: + - BPP Meta APIs + description: Get a list of categories for which feedback can be given by the BAP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /feedback_categories: + post: + tags: + - BAP Meta APIs + description: Get a list of categories for which feedback can be given by the BAP + requestBody: + description: Array of categories for which feedback can be given by the BAP + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + feedback_categories: + type: array + items: + $ref: '#/components/schemas/Rating/properties/rating_category' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_feedback_form: + post: + tags: + - BPP Meta APIs + description: Request a feedback form from the BPP + requestBody: + description: The rating value and category is sent by the BAP + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + rating_value: + $ref: '#/components/schemas/Rating/properties/value' + rating_category: + $ref: '#/components/schemas/Rating/properties/rating_category' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /feedback_form: + post: + tags: + - BAP Meta APIs + description: Get a feedback form from the BPP + requestBody: + description: Feedback form sent by the BPP + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + $ref: '#/components/schemas/Feedback' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using BAP or BPP subscriber''s signing public key.

Format:

Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(BLAKE-512(signing string))"' + GatewaySubscriberAuth: + type: apiKey + in: header + name: Proxy-Authorization + description: 'Signature of message body + BAP/BPP''s Authorization header using BG''s signing public key. Format:

Proxy-Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(BLAKE-512(signing string))"

Note:This header will be deprecated soon and will no longer be supported in future releases. New implementors are requested to use the X-Gateway-Authorization header. Existing implementations are requested to migrate their header to the new header. The deprecation date will be set after discussion as per the standard specification governance process.

' + GatewaySubscriberAuthNew: + type: apiKey + in: header + name: X-Gateway-Authorization + description: 'Signature of message body + BAP/BPP''s Authorization header using BG''s signing public key. Format:

X-Gateway-Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(BLAKE-512(signing string))"' + schemas: + Ack: + description: Describes the ACK response + type: object + properties: + status: + type: string + description: Describe the status of the ACK response. If schema validation passes, status is ACK else it is NACK + enum: + - ACK + - NACK + required: + - status + AddOn: + description: Describes an add-on + type: object + properties: + id: + type: string + description: 'ID of the add-on. This follows the syntax {item.id}/add-on/{add-on unique id} for item specific add-on OR ' + descriptor: + $ref: '#/components/schemas/Descriptor' + price: + $ref: '#/components/schemas/Price' + Address: + description: Describes an address + type: object + properties: + door: + type: string + description: Door / Shop number of the address + name: + type: string + description: Name of address if applicable. Example, shop name + building: + type: string + description: Name of the building or block + street: + type: string + description: Street name or number + locality: + type: string + description: Name of the locality, apartments + ward: + type: string + description: Name or number of the ward if applicable + city: + type: string + description: City name + state: + type: string + description: State name + country: + type: string + description: Country name + area_code: + type: string + description: Area code. This can be Pincode, ZIP code or any equivalent + Agent: + description: Describes an order executor + allOf: + - $ref: '#/components/schemas/Person' + - $ref: '#/components/schemas/Contact' + - type: object + properties: + rateable: + $ref: '#/components/schemas/Rateable' + Authorization: + description: Describes an authorization mechanism + type: object + properties: + type: + type: string + description: Type of authorization mechanism used + token: + type: string + description: Token used for authorization + valid_from: + type: string + format: date-time + description: Timestamp in RFC3339 format from which token is valid + valid_to: + type: string + format: date-time + description: Timestamp in RFC3339 format until which token is valid + status: + type: string + description: Status of the token + Billing: + description: Describes a billing event + type: object + properties: + name: + description: Personal details of the customer needed for billing. + type: string + organization: + $ref: '#/components/schemas/Organization' + address: + $ref: '#/components/schemas/Address' + email: + type: string + format: email + phone: + type: string + time: + $ref: '#/components/schemas/Time' + tax_number: + type: string + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + required: + - name + - phone + Cancellation: + description: Describes the ACK response + type: object + properties: + type: + type: string + enum: + - full + - partial + ref_id: + type: string + policies: + type: array + items: + $ref: '#/components/schemas/Policy' + time: + type: string + format: date-time + cancelled_by: + type: string + reasons: + $ref: '#/components/schemas/Option' + selected_reason: + type: object + properties: + id: + $ref: '#/components/schemas/Option/properties/id' + additional_description: + $ref: '#/components/schemas/Descriptor' + Catalog: + description: Describes a BPP catalog + type: object + properties: + bpp/descriptor: + $ref: '#/components/schemas/Descriptor' + bpp/categories: + type: array + items: + $ref: '#/components/schemas/Category' + bpp/fulfillments: + type: array + items: + $ref: '#/components/schemas/Fulfillment' + bpp/payments: + type: array + items: + $ref: '#/components/schemas/Payment' + bpp/offers: + type: array + items: + $ref: '#/components/schemas/Offer' + bpp/providers: + type: array + items: + $ref: '#/components/schemas/Provider' + exp: + type: string + description: Time after which catalog has to be refreshed + format: date-time + Category: + description: Describes a category + type: object + properties: + id: + type: string + description: Unique id of the category + parent_category_id: + $ref: '#/components/schemas/Category/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + time: + $ref: '#/components/schemas/Time' + tags: + $ref: '#/components/schemas/Tags' + Circle: + description: Describes a circular area on the map + type: object + properties: + gps: + $ref: '#/components/schemas/Gps' + radius: + $ref: '#/components/schemas/Scalar' + required: + - gps + - radius + City: + description: Describes a city + type: object + properties: + name: + type: string + description: Name of the city + code: + type: string + description: City code + Contact: + type: object + properties: + phone: + type: string + email: + type: string + tags: + $ref: '#/components/schemas/Tags' + Context: + description: Describes a beckn message context + type: object + properties: + domain: + $ref: '#/components/schemas/Domain' + country: + $ref: '#/components/schemas/Country/properties/code' + city: + $ref: '#/components/schemas/City/properties/code' + action: + type: string + description: Defines the Beckn API call. Any actions other than the enumerated actions are not supported by Beckn Protocol + enum: + - search + - select + - init + - confirm + - update + - status + - track + - cancel + - rating + - support + - on_search + - on_select + - on_init + - on_confirm + - on_update + - on_status + - on_track + - on_cancel + - on_rating + - on_support + core_version: + type: string + description: Version of Beckn core API specification being used + bap_id: + type: string + format: uri + description: Unique id of the BAP. By default it is the fully qualified domain name of the BAP + bap_uri: + type: string + format: uri + description: URI of the BAP for accepting callbacks. Must have the same domain name as the bap_id + bpp_id: + type: string + format: uri + description: Unique id of the BPP. By default it is the fully qualified domain name of the BPP + bpp_uri: + type: string + format: uri + description: URI of the BPP. Must have the same domain name as the bap_id + transaction_id: + type: string + description: This is a unique value which persists across all API calls from search through confirm + message_id: + type: string + description: This is a unique value which persists during a request / callback cycle + timestamp: + type: string + format: date-time + description: Time of request generation in RFC3339 format + key: + type: string + description: The encryption public key of the sender + ttl: + type: string + description: The duration in ISO8601 format after timestamp for which this message holds valid + max_callbacks: + type: integer + description: The maximum number of callbacks the BAP expects from the BPP. If set to zero, then BAP is not expecting a callback. If set to -1 the BAP can expect any number of callbacks. + default: 1 + required: + - domain + - action + - country + - city + - core_version + - transaction_id + - message_id + - bap_id + - bap_uri + - timestamp + Country: + description: Describes a country. + type: object + properties: + name: + type: string + description: Name of the country + code: + type: string + description: Country code as per ISO 3166-1 and ISO 3166-2 format + DecimalValue: + description: Describes a decimal value + type: string + pattern: '[+-]?([0-9]*[.])?[0-9]+' + Descriptor: + description: Describes the description of a real-world object. + type: object + properties: + name: + type: string + code: + type: string + symbol: + type: string + short_desc: + type: string + long_desc: + type: string + images: + type: array + items: + $ref: '#/components/schemas/Image' + audio: + type: string + format: uri + 3d_render: + type: string + format: uri + Dimensions: + description: Describes the dimensions of a real-world object + type: object + properties: + length: + $ref: '#/components/schemas/Scalar' + breadth: + $ref: '#/components/schemas/Scalar' + height: + $ref: '#/components/schemas/Scalar' + Document: + description: Describes a document which can be sent as a url + type: object + properties: + url: + type: string + format: uri + label: + type: string + Domain: + description: Describes the domain of an object + type: string + Duration: + description: Describes duration as per ISO8601 format + type: string + Error: + description: Describes an error object + type: object + properties: + type: + type: string + enum: + - CONTEXT-ERROR + - CORE-ERROR + - DOMAIN-ERROR + - POLICY-ERROR + - JSON-SCHEMA-ERROR + code: + type: string + description: Beckn specific error code. For full list of error codes, refer to error_codes.md in the root folder of this repo + path: + type: string + description: Path to json schema generating the error. Used only during json schema validation errors + message: + type: string + description: Human readable message describing the error + required: + - type + - code + Feedback: + description: Feedback for a service + type: object + properties: + feedback_form: + $ref: '#/components/schemas/FeedbackForm' + feedback_url: + $ref: '#/components/schemas/FeedbackUrl' + FeedbackForm: + description: Describes a feedback form that a BPP can send to get feedback from the BAP + type: array + items: + $ref: '#/components/schemas/FeedbackFormElement' + FeedbackFormElement: + description: An element in the feedback form. It can be question or an answer to the question. + type: object + properties: + id: + type: string + parent_id: + $ref: '#/components/schemas/FeedbackFormElement/properties/id' + question: + description: Specifies the question to which the answer options will be contained in the child FeedbackFormElements + type: string + answer: + description: Specifies an answer option to which the question will be in the FeedbackFormElement specified in parent_id + type: string + answer_type: + description: Specifies how the answer option should be rendered. + type: string + enum: + - radio + - checkbox + - text + FeedbackUrl: + description: Describes how a feedback URL will be sent by the BPP + type: object + properties: + url: + description: feedback URL sent by the BPP + type: string + format: uri + tl_method: + type: string + enum: + - http/get + - http/post + params: + type: object + properties: + feedback_id: + type: string + description: This value will be placed in the the $feedback_id url param in case of http/get and in the requestBody http/post requests + additionalProperties: + type: string + required: + - feedback_id + Fulfillment: + description: Describes how a single product/service will be rendered/fulfilled to the end customer + type: object + properties: + id: + type: string + description: Unique reference ID to the fulfillment of an order + type: + type: string + description: This describes the type of fulfillment + provider_id: + $ref: '#/components/schemas/Provider/properties/id' + rating: + $ref: '#/components/schemas/Rating/properties/value' + state: + $ref: '#/components/schemas/State' + tracking: + type: boolean + description: Indicates whether the fulfillment allows tracking + default: false + customer: + type: object + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + agent: + $ref: '#/components/schemas/Agent' + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + vehicle: + $ref: '#/components/schemas/Vehicle' + start: + description: Details on the start of fulfillment + type: object + properties: + location: + $ref: '#/components/schemas/Location' + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + authorization: + $ref: '#/components/schemas/Authorization' + end: + description: Details on the end of fulfillment + type: object + properties: + location: + $ref: '#/components/schemas/Location' + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + authorization: + $ref: '#/components/schemas/Authorization' + rateable: + $ref: '#/components/schemas/Rateable' + tags: + $ref: '#/components/schemas/Tags' + Gps: + description: Describes a gps coordinate + type: string + pattern: ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ + Image: + description: 'Image of an object.

A url based image will look like

```uri:http://path/to/image```

An image can also be sent as a data string. For example :

```data:js87y34ilhriuho84r3i4```' + type: string + Intent: + description: Intent of a user. Used for searching for services + type: object + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + provider: + $ref: '#/components/schemas/Provider' + fulfillment: + $ref: '#/components/schemas/Fulfillment' + payment: + $ref: '#/components/schemas/Payment' + category: + $ref: '#/components/schemas/Category' + offer: + $ref: '#/components/schemas/Offer' + item: + $ref: '#/components/schemas/Item' + tags: + $ref: '#/components/schemas/Tags' + ItemQuantity: + description: Describes count or amount of an item + type: object + properties: + allocated: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + available: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + maximum: + type: object + properties: + count: + type: integer + minimum: 1 + measure: + $ref: '#/components/schemas/Scalar' + minimum: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + selected: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + Item: + description: Describes an item. Allows for domain extension. + type: object + properties: + id: + description: This is the most unique identifier of a service item. An example of an Item ID could be the SKU of a product. + type: string + format: '#/components/schemas/Item/properties/id' + parent_item_id: + $ref: '#/components/schemas/Item/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + price: + $ref: '#/components/schemas/Price' + category_id: + $ref: '#/components/schemas/Category/properties/id' + fulfillment_id: + $ref: '#/components/schemas/Fulfillment/properties/id' + rating: + $ref: '#/components/schemas/Rating/properties/value' + location_id: + $ref: '#/components/schemas/Location/properties/id' + time: + $ref: '#/components/schemas/Time' + rateable: + $ref: '#/components/schemas/Rateable' + matched: + type: boolean + related: + type: boolean + recommended: + type: boolean + tags: + $ref: '#/components/schemas/Tags' + Language: + description: indicates language code. Beckn supports country codes as per ISO 639.2 standard + type: object + properties: + code: + type: string + Location: + description: Describes the location of a runtime object. + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + gps: + $ref: '#/components/schemas/Gps' + address: + $ref: '#/components/schemas/Address' + station_code: + type: string + city: + $ref: '#/components/schemas/City' + country: + $ref: '#/components/schemas/Country' + circle: + $ref: '#/components/schemas/Circle' + polygon: + type: string + 3dspace: + type: string + time: + $ref: '#/components/schemas/Time' + Name: + type: string + description: 'Describes the name of a person in format: ./{given_name}/{honorific_prefix}/{first_name}/{middle_name}/{last_name}/{honorific_suffix}' + pattern: ^\./[^/]+/[^/]*/[^/]*/[^/]*/[^/]*/[^/]*$ + Offer: + description: Describes an offer + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + location_ids: + type: array + items: + $ref: '#/components/schemas/Location/properties/id' + category_ids: + type: array + items: + $ref: '#/components/schemas/Category/properties/id' + item_ids: + type: array + items: + $ref: '#/components/schemas/Item/properties/id' + time: + $ref: '#/components/schemas/Time' + Operator: + description: Describes the agent of a service + allOf: + - $ref: '#/components/schemas/Person' + - properties: + experience: + type: object + properties: + label: + type: string + value: + type: string + unit: + type: string + Option: + description: Describes a selectable option + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + Order: + description: Describes the details of an order + type: object + properties: + id: + type: string + description: Hash of order object without id + state: + type: string + provider: + type: object + properties: + id: + $ref: '#/components/schemas/Provider/properties/id' + locations: + type: array + maxItems: 1 + items: + type: object + properties: + id: + $ref: '#/components/schemas/Location/properties/id' + required: + - id + items: + type: array + items: + allOf: + - $ref: '#/components/schemas/Item' + - properties: + quantity: + $ref: '#/components/schemas/ItemQuantity/properties/selected' + type: object + required: + - id + add_ons: + type: array + items: + type: object + properties: + id: + $ref: '#/components/schemas/AddOn/properties/id' + required: + - id + offers: + type: array + items: + type: object + properties: + id: + $ref: '#/components/schemas/Offer/properties/id' + required: + - id + documents: + type: array + items: + $ref: '#/components/schemas/Document' + billing: + $ref: '#/components/schemas/Billing' + fulfillment: + $ref: '#/components/schemas/Fulfillment' + quote: + $ref: '#/components/schemas/Quotation' + payment: + $ref: '#/components/schemas/Payment' + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + Organization: + description: Describes an organization + type: object + properties: + name: + type: string + cred: + type: string + Page: + description: Describes a page in a search result + type: object + properties: + id: + type: string + next_id: + type: string + Payment: + description: Describes a payment + type: object + properties: + uri: + type: string + description: 'A payment uri to be called by the BAP. If empty, then the payment is to be done offline. The details of payment should be present in the params object. If ```tl_method``` = http/get, then the payment details will be sent as url params. Two url param values, ```$transaction_id``` and ```$amount``` are mandatory. And example url would be : https://www.example.com/pay?txid=$transaction_id&amount=$amount&vpa=upiid&payee=shopez&billno=1234' + format: uri + tl_method: + type: string + enum: + - http/get + - http/post + params: + type: object + properties: + transaction_id: + type: string + description: This value will be placed in the the $transaction_id url param in case of http/get and in the requestBody http/post requests + transaction_status: + type: string + amount: + $ref: '#/components/schemas/Price/properties/value' + currency: + $ref: '#/components/schemas/Price/properties/currency' + additionalProperties: + type: string + required: + - currency + type: + type: string + enum: + - ON-ORDER + - PRE-FULFILLMENT + - ON-FULFILLMENT + - POST-FULFILLMENT + status: + type: string + enum: + - PAID + - NOT-PAID + time: + $ref: '#/components/schemas/Time' + Person: + description: Describes a person. + type: object + properties: + name: + $ref: '#/components/schemas/Name' + image: + $ref: '#/components/schemas/Image' + dob: + type: string + format: date + gender: + type: string + description: Gender of something, typically a Person, but possibly also fictional characters, animals, etc. While Male and Female may be used, text strings are also acceptable for people who do not identify as a binary gender + cred: + type: string + tags: + $ref: '#/components/schemas/Tags' + Policy: + description: Describes a policy. Allows for domain extension. + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + parent_policy_id: + $ref: '#/components/schemas/Policy/properties/id' + time: + $ref: '#/components/schemas/Time' + Price: + description: Describes the price of an item. Allows for domain extension. + type: object + properties: + currency: + type: string + value: + $ref: '#/components/schemas/DecimalValue' + estimated_value: + $ref: '#/components/schemas/DecimalValue' + computed_value: + $ref: '#/components/schemas/DecimalValue' + listed_value: + $ref: '#/components/schemas/DecimalValue' + offered_value: + $ref: '#/components/schemas/DecimalValue' + minimum_value: + $ref: '#/components/schemas/DecimalValue' + maximum_value: + $ref: '#/components/schemas/DecimalValue' + Provider: + description: Describes a service provider. This can be a restaurant, a hospital, a Store etc + type: object + properties: + id: + type: string + description: Id of the provider + descriptor: + $ref: '#/components/schemas/Descriptor' + category_id: + type: string + description: Category Id of the provider + rating: + $ref: '#/components/schemas/Rating/properties/value' + time: + $ref: '#/components/schemas/Time' + categories: + type: array + items: + $ref: '#/components/schemas/Category' + fulfillments: + type: array + items: + $ref: '#/components/schemas/Fulfillment' + payments: + type: array + items: + $ref: '#/components/schemas/Payment' + locations: + type: array + items: + allOf: + - $ref: '#/components/schemas/Location' + - type: object + properties: + rateable: + $ref: '#/components/schemas/Rateable' + offers: + type: array + items: + $ref: '#/components/schemas/Offer' + items: + type: array + items: + $ref: '#/components/schemas/Item' + exp: + type: string + description: Time after which catalog has to be refreshed + format: date-time + rateable: + $ref: '#/components/schemas/Rateable' + tags: + $ref: '#/components/schemas/Tags' + Quotation: + description: Describes a quote + type: object + properties: + price: + $ref: '#/components/schemas/Price' + breakup: + type: array + items: + type: object + properties: + title: + type: string + price: + $ref: '#/components/schemas/Price' + ttl: + $ref: '#/components/schemas/Duration' + Rateable: + description: If the entity can be rated or not + type: boolean + Rating: + description: Describes the rating of a person or an object. + type: object + properties: + rating_category: + description: Category of the object being rated + type: string + id: + description: Id of the object being rated + type: string + value: + description: Rating value given to the object + type: number + minimum: 0 + feedback_form: + $ref: '#/components/schemas/FeedbackForm' + feedback_id: + $ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id' + RatingAck: + type: object + properties: + feedback_ack: + description: If feedback has been recorded or not + type: boolean + rating_ack: + description: If rating has been recorded or not + type: boolean + Scalar: + description: An object representing a scalar quantity. + type: object + properties: + type: + type: string + enum: + - CONSTANT + - VARIABLE + value: + type: number + estimated_value: + type: number + computed_value: + type: number + range: + type: object + properties: + min: + type: number + max: + type: number + unit: + type: string + required: + - value + - unit + Schedule: + description: Describes a schedule + type: object + properties: + frequency: + $ref: '#/components/schemas/Duration' + holidays: + type: array + items: + type: string + format: date-time + times: + type: array + items: + type: string + format: date-time + State: + description: Describes a state + type: object + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + updated_at: + type: string + format: date-time + updated_by: + type: string + description: ID of entity which changed the state + Subscriber: + type: object + description: Any entity which wants to authenticate itself on a network. This can be a BAP, BPP, BG, BPPR or a BGR. + properties: + subscriber_id: + type: string + description: Registered domain name of the subscriber. Must have a valid SSL certificate issued by a Certificate Authority of the operating region + type: + type: string + enum: + - bap + - bpp + - bg + - bppr + - bgr + cb_url: + type: string + description: Callback URL of the subscriber. The Registry will call this URL's on_subscribe API to validate the subscriber\'s credentials + domain: + $ref: '#/components/schemas/Domain' + city: + $ref: '#/components/schemas/City/properties/code' + country: + $ref: '#/components/schemas/Country/properties/code' + signing_public_key: + type: string + description: Signing Public key of the subscriber.

Any subscriber platform (BAP, BPP, BG) who wants to transact on the network must digitally sign the ```requestBody``` using the corresponding private key of this public key and send it in the transport layer header. In case of ```HTTP``` it is the ```Authorization``` header.

The ```Authorization``` will be used to validate the signature of a BAP or BPP.

Furthermore, if an API call is being proxied or multicast by a Beckn Gateway, the BG must use it\'s signing key to digitally sign the ```requestBody``` using the corresponding private key of this public key and send it in the ```X-Gateway-Authorization``` header. + encryption_public_key: + type: string + description: Encryption public key of the BAP subscriber. Any BPP must encrypt the ```requestBody.message``` value of the ```on_search``` API using this public key. + status: + type: string + enum: + - INITIATED + - UNDER_SUBSCRIPTION + - SUBSCRIBED + - INVALID_SSL + - UNSUBSCRIBED + created: + type: string + description: Timestamp when a subscriber was added to the registry with status = INITIATED + format: date-time + updated: + type: string + format: date-time + expires: + type: string + description: Expiry timestamp in UTC derived from the ```lease_time``` of the subscriber + format: date-time + Support: + description: Customer support + type: object + properties: + type: + type: string + enum: + - order + - billing + - fulfillment + ref_id: + type: string + channels: + $ref: '#/components/schemas/Tags' + Tags: + description: A simple key-value store which is used to contain extended metadata. However, grouped tags can be created using the recommendations provided in docs/protocol-drafts/BECKN-The-Tags-Schema-Draft-01.md + additionalProperties: + type: string + Time: + description: Describes time in its various forms. It can be a single point in time; duration; or a structured timetable of operations + type: object + properties: + label: + type: string + timestamp: + type: string + format: date-time + duration: + $ref: '#/components/schemas/Duration' + range: + type: object + properties: + start: + type: string + format: date-time + end: + type: string + format: date-time + days: + type: string + description: comma separated values representing days of the week + schedule: + $ref: '#/components/schemas/Schedule' + TrackingData: + description: Describes tracking data object during live tracking of an order + $ref: '#/components/schemas/Location/properties/gps' + Tracking: + description: Describes the tracking info of an object + type: object + properties: + url: + type: string + format: uri + status: + type: string + enum: + - active + - inactive + Vehicle: + description: Describes the properties of a vehicle used in a mobility service + type: object + properties: + category: + type: string + capacity: + type: integer + make: + type: string + model: + type: string + size: + type: string + variant: + type: string + color: + type: string + energy_type: + type: string + registration: + type: string diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Async-Communication.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Async-Communication.png new file mode 100644 index 0000000..1cbd0e9 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Async-Communication.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-API-Sequence.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-API-Sequence.png new file mode 100644 index 0000000..67987c0 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-API-Sequence.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Contract-Infrastructure.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Contract-Infrastructure.png new file mode 100644 index 0000000..70376bb Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Contract-Infrastructure.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Contract.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Contract.png new file mode 100644 index 0000000..2faa858 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Contract.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-1.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-1.png new file mode 100644 index 0000000..abe5ff3 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-1.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-2.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-2.png new file mode 100644 index 0000000..fb6ae8b Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-2.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-3.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-3.png new file mode 100644 index 0000000..9426345 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-3.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-4.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-4.png new file mode 100644 index 0000000..44b95b6 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Payment-Settlement-Flow-4.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy API.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy API.png new file mode 100644 index 0000000..4f0204e Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy API.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Agreement Protocol.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Agreement Protocol.png new file mode 100644 index 0000000..2ad22c2 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Agreement Protocol.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Infrastructure Architecture.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Infrastructure Architecture.png new file mode 100644 index 0000000..5dba2aa Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Infrastructure Architecture.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Workflow.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Workflow.png new file mode 100644 index 0000000..aca536f Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy Workflow.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Agreement-Implementation-Architecture.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Agreement-Implementation-Architecture.png new file mode 100644 index 0000000..e3a3889 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Agreement-Implementation-Architecture.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Agreement-and-Adoption-Protocol.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Agreement-and-Adoption-Protocol.png new file mode 100644 index 0000000..c1bdaba Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Agreement-and-Adoption-Protocol.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Workflow-New.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Workflow-New.png new file mode 100644 index 0000000..b0d8237 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Policy-Workflow-New.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Search-Multicast-with-Reg.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Search-Multicast-with-Reg.png new file mode 100644 index 0000000..17e8bd9 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Search-Multicast-with-Reg.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Search-Multicast.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Search-Multicast.png new file mode 100644 index 0000000..70ac434 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Search-Multicast.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/images/Status.png b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Status.png new file mode 100644 index 0000000..0ac0a99 Binary files /dev/null and b/docs/mobility-core/api/core-0.9.x-lts/docs/images/Status.png differ diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/proposals/README.md b/docs/mobility-core/api/core-0.9.x-lts/docs/proposals/README.md new file mode 100644 index 0000000..1462309 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/proposals/README.md @@ -0,0 +1,5 @@ +# Proposals + +These documents contain all proposals submitted by the community to be included in beckn protocol specifications. The community is encouraged to submit as many proposals as possible to ensure a robust and interoperable protocol. + +After sufficient discussions, these documents may be selected for further review by the working groups as Protocol Drafts. \ No newline at end of file diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Beckn-Protocol-Communication-Draft-01.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Beckn-Protocol-Communication-Draft-01.md new file mode 100644 index 0000000..23a08ea --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Beckn-Protocol-Communication-Draft-01.md @@ -0,0 +1,87 @@ +# Beckn Protocol Communication + +## ID +BECKN-RFC-003 + +## Draft ID +Draft-01 + +## Title +Beckn Protocol Communication + +## Category +Communication + +## Status +Protocol Draft + +## Published on +December 10, 2021 + +## Expires on +December 10, 2021 or Date of publication of next draft which ever is earlier + +## License +CC-BY-ND + +## Authors +1. Ravi Prakash : ravi@becknfoundation.org + +## Reviewers +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + +# Abstract +Communication on beckn enabled networks is server-to-server. Server-to-server means that communication between any two systems on a beckn network does not involve the client application. The client is free to render the data in whatever form chosen by the product. Secondly, all communication is asynchronous. Asynchronous API calls do not block (or wait) for the API call to return from the receiver server in the same session. Instead, an immediate acknowledgment is sent to the sender server in the same session and the actual response from the receiver server is in the form of a callback API call to the sender server. The above two features provide a remarkable advantage as all sorts of innovations are possible in the application layer due to the experience layer being unbundled from the session and presentation layer of the application. + +# Introduction +A beckn enabled network has multiple entities communicating with each other via standard protocol APIs. The following types of communication are possible. + +1. BAP and BG +2. BAP and BPP +3. BG and BPP +4. BAP and Registry +5. BPP and Registry +6. BG and Registry + +All API calls between any two entities on the beckn network are asynchronous. Meaning, an API call from a BAP server (sender) to a BPP server (receiver) does not expect an informational response from a BPP in the same session. The immediate response in the same session is merely an acknowledgement or ACK which basically means, “_Hey, I have received your request and it looks okay during validation of the input. Let me call you back when I have the details you need_”. The actual response is sent later in the form of a standard callback API which the sender is required to implement. + +# Communication Protocol Between 2 Entities + +The sequence diagram of a typical beckn protocol API is shown in Figure 1. For example, let’s say X is the sender and Y is the receiver, and the API being called is **search.** + +In most cases, the sender will call the API first and the receiver will respond immediately with an ACK and close the session. After an arbitrary period of time (which is dependent on the processing of the message), the receiver will respond with an API callback to the sender. The name of the callback API is the name of the sender API with an “on_” prefix. For example, if the request API is called “**search**” then the associated callback API will be “**on_search**”. + +
+ +
Figure 1
+
+ +# Communication Protocol for Search Via Beckn Gateway + +Most communication in a beckn enabled network involves two entities. But sometimes, an intermediate entity like a Beckn Gateway (BG) is involved. In those cases, the flow of communication should be as follows. + +If the address of the BPP is not specified in the context of the API call, then the BAP should call the BG and the BG may multicast this API to multiple BPPs. +The BPPs synchronously respond with ACKs. The BPPs then asynchronously call the **on_search** API which is sent back to the BAP. + +
+ +
Figure 2:
+
+ +# Communication Protocol for Search Via Beckn Gateway with Registry Lookup + +Sometimes the BG may query a Registry via the **lookup** API to get the BPP addresses and then multicast the message to the BPPs. See Figure 3. +
+ +
Figure 3:Search with Registry Lookup
+
+ +# Communication Protocol during status updates + +During the status and on_status calls, the BAP first initiates the transaction by calling **status**. The BAP responds with an **on_status **API call to the BPP just like any other beckn API. However, in the case of the **status** API call, the BPP can asynchronously send multiple **on_status** calls to the BAP after the first call. The BAP does not have to poll the BPP to get an on_status callback. See Figure 4. + +
+ +
Figure 4
+
diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Layering-Network-Policy-Draft-01.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Layering-Network-Policy-Draft-01.md new file mode 100644 index 0000000..b8849dd --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Layering-Network-Policy-Draft-01.md @@ -0,0 +1,425 @@ +# Layering Network Policy on the Specification + +## ID: +BECKN-RFC-001 + +## Draft ID +Draft-01 + +## Title: +Layering Network Policy on the Specification + +## Category: +Network Policy + +## Status: +Protocol Draft + +## Published on: +December 10, 2021 + +## Expires on: +December 10, 2022 or Date of publication of next draft which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Ravi Prakash : ravi@becknfoundation.org + +## Reviewers: +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + +# Scope + +This document contains design principles and methodologies that should be used to configure beckn protocol specification for various sector-specific networks. This document is intended for the following audience. + +1. Anyone who is using beckn protocol specifications to design open commerce networks for a specific set of use cases + +# Prerequisites + +Readers of this document must: + +1. Have knowledge of the core protocol specification +2. Have knowledge of the Architecture of Open Commerce Networks instantiated using beckn protocol. +3. Have knowledge of Open API 3.0 Specification + + +# Context + +Beckn protocol is a set of specifications that enables any two platforms to perform commercial transactions by implementing an API with standard action calls and schema. These specifications are by-design generic and therefore, sector agnostic. However, to establish a smart contract between a BAP and a BPP, additional domain-specific information must sometimes be transmitted between the platforms. For example, a logistics network might have different allowed values for the types of fulfillments it supports like “HOME-DELIVERY” and “STORE-PICKUP” as opposed to an education network where the allowed values may be “TELE-CONSULTATION” or “PHYSICAL-CONSULTATION''. These values are not standardized in the core schema but rather exist as _policies_ framed by the architects of a beckn-enabled open commerce network. + +Similarly, a network might put a limit on the number of matched items that can be returned in a single catalog object. To maintain interoperability but also allow its configurability, beckn protocol specification governance restricts modification of the core schema and actions. However, to allow its adaptability, instead of forcing all specification users to adhere to the core specification and, beckn protocol governance allows creation of network-specific policies. These policies allow sector-agnostic rules and validation criteria to be published along with the specification based on recommendations and comments received from various ecosystem contributors and network participants implementing the protocol. These rules and policies must be layered on the core specification and published as a separate document that can be accessed by the network participants in a machine readable manner. + + +# Abstract + +Beckn Protocol is an abstracted but **highly configurable** specification. A network is an **instantiation** of the core protocol specification. However, to instantiate a network, additional policies must be layered via machine-readable configuration files. These configurations vary from network to network depending upon the use cases supported by them. These configurations allow sector-specific policies to be applied on a network _without_ changing the underlying core specification. This document defines a methodology to publish these network-specific policies as machine-readable documents that can be read by network participants to create API validation middleware. + + +# Terminology + + + +1. **Network :** In the context of beckn protocol, a network refers to an open commerce network formed by the instantiation of beckn protocol specification with a standard network policy +2. **Network Participant:** Any platform that has implemented beckn protocol specification and is part of an open commerce network +3. **Schema:** These are JSON Schema objects with properties as defined in +4. **Action:** These are specific events that occur during the lifecycle of a typical commerce transaction +5. **Network Policy**: These are specific rules that apply to the implementers of a network while developing the protocol API middleware + + +# Problem + +Given the Non-Derivative nature of the core specification, how can networks allow configurability of the core specification without disrupting global interoperability? + + +# Forces + +Beckn protocol governance allows highly specific configurations to the core specification via network policies. These policies must be designed not to modify the underlying schema itself but rather govern the values these schema properties are allowed to take like, + + + +1. Adding enumerations to core schema properties +2. Adding additional qualifiers like min / max and defaults +3. Adding sector-specific and region-specific standards to using regex patterns + + +# Expected Outcomes after reading this document + +After reading this document, the reader should be able to + + + +1. Understand how policies can be layered on the core specification +2. Understand how a machine-readable network-specific protocol can be published +3. Understand how such policies can be made available as an infrastructure on a network for dynamic network policy transmission and enforcement + + +# Network Policy as Code + +A network policy is a set of rules that must be published by the architects of beckn-enabled open commerce networks as a machine-readable specification to allow its participants to create protocol validation middleware in their implementations. This specification should **inherit** all the attributes of the core specification along with some additional constraints on the usage of the specification during network transactions. + + +## Inheritance and Polymorphism in Open API 3.0 + +The core specification currently exists in the form of an Open API Specification 3.0 document with some reserved modifications. To layer policy on the specification, beckn protocol governance allows layering of policies by way of configuration. This configuration is done on the core Open API document by using the inheritance and polymorphism feature of Open API Specification 3.0. Inheritance and polymorphism are terms used in Object Oriented Design and are applicable to beckn protocol specifications as well. To learn more about Inheritance and Polymorphism as a generic concept, click here. + +In Open API 3.0, inheritance and Polymorphism are enabled using the “allOf”, “oneOf” and “anyOf” keywords. + + +### The allOf keyword + +While implementing a protocol API, the data-model may have model schemas that share common properties. Instead of describing these properties for each schema repeatedly, it is possible to describe the schemas as a composition of the common property set and schema-specific properties. In OpenAPI version 3, we can do this with the allOf keyword[4] as shown in the example below + + +``` +components: + schemas: + Tags: + type: object + + CategoryTags: + allOf:# Combines the basic Tags model and the inline Category Tags model + - $ref: '#/components/schemas/Tags + - type: object + properties: + brand: + type: string + enum: + - brand + - purpose + - season +``` + + +As shown above, the **CategoryTags** schema introduces a property called “brand” that is extended from the otherwise generic **Tags** object in the core specification. + + +### The oneOf keyword + +This keyword allows the validator to validate a value against exactly one of the subschemas out of several schemas. + + +### The anyOf keyword + +This keyword allows the validator to validate a value against exactly one or more of the subschemas out of several schemas. + + +## Applying Network-Specific Policies using Open API 3.0 + + +### Adding enumerations, defaults and min / max values + +It is possible to add **enumerations**, **defaults**, **min/max** values to any schema. For example, a network may allow only **search** and **confirm** actions. Hence the `context.action` attribute will contain an enumeration of only `search / on_search` and `confirm / on_confirm` API calls as shown below. + + +``` +ContextPolicy1: + description: Describes the context policy of a message on this network + allOf: + - $ref: '#/components/schemas/Context' + - type: object + properties: + action: + type: string + description: Actions supported by this policy + enum: + - search + - confirm + - on_search + - on_confirm + core_version: + type: string + description: Specification versions supported by this policy + enum: + - '0.9.1' + - '0.9.2' + - '0.9.3-draft' + default: 0.9.2 + ttl: + type: string + description: TTL of the message + minimum: P0S + maximum: P1M +``` + + +Another example is related to the **Rating** schema + + +``` +Rating: + description: Describes the rating of a person or an object. + type: object + properties: + rating_category: + description: Category of the object being rated + type: string + id: + description: Id of the object being rated + type: string + value: + description: Rating value given to the object + type: number +``` + + +If a network policy requires rating to range between 1 and 10, it must create a Rating Policy schema that inherits the properties of the Core **Rating** Schema as shown below + + +``` +RatingPolicy1: + description: Describes the context policy of a message on this network + allOf: + - $ref: '#/components/schemas/Rating + - type: object + properties: + value: + type: number + minimum: 1 + maximum: 10 +``` + + + +### Adding alternative schemas + +Sometimes it is possible to have requests and responses that can be described by several alternative schemas. In OpenAPI 3.0, to describe such a model, we can use the oneOf or anyOf keywords. For example, while transmitting payment terms from BPP to the BAP via the **on_init** action, multiple payment endpoints can be sent in the _params_ property of the **Payment** schema as shown below. + + +``` +PaymentParams: + type: object + properties: + transaction_id: + type: string + transaction_status: + type: string + amount: + $ref: '#/components/schemas/Price/properties/value' + currency: + $ref: '#/components/schemas/Price/properties/currency' + required: + - currency + - amount + +PaymentParamsPolicy1: + allOf: + - $ref: '#/components/schemas/PaymentParams' + - type: object + properties: + anyOf: + - $ref: '#/components/schemas/BankTransfer' + - $ref: '#/components/schemas/UnifiedPaymentInterface' + - $ref: '#/components/schemas/PaymentGatewayParams' + +BankTransfer: + type: object + properties: + account_name: + type: string + account_id: + type: string + ifsc: + type: string + +UnifiedPaymentInterface: + type: object + properties: + vpa: + type: string + +PaymentGatewayParams: + type: object + properties: + merchant_id: + type: string + redirect_uri: + type: string +``` + + + +### Adding required fields + +It is also possible to add **required** properties to any attribute. For example, in the domain of mobility, the origin location’s gps coordinate must be a required field. + + +``` +FulfillmentPolicy1: + description: Describes how a mobility service should be fulfilled + type: object + properties: + id: + type: string + description: Unique reference ID to the fulfillment of an order + type: + type: string + description: This describes the type of fulfillment + provider_id: + $ref: '#/components/schemas/Provider/properties/id' + rating: + $ref: '#/components/schemas/Rating/properties/value' + state: + $ref: '#/components/schemas/State' + tracking: + type: boolean + description: Indicates whether the fulfillment allows tracking + default: false + customer: + type: object + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + agent: + $ref: '#/components/schemas/Agent' + vehicle: + $ref: '#/components/schemas/Vehicle' + start: + description: Details on the start of fulfillment + type: object + properties: + location: + allOf: + - $ref: '#/components/schemas/Location' + - required: + - gps + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + end: + description: Details on the end of fulfillment + type: object + properties: + location: + $ref: '#/components/schemas/Location' + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + rateable: + $ref: '#/components/schemas/Rateable' + tags: + $ref: '#/components/schemas/Tags' + +``` + + + +### Adding standards and formats + +A network in India might choose to use the NIC 2004, Industry Classification Codes to identify the Industry Sector of a network via the **Context.domain** attribute as shown below + + +``` +Domain: + description: Describes the industry domain of an object in the country of India. + type: string + pattern: "^nic2004:(52110|52114)" +``` + + + + The above pattern indicates that the network allows only Retail and Delivery transactions + +Adding domain-specific, region-specific, technology-specific attributes or schema to the **Tags** object to accommodate extensions that might get abstracted and merged into core specifications in future releases. For example, a retail network should publish a list of allowed tags for various schemas used by a network. + + +``` +Tags: + description: Describes a tag. This is a simple key-value store which is used to contain extended metadata + additionalProperties: + type: string +``` + + +All these extensions must be published as part of a separate document called **Network Implementation Policy** + +It is recommended that this document be published along with the API specification of that network using the **externalDocs** attribute as defined by Open API Specification 3.0 + +More Examples: + +The specifications allow a network to define a master list of Rating Categories that can be used by NPs. So when creating the API specification of a network, the **rating_categories ** API must define all the allowed rating categories as enums as shown below. + + +``` +Rating: + description: Describes the rating of an object. + type: object + properties: + rating_category: + description: Category of the object being rated + type: string + enum: + - Order + - Fulfillment + - Item + - Provider + - anything else + id: + description: Id of the object being rated + type: string + + value: + description: Rating value given to the object + type: number + minimum: 0 + feedback_form: + $ref: '#/components/schemas/FeedbackForm' + required: false + feedback_id: + $ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id' + required: false +``` diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Payments-On-Beckn-Enabled-Networks.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Payments-On-Beckn-Enabled-Networks.md new file mode 100644 index 0000000..87e3039 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Payments-On-Beckn-Enabled-Networks.md @@ -0,0 +1,189 @@ +# Payments on Beckn-Enabled Networks + + +## ID: +BECKN-RFC-002 + +## Draft ID +Draft-01 + +## Title: +Payments on Beckn-Enabled Networks + +## Category: +Payments + +## Status: +Protocol Draft + +## Published on: +December 10, 2021 + +## Expires on: +April 05, 2022 or Date of publication of next draft which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Ravi Prakash : ravi@becknfoundation.org + +## Reviewers: +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + +# Introduction +In beckn-enabled networks, payments are expected to be settled outside the network. Meaning, the implementers of beckn-enabled applications are expected to use existing payment infrastructures in their region(s) of operation to collect, process and settle payments. Since payments is a highly regulated industry across the world, different geo-political regions may choose different standards and modalities to enable digital payments. Therefore, it is left to the implementer to templatize such region-specific payment modalities and dynamically enable them on the respective user applications of both the payer and payee, based on their respective geo-political locations. + + +*it is left to the implementer to templatize such region-specific payment modalities and dynamically enable them on the respective user applications of both the payer and payee, based on their respective geo-political locations...* +== + +# Payment Infrastructure on a Beckn-enabled Network + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Contract-Infrastructure.png) + +# Payment Contract Agreement + +On the protocol layer, only the terms of payment and the proof of payment are exchanged between the BAP and the BPP. Together, the exchange of terms; and the agreement of those terms between the payer and the payee are together known as a **Payment Contract Agreement**. + +It is important to note that beckn protocol only supports the Payment Contract Agreement. The actual act of payment and settlements like charging a card, source bank account debit and destination account remittance are performed asynchronously by integrating with the already established payment infrastructure available in the region of operation like banking APIs, payment gateway / aggregator services, payment processors, open payment protocols etc. + +# Payment Contract Roles +There are two roles that participate in a payment contract agreement on beckn protocol. They are + +- Payer (belongs to BAP): The entity that pays for an order. +- Payee (belongs to BPP): The entity that receives payment for the order + +# Payment Terms + +The money transfer from a Payer to a Payee may go via different channels and modes. For example, a customer may use his credit card to pay the BAP say, at time T=0. The BAP may pay the BPP on T=1 as part of a bulk settlement. The BPP may pay the provider on T=2. And finally the provider may settle the money to the store owner or agent at T=3. At each stage, the intermediary may charge a small transaction fee to process that payment. In beckn protocol, only the settlement terms between the BAP and the BPP are considered. All other payment terms are outside the scope of beckn protocol and are strictly within the scope of the business partnership agreement between the respective parties. + +## BAP Terms +During a transaction, a BAP can inform the BPP its terms and conditions about collecting the payment. +- If it is going to collect the money first + +## BPP Payment Terms +The BPP must send its terms to the BAP . These terms contain the following information: +- The amount that needs to be paid in a specific currency +- The payment endpoint in url format. The supported url schemes are +1. https:// - For payment gateway endpoints +2. payto:// - For all other endpoints as defined in [RFC8095](https://datatracker.ietf.org/doc/html/rfc8905) +- The stage of the order lifecycle when the payment must be made +- When the payment must be settled with the Payee +- Status of the payment + +# Payment Contract Sequence + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-API-Sequence.png) + +# Payment Scenarios on beckn-enabled Networks + +An end-to-end payment flow between a BAP and a BPP comprises of the following activities + +1. Payment collection from buyer: The activity where the money is collected from the buyer +2. Payment settlement with seller: The activity where the money is settled with the seller + +From the buyer to the seller, money may flow through different payment intermediaries. Each intermediary may collect a small transaction fee for processing the transaction. Some common flows are shown below + +## Flow 1: BAP Collects Payment from Buyer + +1. BAP informs BPP that it will be collecting the payment first and then settling it with BPP via beckn protocol APIs +2. BPP agrees to BAP’s terms and allows BAP to collect the payment from the buyer via beckn protocol APIs +3. The BAP shows a payment interface to the buyer and the buyer makes the payment. The money gets deposited into the BAP’s bank account. This is NOT done via any beckn protocol APIs +4. BAP pays BPP : The BAP transfers the amount to the BPP’s bank account +5. BPP pays the Seller + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Settlement-Flow-1.png) + +## Flow 2: BPP collects payment from Buyer + +1. BAP informs BPP that it will NOT be collecting the payment and the BPP should provide the payee details for collection +2. BPP agrees to BAP’s terms and provides the payee details. These details can include a link to the BPP’s payment interface; bank account details or a virtual payment address (in case of UPI) +3. BPP renders the payment interface or other payment details on the BAP’s UI +4. The BAP user makes the payment directly to the BPP +5. BAP queries the BPP for the status of the transaction by providing the proof of payment via beckn protocol APIs +6. BPP periodically checks for transaction success from its Payment Service Provider +7. If payment is successful, the BPP returns the transaction status + +![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Settlement-Flow-2.png) + +# Invoking the Payment Flow on the BAP app + +Whenever a BAP user wants to checkout an order, the BAP should call the init action on the BPP’s API. The init message contains the final draft of the order that contains the items selected, billing and fulfillment details, or any other information the BPP might need to checkout the order. By calling this action, the BAP should expect the BPP to send the terms of payment along with any additional information needed to make the payment. + +Once the BPP receives the init message, it should send the acknowledgement that it has received the message. The BPP should then send the terms of payment by calling the on_init action on the BAP’s API. Upon receipt of the on_init API call, The BAP must invoke the payment flow on its app to collect the payment from the buyer and asynchronously settle the money with the BPP according to those terms. + +# Payment Object + +| Property | Description | +|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| url | Payment endpoint URL as defined in “BAP Terms” | +| tl_method | Method to call the API URL. supported values are 1. HTTP/GET 2. HTTP/POST 3. PAYTO 4. UPI | +| params | Parameters associated with that URL like 1. amount 2. currency Any other parameters required to authorize the payment like 1. ifsc 2. account 3. vpa (In case of UPI) | +| type | Stage at which the payment should happen. Supported values are: 1. ON-ORDER, 2. PRE-FULFILLMENT, 3. ON-FULFILLMENT, 4. POST-FULFILLMENT | +| time | If the type is “POST_FULFILLMENT”, this field contains the time related information at which the payment must be made | + +# Runtime Payment Object Examples + +## Example 1 +Payment Collection by a BAP and settled at the end of the month to a bank account before 30th of November 2021 + +``` +{ + "collected_by": "bap", + "uri": "payto://bank/98273982749428?amount=$currency:$value&ifsc=$ifsc&message=hello", + "method": "PAYTO", + "type": "POST_FULFILLMENT", + "status": "NOT-PAID", + "params": { + "ifsc": "SBIN0000575", + "value": "200", + "currency": "INR" + }, + "time": { + "range": { + "end": "2021-11-30 00:00:00" + } + } +} +``` + +## Example 2 +Immediate payment on order placement to a UPI Endpoint + +``` +{ + "uri": "payto://upi/example@upi?amount=$currency:$value&message=hello", + "method": "PAYTO", + "type": "ON-ORDER", + "status": "NOT-PAID", + "params": { + "value": "200", + "currency": "INR" + } +} +``` + +## Example 3 +Transfer to a Payment Gateway Endpoint + +``` +{ + "uri": "https://pay.example.com?amount=$value&cur=$currency", + "method": "PAYTO", + "type": "ON-ORDER", + "status": "NOT-PAID", + "params": { + "value": "200", + "currency": "INR" + } +} +``` + + + + + + + diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Policy-Administration-On-Beckn-Enabled-Networks.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Policy-Administration-On-Beckn-Enabled-Networks.md new file mode 100644 index 0000000..a21f436 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-Policy-Administration-On-Beckn-Enabled-Networks.md @@ -0,0 +1,339 @@ +# Policy Administration on Beckn-Enabled Networks + +## ID: +BECKN-RFC-004 + +## Draft ID +Draft-01 + +## Title: +Policy Administration on Beckn-Enabled Networks + +## Category: +Policy + +## Status: +Protocol Draft + +## Published on: +December 10, 2021 + +## Expires on: +December 10, 2022 or Date of publication of next draft which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Ravi Prakash : ravi@becknfoundation.org +2. Sujith Nair : sujith@becknfoundation.org + +## Reviewers: +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org + + +# Introduction + +Beckn protocol allows the creation of **Open Commerce Networks**. The primary actors on such networks are BAP, BPP, BG and Registry. Each actor implements an API that enables products and services to be discovered, ordered and fulfilled via a standard API. These API calls correspond to different interactions that happen between a buyer and a seller. + +The messages that are exchanged in these interactions belong to a standard sector-agnostic schema. The schema is very generic but is highly configurable. The configuration is done via the application of constraints and rules on the fields in various schema and subschema. + +Various use cases can be enabled by calling these APIs in different ways. These could be the order in which the APIs are called; the message fields that are mandatory to execute a specific function; the standards and formats that need to be used across all implementors to ensure data interoperability. + +Each network has a logical boundary. This boundary is created by the governance of a network. They will most likely be part of a larger consortium known as a Network Facilitator Organization. The facilitators create the boundary by defining the rules and regulations for various activities that are performed by the network participants starting from implementation to run-time. These rules are published by the creators as part of a document called the **Network Policy**. + +This document contains the methodology to publish, implement and enforce the Network Policy on an Open Commerce Network. The process of publication, implementation and enforcement of network policy is known as **Network Policy Administration**. + +# Network Policy Use Cases + +To get a better understanding of what a network policy outlines, let us take a look at some policy use cases that a network creator might enforce on the participants. + +## Supported Industry Sectors Adaptations + +While the protocol itself is sector agnostic, a network may support only a specific set of industry sectors like “Mobility”, “Retail”, or “Logistics”. These sectors may contain sub-sectors like, say, “On-demand Cab Services”, “Bike Rental”, “Metro services” under the Mobility Sector. Such sectors could be specified by allowing only certain sector codes to be transmitted in the messages. + +## Supported Fulfillment Modes +A network may support various fulfillment flows for various sectors. For example, a retail network may support "STORE-PICKUP" and "HOME-DELIVERY". In the sector of education, a network may support "VIRTUAL-CLASS" and "PHYSICAL-CLASS". These modes may vary with the Industry Sector Adaptations of a network. + +## Catalog Restrictions +A network may place restrictions on a catalog. For example, a network may restrict certain kinds of goods like *illegal items* or *non-essential* items to be listed or searched for. + +## Policy Coverage +A policy may apply to different geo-political regions on the map. It may also apply only during certain time slots. Such spatial and temporal on the policy is called **Policy Coverage** + +## Geo-Spatial Coverage +The network may place geo-spatial constraints on various activities performed on a network. For example, a network may allow certain businesses to operate only within a specific city. This rule may also include exclusion and inclusion zones within a city like containment zones, restricted areas etc. Such restrictions could be implemented by rejecting search requests to exclusion zones. + +## Temporal Coverage +The network may place temporal (time-based) constraints on various activities performed on a network. For example, a network may allow certain businesses to operate only within certain hours of the day, or only on certain days of the week. Sometimes, the network may allow specific platforms to operate for a fixed duration (like a month) as part of a pilot launch. + +# Policy Categories +Policies can be of various categories as shown below + +1. Implementation +2. Registration +3. Subscription +4. Transaction +5. Payment +6. Data Transmission +7. Communication + +# Problem Definition + +How do we set up a digital infrastructure that achieve the following outcomes: +1. Create, view, update and delete network policies for various use cases described above +2. Create, view, update and delete subscriber policies policies of a subscriber +3. Agree or disagree to a network policy +4. View network participants that have agreed / disagreed to specific network policies +5. Dynamically apply network policies as a middleware on protocol implementations +6. Audit network participants for compliance with a network policy + +# Solution Approach + +This section describes the specification to create a digital infrastructure to achieve the above outcomes. It contains +1. Implementation Process +2. Data Model +3. Policy APIs +4. Policy Agreement and Adoption Protocol +5. Reference Architecture +6. Sample Workflow + +# Network Policy Design Principles + +## Ensuring Interoperabililty +The guiding design principle of any network policy is to ensure interoperability at all costs. This can be achieved by publishing sector-specific codes, standards, benchmarks, data exchange mechanisms and supported use cases as Open API files, Policy Registries, Sample Flows and Certification Agencies etc. + +## Avoid Re-imposing Existing Policies +Most sector-specific regulatory policies are already enforced by the authorities of a region and do not need to be re-imposed on a network. For example, if selling unauthorised articles online is an existing policy that has been imposed by a region's authorities, it does not need to be re-imposed as a network policy. The fact that a network participant is on an Open Commerce Network does not change the rules and regulations of the region they are operating in. the Network Facilitators should strive to ensure that the relevant policies are available to the network participants easily without searching for them in various websites and possibly missing some of them. + +## Inclusiveness and Optimal Ignorance +This should be a prime directive of any Network Policy. Before designing a new policy, the policy designers must ask themselves following questions. +1. Is this needed? +2. Is this needed NOW? +3. Does this policy introduce unnecessary regulatory control over the network participants over and above the already established regulations of the industry? +4. Does this policy unnecessarily restrict NPs from registering on a network? + +## API-fication +All policy documents must be available and agreeable via an API. + +## Machine Readability +All policy administrators must strive to encode all policies in a machine readable format. This is of course not mandatory but merely a principle for the administrators to adopt as much as possible. In those cases where policies are subjective and cannot be encoded, they should be present as URLs to pdf documents + +## Non-repudiability +All policies in machine-readable or document format must be accompanied with digital signatures. These signatures must be digitally verifiable by NPs using public keys. + +# Policy Workflow +Policy administrators and network participants can adopt the below workflow. This merely a reference workflow and is not a standard. Networks are free to design their own workflows to ensure better interoperability. + +![Policy Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Workflow-New.png) + +# Policy Framework Roles +1. Policy Adopter (BPPs, BAPs, BGs, Registries) +2. Policy Publisher (SRO or equivalent) +3. Policy Auditor (Monitoring and Reporting) + +# Policy Implementation Architecture + +The below diagram shows a reference policy microservice layered on the transaction layer as a middleware. + +![Policy Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Agreement-Implementation-Architecture.png) + +# Policy Agreement and Adoption Protocol + +The below diagram shows a reference dynamic policy adoption workflow via policy API calls + +![Policy Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Agreement-and-Adoption-Protocol.png) + +# Policy Compliance Audits and Checks + +## Technical Audits +The NFO can engage a testing agency to test policy compliance via an automated test suite + +## Non-technical Audits +### Social Audits by External Agency: +NFO can engage a social audit agency to test compliance of a Subscriber + +### Social Audits by Users: +NFO can mandate that all apps must have a one-click report feature by which users can report any compliance issues with the application to an ODR system. These reports can be viewed by an auditor to fetch any policy compliance violations + +# Policy Layer Data Model +This section describes the minimum schema that must be implemented by any service that enables the above outcomes covering the use cases described above. + +## PolicyCategory + +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|--------|-----------------------------| +| id | string | ID of the policy category | +| name | string | Name of the policy category | + +## SpatialCoverage +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|----------|------------------------------------------| +| id | string | ID of the coverage | +| location | Location | Location of coverage | +| type | string | Enum ( “incl”, “excl” ), Default: “incl” | + +## TemporalCoverage +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|--------|------------------------------------------| +| id | string | ID of the coverage | +| time | Time | Time of coverage | +| type | string | Enum ( “incl”, “excl” ), Default: “incl” | + +## SubscriberCoverage +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|---------------|---------|------------------------------------------| +| id | string | ID of coverage | +| subscriber_id | string | ID of the subscriber | +| type | string | Enum ( “incl”, “excl” ), Default: “incl” | + +## SchemaOverride +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|-----------------|--------|---------------------------------------------| +| id | string | ID of row | +| target_schema | Time | Schema to be overriden | +| override_schema | string | Schema that has to override existing schema | + +## Action +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|--------|-------------------------| +| id | string | ID of protocol action | +| action | string | Name of protocol action | + +## ProtocolVersion +### Description +The protocol version of the specification + +### Type +string + +### Properties + + +## Policy +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|---------------------|--------------------|-------------------------------------| +| id | string | ID of policy | +| category | string | Category ID of policy | +| parent_policy_id | Time | Parent Policy | +| protocol_version | ProtocolVersion | Applicable protocol version | +| action | Action | Applied to action | +| schema_policy | SchemaPolicy | ID of schema policy | +| spatial_coverage | SpatialCoverage | Spatial Coverage of policy | +| temporal_coverage | TemporalCoverage | Temporal Coverage of policy | +| subscriber_coverage | SubscriberCoverage | Subscriber Coverage | +| published_on | DateTime | Date on which this was published | +| applicable_from | DateTime | Date from which this policy applies | +| expires_on | DateTime | Date on which this policy expires | +| signature | string | Digital Signature of publisher | +| attachment | string | URL of attached document | + +## PolicyManifest + +### Description +The complete list of policies published by a Network Subscriber + +### Type +object + +### Properties +| Property | Type | Description | +|-----------|----------------|---------------------| +| id | string | ID of manifest | +| policies | Array (Policy) | Array of policies | +| Meta info | string | Any additional info | + +## PolicyDifference +### Description +This is the diff of the policy files + +### Type +string + +## PolicyConflict +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|-----------|------------------|-----------------------------------------------| +| policy_id | boolean | Indicates if there is a conflict of interest | +| diff | PolicyDifference | A diff between existing and new schema | +| reason | ConflictReason | Reason for the conflict of interest | + +## ConflictReason +### Description +TODO + +### Type +object + +### Properties +| Property | Type | Description | +|----------|-------------|-------------| +| code | string enum | Reason code | + +#### Reason Codes Enumeration + +**NETWORK_POLICY_VIOLATION** +The adopter should return this code if the new policy violates the default network policy. + +**SELLER_POLICY_VIOLATION** +The adopter should return this code if the new policy violates the default seller policy, then. + + + + diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-The-Tags-Schema-Draft-01.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-The-Tags-Schema-Draft-01.md new file mode 100644 index 0000000..1c249dc --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/BECKN-The-Tags-Schema-Draft-01.md @@ -0,0 +1,189 @@ +# The Tags Schema + +## ID: +BECKN-RFC-The-Tags-Schema + +## Title: +The Tags Schema + +## Category: +Schema + +## Status: +Protocol Draft + +## Published on: +April 03, 2023 + +## Expires on: +April 02, 2024 or the date of publication of next draft, which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Ravi Prakash : ravi@fide.org + +# Scope + +This document contains recommendations that enable sector or category-specific information to be transmitted via beckn APIs. This document is intended for the following audience. + +1. Anyone who is attempting to add sector-specific attributes to various core schema elements. + +# Prerequisites + +Readers of this document must: + +1. Have knowledge of the core protocol specification +2. Have knowledge of the Architecture of Open Networks instantiated using beckn protocol. +3. Have knowledge of Open API 3.0 Specification + + +# Context + +Beckn protocol is a generic transaction protocol that allows any producer and consumer to interact and perform digitally signed transactions via a standard set of APIs. The schema of beckn has been abstracted to a level that allows any real-world entity to be represented as a generic object. + +Fundamentally, all transactions are the same according to beckn protocol. But practically, things are somewhat different. Sometimes, interacting entities (a.k.a Network Participants) need to send additional information related to various real-world entities to comply with policies and conventions governing the domain, network or the region of operation. Strictly speaking, this information may not be necessary to perform a transaction, but to allow an element of trust and convenience to be associated with a transaction. + +A retailer selling fast moving consumer goods might be legally obligated to send nutritional information, manufacturer details, food certification details, and other relevant information related to the products they are selling. On the other hand, consumers might want to narrow their search by sending specific information about the product they want. + +A car rental provider might want to send additional information on the make, model, variant, and other features of a car that might be useful to the customer to make a decision. It is also useful to the provider to provide faster and better search results if this additional information was sent by the customer while searching for the right car to rent. + +Similarly, a hospitality service provider may want to transmit additional information related to a room like AC/Non-AC, WiFi availability, Breakfast included, etc to allow the customer to choose the right room for themselves. + +As you can see from the above examples, the above information is not strictly necessary for an order to be created. But rather as metadata for display purposes, grouping, and filtering at the consumer’s end; and for enabling search optimization at the provider’s end. + + +# Problem + +How to transmit extended metadata related to a transaction in beckn protocol without breaking interoperability across implementations. + + +# Solution + +Beckn protocol defines a schema called **Tags**, that allows various sector-specific, network-specific key-value pairs to be transmitted between network participants. Each domain-specific adaptation of beckn protocol should publish a standard set of supported tags that all implementers should adopt. + + +## The **Tags** schema + +The **Tags** schema is an object. The schema is represented below. + + +``` +components: + schemas: + Tags: + description: A simple key-value store which is used to contain extended metadata. + additionalProperties: + type: string +``` + + +The `Tags` schema is explicitly referenced in the following schemas. + +* Category.tags +* Contact.tags +* Fulfillment.tags +* Intent.tags +* Item.tags +* Person.tags +* Provider.tags +* Support.tags + +However, this can be added to _any_ schema to carry extended metadata under the reserved keyname “tags”. + +## Usage + +When sending tags, the implementer must perform the following steps, + +1. Identify and define the domain / region / network specific attributes of each platform-specific schema that has been mapped +2. Codify the attribute +3. Add those tags in the appropriate schema with prefixes if required + + +## Grouped Tags + +Usually extended information sent in certain schema like `Item` require tags to be grouped under specific headings. For example, A television might have its details grouped under various headings like Technical Specifications, Additional Details, warranty, Installation Guide etc. To group such information under specific headings, a certain format has to be adopted. + +### Usage +1. Create an empty tag object +2. Create a key having the following prefix 'groups/{group-index}/'. Here group-index defines the order in which these groups are defined +3. Assign it the value equal to the name of the group. + +``` +{ + 'groups/1/descriptor/name' : "Nutritional Information" +} +``` +4. If the group is a standardized group, then we can use the `descriptor/code` property add it to the tag object. For example +``` +{ + 'groups/1/descriptor/name' : "Nutritional Information", + 'groups/1/descriptor/code' : "nutritional_info" +} +``` +5. If the group has to be displayed to the user, we can use the `display` property set to `true`. For example +``` +{ + 'groups/1/descriptor/name' : "Nutritional Information", + 'groups/1/descriptor/code' : "nutritional_info" + 'groups/1/display: true +} +``` +6. Add the list of tags under this group using the `list` property. For example +``` +{ + 'groups/1/descriptor/name' : "Nutritional Information", + 'groups/1/descriptor/code' : "nutritional_info" + 'groups/1/display: true, + 'groups/1/list/1/descriptor/name: "Sugar", + 'groups/1/list/1/descriptor/code: "sugar", +} +``` +7. Add the value of these listed tags using the `value` property. For example +``` +{ + 'groups/1/descriptor/name' : "Nutritional Information", + 'groups/1/descriptor/code' : "nutritional_info" + 'groups/1/display: true, + 'groups/1/list/1/descriptor/name: "Sugar", + 'groups/1/list/1/descriptor/code: "sugar", + 'groups/1/list/1/value: "3 g", +} +``` + +## Non-standard tags +In case the implementer wants to send a list of informational non-standard tags just for informational purposes, they can do so without the `descriptor/code` property. For example, + +``` +{ + 'groups/1/descriptor/name' : "Nutritional Information", + 'groups/1/display: true, + 'groups/1/list/1/descriptor/name: "Sugar", + 'groups/1/list/1/value: "3 g", +} +``` + +### Note: + +Sending non-standard tags is allowed, however it is recommended for all platforms to standardize tags as much as possible. This will allow rich experiences to be built on the BAP like comparison, filtering, sorting etc. + +At the BPP side, using standardized tags will allow for better indexing of catalogs that will ultimately result in faster search responses. + +## Nameless tag groups +In case the implementer wants to send listed information that is not in a key-value format but just a set of values, they can do so by omitting the `descriptor/name` and `descriptor/code` properties, and set just the `value` property. For example, + +``` +{ + 'groups/1/descriptor/name' : "Steps to installation", + 'groups/1/display: true, + 'groups/1/list/1/value: "Insert the adaptor into the socket", + 'groups/1/list/2/value: "Switch on the power button", + 'groups/1/list/2/value: "Click the network button at least 5 times until the LED glows orange", +} +``` + +## Parsing tags + +[TODO] + diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/README.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/README.md new file mode 100644 index 0000000..e05935f --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-drafts/README.md @@ -0,0 +1,5 @@ +# Protocol Drafts + +These files contain specifications that have been selected from the proposals submitted to the beckn protocol specifications. The are currently under review by different working groups in the various categories supported beckn protocol governance. + +After sufficient deliberation, these drafts may be published as a Protocol Standard. \ No newline at end of file diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-standards/README.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-standards/README.md new file mode 100644 index 0000000..2f17b88 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-standards/README.md @@ -0,0 +1,13 @@ +# Protocol Standards + +These files contain specifications that MUST be OR are RECOMMENDED to be implemented by the implementors of beckn protocol. + +There are two types of Protocol Standards + +## Required Standards + +These specifications MUST be implemented by ALL implementors of beckn protocol + +## Recommended Standards + +These specifications MUST be implemented by ALL implementors of beckn protocol on certain conditions ONLY. \ No newline at end of file diff --git a/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-standards/recommended/README.md b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-standards/recommended/README.md new file mode 100644 index 0000000..9ca7065 --- /dev/null +++ b/docs/mobility-core/api/core-0.9.x-lts/docs/protocol-standards/recommended/README.md @@ -0,0 +1,2 @@ +# Recommended Standards + diff --git a/docs/mobility-core/api/mobility.yaml b/docs/mobility-core/api/mobility.yaml new file mode 100644 index 0000000..1098169 --- /dev/null +++ b/docs/mobility-core/api/mobility.yaml @@ -0,0 +1,6070 @@ +openapi: 3.0.0 +info: + title: Beckn Mobility API Specification + description: Adaptation of beckn protocol for the mobility sector. Compatible with core version 0.9.4 LTS. + version: 0.8.2 +security: + - SubscriberAuth: [] + - GatewaySubscriberAuth: [] + - GatewaySubscriberAuthNew: [] +paths: + /search: + post: + tags: + - Beckn Provider Platform (BPP) + - Beckn Gateway (BG) + description: Search for services by intent + requestBody: + description: BAP searches for services + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + intent: + $ref: '#/components/schemas/Intent' + required: + - context + - message + examples: + Search for services in the city of Bengaluru by pickup and drop location: + value: + context: + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + action: search + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + intent: + fulfillment: + start: + location: + gps: 12.923608703179461, 77.61462964117527 + end: + location: + gps: 12.9346302, 77.61533969999999 + Search by pickup and drop location with localization info: + value: + context: + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + action: search + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + intent: + fulfillment: + start: + location: + gps: 12.923608703179461, 77.61462964117527 + end: + location: + gps: 12.9346302, 77.61533969999999 + customer: + person: + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /select: + post: + tags: + - Beckn Provider Platform (BPP) + description: Select items from the catalog and build your order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + examples: + Get quote for a specific product from a mobility catalog: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:46:45Z' + bap_id: example-bap.com + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.com + message_id: 432fdfd6-0457-47b6-9fac-80cbe5c0a75b + city: std:080 + core_version: 0.9.4 + action: select + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + max_callbacks: 3 + ttl: P120S + message: + order: + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + fulfillment: + start: + location: + gps: 12.910458, 77.543089 + end: + location: + gps: 12.9535139, 77.5710434 + Get quote for a specific product from a mobility catalog with gps and address details: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:46:45Z' + bap_id: example-bap.com + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.com + message_id: 432fdfd6-0457-47b6-9fac-80cbe5c0a75b + city: std:080 + core_version: 0.9.4 + action: select + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + max_callbacks: 3 + ttl: P120S + message: + order: + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + fulfillment: + start: + location: + gps: 12.910458, 77.543089 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9535139, 77.5710434 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + Get quote for a specific product from a mobility catalog with localization: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:46:45Z' + bap_id: example-bap.com + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.com + message_id: 432fdfd6-0457-47b6-9fac-80cbe5c0a75b + city: std:080 + core_version: 0.9.4 + action: select + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + max_callbacks: 3 + ttl: P120S + message: + order: + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + fulfillment: + start: + location: + gps: 12.910458, 77.543089 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9535139, 77.5710434 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + customer: + person: + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + Get a quote for a fare product selected from a public transit catalog: + value: + context: + domain: nic2004:60221 + country: IND + city: std:080 + action: select + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://kmrl-bpp.com + bpp_uri: https://kmrl-bpp.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + items: + - id: '1' + provider: + id: '1' + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /init: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + examples: + Initialize draft order and request for terms of service: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: init + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + provider: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + fulfillment_id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + payment_id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + quote: + value: '76' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + start: + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + collected_by: BPP + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + + Initialize the order by providing billing details: + value: + context: + domain: nic2004:60221 + country: IND + city: std:080 + action: init + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://kmrl-bpp.com + bpp_uri: https://kmrl-bpp.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + items: + - id: '1' + provider: + id: '1' + billing: + name: John Doe + email: john.doe@example.com + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /confirm: + post: + tags: + - Beckn Provider Platform (BPP) + description: Initialize an order by providing billing and/or shipping details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + required: + - context + - message + examples: + Confirm ride booking: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: confirm + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + start: + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: NOT-PAID + Confirm ticket booking: + value: + context: + domain: nic2004:60221 + country: IND + city: std:080 + action: confirm + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://kmrl-bpp.com + bpp_uri: https://kmrl-bpp.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + items: + - id: '1' + provider: + id: '1' + billing: + name: John Doe + email: john.doe@example.com + payment: + params: + amount: '55' + currency: INR + transaction_id: '24566345563' + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /status: + post: + tags: + - Beckn Provider Platform (BPP) + description: Fetch the latest order object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + required: + - order_id + required: + - context + - message + examples: + Get latest fulfillment status of a booking: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: status + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order_id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + Get latest status of a transit ticket booking: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: status + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://api.example-bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order_id: '123413' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /track: + post: + tags: + - Beckn Provider Platform (BPP) + description: Track an active order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + callback_url: + type: string + format: uri + required: + - order_id + required: + - context + - message + examples: + Track an active ride: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + city: std:080 + core_version: 0.9.4 + action: track + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order_id: 22e090fc-b8b1-4437-9126-ff7a71c7845c + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /cancel: + post: + tags: + - Beckn Provider Platform (BPP) + description: Cancel an order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order_id: + $ref: '#/components/schemas/Order/properties/id' + cancellation_reason_id: + $ref: '#/components/schemas/Option/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + required: + - order_id + required: + - context + - message + examples: + Cancel a ride with selected reason: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T05:15:08Z' + bap_id: api.beckn.juspay.in/pilot/bap/cab/v1 + bpp_id: api.beckn.juspay.in/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + message_id: be6a495a-e941-4fbf-9d59-f1e6166cccc8 + city: Bangalore + core_version: 0.9.4 + action: cancel + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order_id: b4232ad4-19ee-4c67-9223-a5189b13a741 + cancellation_reason_id: '5' + Cancel a ride with user provided information: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T05:15:08Z' + bap_id: api.beckn.juspay.in/pilot/bap/cab/v1 + bpp_id: api.beckn.juspay.in/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + message_id: be6a495a-e941-4fbf-9d59-f1e6166cccc8 + city: Bangalore + core_version: 0.9.4 + action: cancel + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order_id: b4232ad4-19ee-4c67-9223-a5189b13a741 + cancellation_reason_id: '7' + descriptor: + short_desc: Accidenally booked the ride + Cancel a transit ticket booking before the cancellation period: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: cancel + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://api.example-bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + cancellation_reason_id: '2' + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /update: + post: + tags: + - Beckn Provider Platform (BPP) + description: Remove object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + update_target: + description: 'Comma separated values of order objects being updated. For example: ```"update_target":"item,billing,fulfillment"```' + type: string + order: + $ref: '#/components/schemas/Order' + required: + - update_target + - order + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /rating: + post: + tags: + - Beckn Provider Platform (BPP) + description: Provide feedback on a service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + $ref: '#/components/schemas/Rating' + required: + - context + - message + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + examples: + Provide a rating: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:46:45Z' + bap_id: example-bap.com + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.com + message_id: 432fdfd6-0457-47b6-9fac-80cbe5c0a75b + city: std:080 + core_version: 0.9.4 + action: rating + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + id: b0462745-f6c9-4100-bbe7-4fa3648b6b40 + rating_category: DRIVER + value: 4 + Provide a rating with feedback form data: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:46:45Z' + bap_id: example-bap.com + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.com + message_id: 432fdfd6-0457-47b6-9fac-80cbe5c0a75b + city: std:080 + core_version: 0.9.4 + action: rating + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + id: b0462745-f6c9-4100-bbe7-4fa3648b6b40 + rating_category: DRIVER + value: 4 + feedback_form: + - id: '1' + answer: Driver took me on a route not shown by Google Maps and we reached 10 minutes before time + /support: + post: + tags: + - Beckn Provider Platform (BPP) + description: Contact support + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + ref_id: + type: string + description: ID of the element for which support is needed + required: + - context + - message + examples: + Fetch support information related to a particular order: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + city: std:080 + core_version: 0.9.4 + action: support + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + ref_id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_search: + post: + tags: + - Beckn App Platform (BAP) + - Beckn Gateway (BG) + description: Send catalog + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + catalog: + $ref: '#/components/schemas/Catalog' + required: + - catalog + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return a single provider mobility catalog: + value: + message: + context: + country: IND + bpp_uri: https://api.example-bpp.in/path/to/url + domain: nic2004:60221 + timestamp: '2023-03-23T04:43:02Z' + bap_id: example-bap.in + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.in + message_id: 21e54d3c-9c3b-47c1-aa3b-b0e7b20818ee + city: std:080 + core_version: 0.9.4 + action: on_search + bap_uri: https://api.example-bpp.in/path/to/url + catalog: + bpp/descriptor: + name: Acme Taxis + bpp/providers: + - id: '1' + descriptor: + name: Acme Taxis + locations: + - id: '1' + gps: 12.9164682,77.6089985 + - id: '2' + gps: 12.91671,77.6092983 + - id: '3' + gps: 12.9165733,77.6152167 + - id: '4' + gps: 12.9068578,77.6044567 + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Economy + code: RIDE + price: + value: '175' + currency: INR + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Waiting Charges + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + fulfillments: + - id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + start: + location: + gps: 12.9099828, 77.6118226 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9351856, 77.62459969999999 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + vehicle: + category: TAXI + payments: + - id: '1' + type: ON-FULFILLMENT + collected_by: BPP + Return a mobility catalog with multiple providers: + value: + message: + context: + country: IND + bpp_uri: https://api.example-bpp.in/path/to/url + domain: nic2004:60221 + timestamp: '2023-03-23T04:43:02Z' + bap_id: example-bap.in + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.in + message_id: 21e54d3c-9c3b-47c1-aa3b-b0e7b20818ee + city: std:080 + core_version: 0.9.4 + action: on_search + bap_uri: https://api.example-bpp.in/path/to/url + catalog: + bpp/descriptor: + name: Open Mobility Solutions + images: + - https://example-bpp.com/images/logos/oms.ico + bpp/providers: + - id: '1' + descriptor: + name: Acme Cabs + images: + - https://example-bpp.com/images/logos/acme.ico + items: + - id: '1' + descriptor: + name: Economy + price: + value: '175' + currency: INR + fulfillment_id: '1' + payment_id: '1' + - id: '2' + descriptor: + name: Premium + price: + value: '250' + currency: INR + fulfillment_id: '1' + payment_id: '1' + - id: '3' + descriptor: + name: Luxury + price: + value: '500' + currency: INR + fulfillment_id: '1' + payment_id: '1' + fulfillments: + - id: '1' + start: + location: + gps: 12.9099828, 77.6118226 + end: + location: + gps: 12.9351856, 77.6245996 + vehicle: + category: TAXI + payments: + - id: '1' + type: ON-FULFILLMENT + collected_by: BPP + - descriptor: + name: Beta Taxis + images: + - https://example-bpp.com/images/logos/betataxis.ico + items: + - id: '1' + descriptor: + name: Beta Prime + short_desc: Affordable sedans, at affordable costs + price: + value: '200' + currency: INR + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + - id: '2' + descriptor: + name: Beta Max + short_desc: Spacious vans for large groups + price: + value: '1500' + currency: INR + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + fulfillments: + - id: '1' + start: + location: + gps: 12.9099828, 77.6118226 + end: + location: + gps: 12.9351856, 77.62459969999999 + vehicle: + category: TAXI + - id: '2' + start: + location: + gps: 12.9099828, 77.6118226 + end: + location: + gps: 12.9351856, 77.62459969999999 + vehicle: + category: TEMPO-TRAVELLER + payments: + - id: '1' + type: ON-FULFILLMENT + collected_by: BPP + Return a mobility catalog with no provider: + value: + message: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:43:02Z' + bap_id: example-bap.com + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.com + message_id: 21e54d3c-9c3b-47c1-aa3b-b0e7b20818ee + city: std:080 + core_version: 0.9.4 + action: on_search + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + catalog: + bpp/descriptor: + name: InstaAuto + bpp/providers: + - id: 1 + locations: + - id: '1' + gps: 12.9164682,77.6089985 + - id: '2' + gps: 12.91671,77.6092983 + - id: '3' + gps: 12.9165733,77.6152167 + - id: '4' + gps: 12.9068578,77.6044567 + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + price: + maximum_value: '156' + currency: INR + minimum_value: '176' + value: 156 - 176 INR + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + fulfillments: + - id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + start: + location: + gps: 12.9099828, 77.6118226 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9351856, 77.62459969999999 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + vehicle: + category: AUTO_RICKSHAW + payments: + - id: '1' + type: ON-FULFILLMENT + collected_by: BPP + Return a single provider mobility catalog (with some optional tags): + value: + message: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:43:02Z' + bap_id: example-bap.com + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + bpp_id: example-bpp.com + message_id: 21e54d3c-9c3b-47c1-aa3b-b0e7b20818ee + city: std:080 + core_version: 0.9.4 + action: on_search + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + catalog: + bpp/descriptor: + name: InstaAuto + bpp/providers: + - locations: + - id: '1' + gps: 12.9164682,77.6089985 + - id: '2' + gps: 12.91671,77.6092983 + - id: '3' + gps: 12.9165733,77.6152167 + - id: '4' + gps: 12.9068578,77.6044567 + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + price: + maximum_value: '156' + currency: INR + minimum_value: '176' + value: 156 - 176 INR + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Waiting Charges + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Night Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + fulfillments: + - id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + start: + location: + gps: 12.9099828, 77.6118226 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9351856, 77.62459969999999 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + vehicle: + category: AUTO_RICKSHAW + payments: + - id: '1' + type: ON-FULFILLMENT + collected_by: BPP + Return a public transit catalog of fare products: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: on_search + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + catalog: + bpp/descriptor: + name: Transit Solutions + images: + - https://transitsolutions.in/logos/logo.ico + bpp/providers: + - id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + items: + - id: '1' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '1' + price: + currency: '35' + value: INR + - id: '2' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '2' + price: + currency: '65' + value: INR + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + - id: '4' + descriptor: + name: Return Journey Ticket + images: + - https://delhimetrorail.com/icons/rjt.ico + fulfillment_id: '1' + price: + currency: '60' + value: INR + - id: '5' + descriptor: + name: Return Journey Ticket + images: + - https://delhimetrorail.com/icons/rjt.ico + fulfillment_id: '2' + price: + currency: '90' + value: INR + - id: '6' + descriptor: + name: Return Journey Ticket + images: + - https://delhimetrorail.com/icons/rjt.ico + fulfillment_id: '3' + price: + currency: '100' + value: INR + - id: '7' + descriptor: + name: Monthly Pass + images: + - https://delhimetrorail.com/icons/mp.ico + price: + currency: INR + value: '250' + fulfillments: + - id: '1' + start: + location: + descriptor: + name: Dwarka Sector 10 - Blue Line + gps: 28.5811261,77.0548206 + end: + location: + descriptor: + name: Patel Chowk - Yellow Line + gps: 28.6230972,77.2099917 + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '1' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 60 min + - id: '2' + start: + location: + descriptor: + name: Dwarka Sector 10 - Blue Line + gps: 28.5811261,77.0548206 + end: + location: + descriptor: + name: Shivaji Stadium - Airport Express Line + gps: 28.6288785,77.2085895 + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '1' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 45 min + - id: '3' + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + tags: + groups/0/list/0/descriptor/name: Timetable + groups/0/list/0/value: https://delhimetrorail.com/timetable.html + groups/0/list/1/descriptor/name: GTFS Schedule + groups/0/list/1/value: https://delhimetrorail.com/gtfs + groups/0/list/1/display: false + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - context + /on_select: + post: + tags: + - Beckn App Platform (BAP) + description: Send draft order object with quoted price for selected items + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return a quote offered by a ride hailing service provider: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + transaction_id: 870782be-6757-43f1-945c-8eeaf9536259 + city: std:080 + core_version: 0.9.4 + action: on_select + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '76' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + ttl: P200S + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + name: Found drivers + code: AGENTS_FOUND + start: + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + Return a quote offered by a public transit service provider: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: on_select + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + tags: + groups/0/list/0/descriptor/name: Validity + groups/0/list/0/value: 24 hours from the time of purchase + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + quote: + price: + value: '60.5' + currency: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_init: + post: + tags: + - Beckn App Platform (BAP) + description: Send order object with payment details updated + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return draft ride hailing order with payment after ride completion: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_init + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + start: + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: NOT-PAID + Return draft order for transit ticket with settlement via payment link: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: on_init + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://api.example-bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + tags: + groups/0/list/0/descriptor/name: Validity + groups/0/list/0/value: 24 hours from the time of purchase + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + instructions: Show this ticket at the QR code scanner at the entry gate. If the QR code scanner is not present, show this at the ticket counter to get your token + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + documents: + - label: Cancellation Terms + url: https://dmrc.com/fare_products/sjt/cancellation_terms.html + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + type: ON-ORDER + uri: https://pay.razorpay.com?amt=60.5&cur=INR&ref=24566345563 + tl_method: GET + status: NOT-PAID + + Return draft order for transit ticket with T+1 settlment via bank transfer: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: on_init + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://api.example-bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + tags: + groups/0/list/0/descriptor/name: Validity + groups/0/list/0/value: 24 hours from the time of purchase + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + instructions: Show this ticket at the QR code scanner at the entry gate. If the QR code scanner is not present, show this at the ticket counter to get your token + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + documents: + - label: Cancellation Terms + url: https://dmrc.com/fare_products/sjt/cancellation_terms.html + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + type: POST-FULFILLMENT + status: NOT-PAID + params: + amount: '60.5' + currency: INR + transaction_id: '24566345563' + bank_account: '32756678999' + bank_code: 'SBIN0000575' + time: + range: + start: '2021-03-23T10:00:40.065Z' + end: '2021-03-24T10:00:40.065Z' + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_confirm: + post: + tags: + - Beckn App Platform (BAP) + description: Send active order object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return confirmed order with latest fulfillment details: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_confirm + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: DRIVER_EN_ROUTE + name: Driver is on the way + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: NOT-PAID + Return confirmed ticket order with payment confirmation: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: on_confirm + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://api.example-bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + tags: + groups/0/list/0/descriptor/name: Validity + groups/0/list/0/value: 24 hours from the time of purchase + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + instructions: Show this ticket at the QR code scanner at the entry gate. If the QR code scanner is not present, show this at the ticket counter to get your token + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + documents: + - label: Cancellation Terms + url: https://dmrc.com/fare_products/sjt/cancellation_terms.html + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + type: ON-ORDER + status: PAID + params: + amount: '60.5' + currency: INR + transaction_id: '24566345563' + Return confirmed ticket order with T+1 pending settlement: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: on_confirm + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://api.example-bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + tags: + groups/0/list/0/descriptor/name: Validity + groups/0/list/0/value: 24 hours from the time of purchase + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + state: + descriptor: + name: Ticket issued + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + instructions: Show this ticket at the QR code scanner at the entry gate. If the QR code scanner is not present, show this at the ticket counter to get your token + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + documents: + - label: Cancellation Terms + url: https://dmrc.com/fare_products/sjt/cancellation_terms.html + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + type: POST-FULFILLMENT + status: NOT-PAID + params: + amount: '60.5' + currency: INR + transaction_id: '24566345563' + bank_account: '32756678999' + bank_code: 'SBIN0000575' + time: + range: + start: '2021-03-23T10:00:40.065Z' + end: '2021-03-24T10:00:40.065Z' + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_track: + post: + tags: + - Beckn App Platform (BAP) + description: Send tracking details of an active order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + tracking: + $ref: '#/components/schemas/Tracking' + required: + - tracking + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return tracking information for an order: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T05:41:09Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + message_id: ec3dea8c-c64c-4f06-b2a0-ec1f9584d7ba + city: std:080 + core_version: 0.9.4 + action: on_track + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + tracking: + content_type: application/json + url: https://api.beckn.juspay.in/dobpp/ui/driver/location/abc9f0aa-bbfd-4e91-b378-41feee12f05f + status: active + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_cancel: + post: + tags: + - Beckn App Platform (BAP) + description: Send cancellation request_id with reasons list in case of cancellation request. Else send cancelled order object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return order cancelled by the driver: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_cancel + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '0' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: RIDE_CANCELLED + name: Oops! The driver had to cancel + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payments: + - id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: POST-FULFILLMENT + params: + amount: '0' + currency: INR + transaction_status: CANCELLED + Return order cancelled by rider with cancellation charges: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_cancel + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '30' + currency: INR + breakup: + - title: Cancellation charges + price: + value: '30' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: DRIVER_EN_ROUTE + name: Driver is on the way + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: POST-FULFILLMENT + params: + amount: '30' + currency: INR + transaction_status: NOT-PAID + bank_account_name: RAGHAVENDRA J + bank_account: '32754478993' + bank_code: SBIN0000575 + time: + duration: P1D + Return cancelled ticket order with cancellation charges: + value: + context: + domain: nic2008:49213 + country: IND + city: std:011 + action: on_cancel + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://api.example-bap.com/beckn/ + bpp_id: https://transit-solutions.com + bpp_uri: https://api.transit-solutions.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + tags: + groups/0/list/0/descriptor/name: Validity + groups/0/list/0/value: 24 hours from the time of purchase + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + instructions: Show this ticket at the QR code scanner at the entry gate. If the QR code scanner is not present, show this at the ticket counter to get your token + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + documents: + - label: Cancellation Terms + url: https://dmrc.com/fare_products/sjt/cancellation_terms.html + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + type: POST-FULFILLMENT + status: NOT-PAID + params: + amount: '10' + currency: INR + bank_account: '32756678999' + bank_code: SBIN0000575 + time: + range: + start: '2021-03-23T10:00:40.065Z' + end: '2021-03-24T10:00:40.065Z' + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_update: + post: + tags: + - Beckn App Platform (BAP) + description: Returns updated service with updated runtime object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return updated order with payment transaction status: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_confirm + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + update_target: order.payment + order: + id: ABC1234 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: PAYMENT_COLLECTED + name: Payment received + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: PAID + Return updated order with recomputed charges: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_confirm + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + update_target: order.payment, order.quote + order: + id: ABC1234 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '75' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '40' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: RIDE_ENDED + name: Your ride has ended + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '75' + currency: INR + transaction_status: NOT-PAID + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_status: + post: + tags: + - Beckn App Platform (BAP) + description: Fetch the status of a Service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return order with status - Driver at pickup: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_status + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: DRIVER_AT_PICKUP + name: Driver Arrived at Pickup Location + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: NOT-PAID + Return order with latest fulfillment status - Driver en-route to pickup: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_status + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: DRIVER_EN_ROUTE_TO_PICKUP + name: Driver is en-route to your location + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: NOT-PAID + Return order with latest status - Ride started: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_status + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: RIDE_STARTED + name: Your ride has started + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: NOT-PAID + Return order with latest status - Ride Ended: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T04:48:53Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + transaction_id: b580c989-f84d-4abe-af28-2c818aafce3b + message_id: 8926b747-0362-4fcc-b795-0994a6287700 + city: std:080 + core_version: 0.9.4 + action: on_status + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + order: + id: 7751bd26-3fdc-47ca-9b64-e998dc5abe68 + provider: + id: e8542642-0f4a-454c-9a9f-f46110c367a3 + descriptor: + name: Raghavendra J + items: + - id: 5777a0bf-9a08-49aa-a97d-1e5561a9622e + descriptor: + name: Auto Ride + code: RIDE + tags: + groups/1/descriptor/name: Daytime Charges + groups/1/display: true + groups/1/list/1/descriptor/name: Min Fare upto 2 km + groups/1/list/1/value: ₹ 30 upto 2 km + groups/1/list/2/descriptor/name: Rate above Min. Fare + groups/1/list/2/value: ₹15 / km + groups/1/list/3/descriptor/name: Driver Pickup Charges + groups/1/list/3/value: ₹ 10 + groups/1/list/4/descriptor/name: Nominal Fare + groups/1/list/4/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/4/value: ₹ 10 + groups/1/list/5/descriptor/name: Nominal Fare + groups/1/list/5/descriptor/short_desc: Driver may quote extra to cover for traffic, chance of return trip, etc. + groups/1/list/5/value: ₹ 0 / min + groups/2/descriptor/name: Waiting Charges + groups/2/display: true + groups/2/list/1/descriptor/name: Night Charges + groups/2/list/1/value: 1.5x of daytime charges applicable at night from 10 PM to 5 PM + groups/2/list/2/descriptor/name: Night Shift Start + groups/2/list/2/value: '22:00:00' + groups/2/list/3/descriptor/name: Night Shift End + groups/2/list/3/value: '05:00:00' + groups/3/descriptor/name: General Information + groups/3/display: true + groups/3/list/1/descriptor/name: Distance to nearest driver + groups/3/list/1/value: 661 m + groups/3/list/2/descriptor/name: Wait time upto + groups/3/list/2/value: 3 min + fulfillment_id: fb5c84d4-1b59-4b9d-96b5-9d79107432c5 + payment_id: '1' + quote: + value: '81' + currency: INR + breakup: + - title: Base Fare + price: + value: '30' + currency: INR + - title: Per km fare + price: + value: '56' + currency: INR + - title: CGST @ 5% + price: + value: '2.5' + currency: INR + - title: SGST @ 5% + price: + value: '2.5' + currency: INR + fulfillment: + id: fulf_5cf064d5-4c0a-42d3-b73d-5f19a6f7468e + state: + descriptor: + code: RIDE_ENDED + name: Your ride has ended + start: + authorization: + type: OTP + token: '234234' + location: + gps: 13.008935, 77.6444085 + address: + ward: Uttarahalli Hobli, Ramanjaneyanagar + country: India + building: 6th Main Rd + state: Karnataka 560061 + city: Bengaluru + locality: Uttarahalli Hobli + door: 98A, Sarovarm 2nd cross + area_code: '560061' + street: Ramanjaneyanagar + end: + location: + gps: 12.9711869, 77.5868122 + address: + ward: Basavanagudi, Chikkanna Garden, Rangadore Memorial Hospital + country: India + building: Rangadore Memorial Hospital + state: Karnataka + city: Bengaluru + locality: Basavanagudi + door: null + area_code: '' + street: Chikkanna Garden + agent: + name: RAGHAVENDRA J + phone: +91-98978675645 + rateable: true + rating: '5' + vehicle: + category: AUTO_RICKSHAW + registration: KA01JG1231 + customer: + person: + name: John Doe + phone: +91-9897867564 + tags: + groups/1/descriptor/name: Localization + groups/1/display: false + groups/1/list/1/descriptor/name: Language + groups/1/list/1/value: en + payment: + id: 7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + type: ON-FULFILLMENT + params: + amount: '81' + currency: INR + transaction_status: NOT-PAID + Return transit ticket order with status - Ticket Issued: + value: + context: + domain: nic2004:60221 + country: IND + city: std:080 + action: on_status + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://kmrl-bpp.com + bpp_uri: https://kmrl-bpp.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + state: + descriptor: + name: Ticket Issued + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + uri: https://pay.razorpay.com?amt=60.5&cur=INR&ref=24566345563 + params: + amount: '60.5' + currency: INR + transaction_id: '24566345563' + status: PAID + Return transit ticket order with status - Entered Paid Area: + value: + context: + domain: nic2004:60221 + country: IND + city: std:080 + action: on_status + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://kmrl-bpp.com + bpp_uri: https://kmrl-bpp.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + state: + descriptor: + name: Entered paid area + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + uri: https://pay.razorpay.com?amt=60.5&cur=INR&ref=24566345563 + params: + amount: '60.5' + currency: INR + transaction_id: '24566345563' + status: PAID + Return transit ticket order with status - Exited paid area: + value: + context: + domain: nic2004:60221 + country: IND + city: std:080 + action: on_status + core_version: 0.9.4 + bap_id: https://example-bap.com + bap_uri: https://mock_bap.com/beckn/ + bpp_id: https://kmrl-bpp.com + bpp_uri: https://kmrl-bpp.com/beckn/ + transaction_id: 6f339232-2bc3-44d2-915c-30d2b053ce1d + message_id: fde8b8b6-c2e5-49f7-b254-720843d528bd + timestamp: '2021-03-23T10:00:40.065Z' + message: + order: + id: '123413' + items: + - id: '3' + descriptor: + name: Single Journey Ticket + images: + - https://delhimetrorail.com/icons/sjt.ico + fulfillment_id: '3' + price: + currency: '55' + value: INR + provider: + id: '1' + descriptor: + name: Delhi Metro Rail Limited + images: + - https://delhimetrorail.com/logos/logo.ico + fulfillment: + id: '3' + state: + descriptor: + name: Exited paid area + start: + location: + descriptor: + name: Dwarka Sector 21 + gps: 9.05,12.06 + time: + timestamp: '2021-10-15T00:32:19.000Z' + end: + location: + descriptor: + name: Shivaji Stadium + gps: 9.07,12.07 + time: + timestamp: '2021-10-15T00:43:21.000Z' + vehicle: + category: METRO + tags: + groups/0/list/0/descriptor/name: Transfers + groups/0/list/0/value: '0' + groups/0/list/1/descriptor/name: Duration + groups/0/list/1/value: 30 min + billing: + name: John Doe + email: john.doe@example.com + quote: + price: + currency: '60.5' + value: INR + breakup: + - title: Single Journey Ticket X 1 + price: + currency: INR + value: '55' + - title: CGST @ 5% + price: + currency: INR + value: '2.75' + - title: SGST @ 5% + price: + currency: INR + value: '2.75' + payment: + uri: https://pay.razorpay.com?amt=60.5&cur=INR&ref=24566345563 + params: + amount: '60.5' + currency: INR + transaction_id: '24566345563' + status: PAID + + + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_rating: + post: + tags: + - Beckn App Platform (BAP) + description: Provide feedback on a service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + $ref: '#/components/schemas/RatingAck' + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return acknowledgement of rating and feedback: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T05:41:15Z' + bap_id: api.beckn.juspay.in/pilot/bap/cab/v1 + bpp_id: api.beckn.juspay.in/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + message_id: 2a17e268-1dc4-4d1a-98a2-17554a50c7d2 + city: Bangalore + core_version: 0.9.4 + action: on_rating + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + feedback_ack: true + rating_ack: true + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /on_support: + post: + tags: + - Beckn App Platform (BAP) + description: Contact Support + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + phone: + type: string + format: phone + email: + type: string + format: email + uri: + type: string + format: uri + error: + $ref: '#/components/schemas/Error' + required: + - context + examples: + Return support information related to an order: + value: + context: + country: IND + bpp_uri: https://api.example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + domain: nic2004:60221 + timestamp: '2023-03-23T05:41:09Z' + bap_id: example-bap.com + bpp_id: example-bpp.com + message_id: ec3dea8c-c64c-4f06-b2a0-ec1f9584d7ba + city: std:080 + core_version: 0.9.4 + action: on_support + bap_uri: https://api.example-bap.com/pilot/bap/cab/v1 + message: + phone: '+918068870525' + email: support@example-bpp.com + url: https://support.example-bpp.com/gethelp + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_cancellation_reasons: + post: + tags: + - BPP Meta APIs + description: Get cancellation reasons from the BPP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + examples: + Request for cancellation reasons list: + value: + context: + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + bap_uri: https://example-bap.com/pilot/bap/cab/v1 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + action: get_cancellation_reasons + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /cancellation_reasons: + post: + tags: + - BAP Meta APIs + description: Get cancellation reasons from the BPP + requestBody: + description: List of cancellation reasons + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + cancellation_reasons: + type: array + items: + $ref: '#/components/schemas/Option' + examples: + Send a list of cancellation reasons: + value: + context: + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + bap_uri: https://example-bap.com/pilot/bap/cab/v1 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + action: cancellation_reasons + message: + cancellation_reasons: + - id: '1' + descriptor: + name: Got a ride elsewhere + - id: '2' + descriptor: + name: Fare was high + - id: '3' + descriptor: + name: Wait time too long + - id: '4' + descriptor: + name: Driver wasn't reachable + - id: '5' + descriptor: + name: Driver was rude + - id: '6' + descriptor: + name: Driver requested me to cancel + - id: '7' + descriptor: + name: Some other reason + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_return_reasons: + post: + tags: + - BPP Meta APIs + description: Get return reasons from the BPP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /return_reasons: + post: + tags: + - BAP Meta APIs + description: Get return reasons from the BPP + requestBody: + description: List of return reasons + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + return_reasons: + type: array + items: + $ref: '#/components/schemas/Option' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_rating_categories: + post: + tags: + - BPP Meta APIs + description: Get a list of categories that can be rated by the BAP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + examples: + Request rateable entities from the BPP: + value: + context: + action: get_rating_categories + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + bap_uri: https://example-bap.com/pilot/bap/cab/v1 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /rating_categories: + post: + tags: + - BAP Meta APIs + description: Get a list of categories that can be rated by the BAP + requestBody: + description: Array of categories which can be rated + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + rating_categories: + type: array + items: + $ref: '#/components/schemas/Rating/properties/rating_category' + examples: + Send a list of rateable entities in a BPP: + value: + context: + action: get_rating_categories + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + bap_uri: https://example-bap.com/pilot/bap/cab/v1 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + message: + rating_categories: + - RIDE + - DRIVER + - VEHICLE + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_feedback_categories: + post: + tags: + - BPP Meta APIs + description: Get a list of categories for which feedback can be given by the BAP + requestBody: + description: Context header is sent as the request + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /feedback_categories: + post: + tags: + - BAP Meta APIs + description: Get a list of categories for which feedback can be given by the BAP + requestBody: + description: Array of categories for which feedback can be given by the BAP + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + feedback_categories: + type: array + items: + $ref: '#/components/schemas/Rating/properties/rating_category' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /get_feedback_form: + post: + tags: + - BPP Meta APIs + description: Request a feedback form from the BPP + requestBody: + description: The rating value and category is sent by the BAP + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + type: object + properties: + rating_value: + $ref: '#/components/schemas/Rating/properties/value' + rating_category: + $ref: '#/components/schemas/Rating/properties/rating_category' + examples: + Request feedback form for a specific rating and rating category: + value: + context: + action: get_feedback_form + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + bap_uri: https://example-bap.com/pilot/bap/cab/v1 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + message: + rating_value: '4' + rating_category: RIDE + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message + /feedback_form: + post: + tags: + - BAP Meta APIs + description: Get a feedback form from the BPP + requestBody: + description: Feedback form sent by the BPP + content: + application/json: + schema: + type: object + properties: + context: + $ref: '#/components/schemas/Context' + message: + $ref: '#/components/schemas/Feedback' + example: + Send feedback form: + value: + context: + action: feedback_form + country: IND + domain: nic2004:60221 + timestamp: '2023-03-23T04:41:16Z' + bap_id: example-bap.com + bap_uri: https://example-bap.com/pilot/bap/cab/v1 + bpp_id: example-bpp.com + bpp_uri: https://example-bpp.com/dobpp/beckn/7f7896dd-787e-4a0b-8675-e9e6fe93bb8f + transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176 + city: std:080 + core_version: 0.9.4 + message: + feedback_form: + - id: 1 + question: Tell us your feedback + answer_type: text + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + message: + type: object + properties: + ack: + $ref: '#/components/schemas/Ack' + required: + - ack + error: + $ref: '#/components/schemas/Error' + required: + - message +components: + securitySchemes: + SubscriberAuth: + type: apiKey + in: header + name: Authorization + description: 'Signature of message body using BAP or BPP subscriber''s signing public key.

Format:

Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(BLAKE-512(signing string))"' + GatewaySubscriberAuth: + type: apiKey + in: header + name: Proxy-Authorization + description: 'Signature of message body + BAP/BPP''s Authorization header using BG''s signing public key. Format:

Proxy-Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(BLAKE-512(signing string))"

Note:This header will be deprecated soon and will no longer be supported in future releases. New implementors are requested to use the X-Gateway-Authorization header. Existing implementations are requested to migrate their header to the new header. The deprecation date will be set after discussion as per the standard specification governance process.

' + GatewaySubscriberAuthNew: + type: apiKey + in: header + name: X-Gateway-Authorization + description: 'Signature of message body + BAP/BPP''s Authorization header using BG''s signing public key. Format:

X-Gateway-Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(BLAKE-512(signing string))"' + schemas: + Ack: + description: Describes the ACK response + type: object + properties: + status: + type: string + description: Describe the status of the ACK response. If schema validation passes, status is ACK else it is NACK + enum: + - ACK + - NACK + required: + - status + AddOn: + description: Describes an add-on + type: object + properties: + id: + type: string + description: 'ID of the add-on. This follows the syntax {item.id}/add-on/{add-on unique id} for item specific add-on OR ' + descriptor: + $ref: '#/components/schemas/Descriptor' + price: + $ref: '#/components/schemas/Price' + Address: + description: Describes an address + type: object + properties: + door: + type: string + description: Door / Shop number of the address + name: + type: string + description: Name of address if applicable. Example, shop name + building: + type: string + description: Name of the building or block + street: + type: string + description: Street name or number + locality: + type: string + description: Name of the locality, apartments + ward: + type: string + description: Name or number of the ward if applicable + city: + type: string + description: City name + state: + type: string + description: State name + country: + type: string + description: Country name + area_code: + type: string + description: Area code. This can be Pincode, ZIP code or any equivalent + Agent: + description: Describes an order executor + allOf: + - $ref: '#/components/schemas/Person' + - $ref: '#/components/schemas/Contact' + - type: object + properties: + rateable: + $ref: '#/components/schemas/Rateable' + Authorization: + description: Describes an authorization mechanism + type: object + properties: + type: + type: string + description: Type of authorization mechanism used + token: + type: string + description: Token used for authorization + valid_from: + type: string + format: date-time + description: Timestamp in RFC3339 format from which token is valid + valid_to: + type: string + format: date-time + description: Timestamp in RFC3339 format until which token is valid + status: + type: string + description: Status of the token + Billing: + description: Describes a billing event + type: object + properties: + name: + description: Personal details of the customer needed for billing. + type: string + organization: + $ref: '#/components/schemas/Organization' + address: + $ref: '#/components/schemas/Address' + email: + type: string + format: email + phone: + type: string + time: + $ref: '#/components/schemas/Time' + tax_number: + type: string + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + required: + - name + - phone + Cancellation: + description: Describes the ACK response + type: object + properties: + type: + type: string + enum: + - full + - partial + ref_id: + type: string + policies: + type: array + items: + $ref: '#/components/schemas/Policy' + time: + type: string + format: date-time + cancelled_by: + type: string + reasons: + $ref: '#/components/schemas/Option' + selected_reason: + type: object + properties: + id: + $ref: '#/components/schemas/Option/properties/id' + additional_description: + $ref: '#/components/schemas/Descriptor' + Catalog: + description: Describes a BPP catalog + type: object + properties: + bpp/descriptor: + $ref: '#/components/schemas/Descriptor' + bpp/categories: + type: array + items: + $ref: '#/components/schemas/Category' + bpp/fulfillments: + type: array + items: + $ref: '#/components/schemas/Fulfillment' + bpp/payments: + type: array + items: + $ref: '#/components/schemas/Payment' + bpp/offers: + type: array + items: + $ref: '#/components/schemas/Offer' + bpp/providers: + type: array + items: + $ref: '#/components/schemas/Provider' + exp: + type: string + description: Time after which catalog has to be refreshed + format: date-time + Category: + description: Describes a category + type: object + properties: + id: + type: string + description: Unique id of the category + parent_category_id: + $ref: '#/components/schemas/Category/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + time: + $ref: '#/components/schemas/Time' + tags: + $ref: '#/components/schemas/Tags' + Circle: + description: Describes a circular area on the map + type: object + properties: + gps: + $ref: '#/components/schemas/Gps' + radius: + $ref: '#/components/schemas/Scalar' + required: + - gps + - radius + City: + description: Describes a city + type: object + properties: + name: + type: string + description: Name of the city + code: + type: string + description: City code + Contact: + type: object + properties: + phone: + type: string + email: + type: string + tags: + $ref: '#/components/schemas/Tags' + Context: + description: Describes a beckn message context + type: object + properties: + domain: + $ref: '#/components/schemas/Domain' + country: + $ref: '#/components/schemas/Country/properties/code' + city: + $ref: '#/components/schemas/City/properties/code' + action: + type: string + description: Defines the Beckn API call. Any actions other than the enumerated actions are not supported by Beckn Protocol + enum: + - search + - select + - init + - confirm + - update + - status + - track + - cancel + - rating + - support + - on_search + - on_select + - on_init + - on_confirm + - on_update + - on_status + - on_track + - on_cancel + - on_rating + - on_support + core_version: + type: string + description: Version of Beckn core API specification being used + bap_id: + type: string + format: uri + description: Unique id of the BAP. By default it is the fully qualified domain name of the BAP + bap_uri: + type: string + format: uri + description: URI of the BAP for accepting callbacks. Must have the same domain name as the bap_id + bpp_id: + type: string + format: uri + description: Unique id of the BPP. By default it is the fully qualified domain name of the BPP + bpp_uri: + type: string + format: uri + description: URI of the BPP. Must have the same domain name as the bap_id + transaction_id: + type: string + description: This is a unique value which persists across all API calls from search through confirm + message_id: + type: string + description: This is a unique value which persists during a request / callback cycle + timestamp: + type: string + format: date-time + description: Time of request generation in RFC3339 format + key: + type: string + description: The encryption public key of the sender + max_callbacks: + description: Number of callbacks expected. If this value is -1, then there is no limit. If it is 0, then no callbacks are expected. + type: integer + minimum: -1 + ttl: + type: string + description: The duration in ISO8601 format after timestamp for which this message holds valid + required: + - domain + - action + - country + - city + - core_version + - transaction_id + - message_id + - bap_id + - bap_uri + - timestamp + Country: + description: Describes a country. + type: object + properties: + name: + type: string + description: Name of the country + code: + type: string + description: Country code as per ISO 3166-1 and ISO 3166-2 format + DecimalValue: + description: Describes a decimal value + type: string + pattern: '[+-]?([0-9]*[.])?[0-9]+' + Descriptor: + description: Describes the description of a real-world object. + type: object + properties: + name: + type: string + code: + type: string + symbol: + type: string + short_desc: + type: string + long_desc: + type: string + images: + type: array + items: + $ref: '#/components/schemas/Image' + audio: + type: string + format: uri + 3d_render: + type: string + format: uri + Dimensions: + description: Describes the dimensions of a real-world object + type: object + properties: + length: + $ref: '#/components/schemas/Scalar' + breadth: + $ref: '#/components/schemas/Scalar' + height: + $ref: '#/components/schemas/Scalar' + Document: + description: Describes a document which can be sent as a url + type: object + properties: + url: + type: string + format: uri + label: + type: string + Domain: + description: Describes the domain of an object + type: string + Duration: + description: Describes duration as per ISO8601 format + type: string + Error: + description: Describes an error object + type: object + properties: + type: + type: string + enum: + - CONTEXT-ERROR + - CORE-ERROR + - DOMAIN-ERROR + - POLICY-ERROR + - JSON-SCHEMA-ERROR + code: + type: string + description: Beckn specific error code. For full list of error codes, refer to error_codes.md in the root folder of this repo + path: + type: string + description: Path to json schema generating the error. Used only during json schema validation errors + message: + type: string + description: Human readable message describing the error + required: + - type + - code + Feedback: + description: Feedback for a service + type: object + properties: + feedback_form: + $ref: '#/components/schemas/FeedbackForm' + feedback_url: + $ref: '#/components/schemas/FeedbackUrl' + FeedbackForm: + description: Describes a feedback form that a BPP can send to get feedback from the BAP + type: array + items: + $ref: '#/components/schemas/FeedbackFormElement' + FeedbackFormElement: + description: An element in the feedback form. It can be question or an answer to the question. + type: object + properties: + id: + type: string + parent_id: + $ref: '#/components/schemas/FeedbackFormElement/properties/id' + question: + description: Specifies the question to which the answer options will be contained in the child FeedbackFormElements + type: string + answer: + description: Specifies an answer option to which the question will be in the FeedbackFormElement specified in parent_id + type: string + answer_type: + description: Specifies how the answer option should be rendered. + type: string + enum: + - radio + - checkbox + - text + FeedbackUrl: + description: Describes how a feedback URL will be sent by the BPP + type: object + properties: + url: + description: feedback URL sent by the BPP + type: string + format: uri + tl_method: + type: string + enum: + - http/get + - http/post + params: + type: object + properties: + feedback_id: + type: string + description: This value will be placed in the the $feedback_id url param in case of http/get and in the requestBody http/post requests + additionalProperties: + type: string + required: + - feedback_id + Fulfillment: + description: Describes how a single product/service will be rendered/fulfilled to the end customer + type: object + properties: + id: + type: string + description: Unique reference ID to the fulfillment of an order + type: + type: string + description: This describes the type of fulfillment + provider_id: + $ref: '#/components/schemas/Provider/properties/id' + rating: + $ref: '#/components/schemas/Rating/properties/value' + state: + $ref: '#/components/schemas/State' + tracking: + type: boolean + description: Indicates whether the fulfillment allows tracking + default: false + customer: + type: object + properties: + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + agent: + $ref: '#/components/schemas/Agent' + person: + $ref: '#/components/schemas/Person' + contact: + $ref: '#/components/schemas/Contact' + vehicle: + $ref: '#/components/schemas/Vehicle' + start: + description: Details on the start of fulfillment + type: object + properties: + location: + $ref: '#/components/schemas/Location' + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + authorization: + $ref: '#/components/schemas/Authorization' + end: + description: Details on the end of fulfillment + type: object + properties: + location: + $ref: '#/components/schemas/Location' + time: + $ref: '#/components/schemas/Time' + instructions: + $ref: '#/components/schemas/Descriptor' + contact: + $ref: '#/components/schemas/Contact' + person: + $ref: '#/components/schemas/Person' + authorization: + $ref: '#/components/schemas/Authorization' + rateable: + $ref: '#/components/schemas/Rateable' + tags: + $ref: '#/components/schemas/Tags' + Gps: + description: Describes a gps coordinate + type: string + pattern: ^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$ + Image: + description: 'Image of an object.

A url based image will look like

```uri:http://path/to/image```

An image can also be sent as a data string. For example :

```data:js87y34ilhriuho84r3i4```' + type: string + Intent: + description: Intent of a user. Used for searching for services + type: object + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + provider: + $ref: '#/components/schemas/Provider' + fulfillment: + $ref: '#/components/schemas/Fulfillment' + payment: + $ref: '#/components/schemas/Payment' + category: + $ref: '#/components/schemas/Category' + offer: + $ref: '#/components/schemas/Offer' + item: + $ref: '#/components/schemas/Item' + tags: + $ref: '#/components/schemas/Tags' + ItemQuantity: + description: Describes count or amount of an item + type: object + properties: + allocated: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + available: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + maximum: + type: object + properties: + count: + type: integer + minimum: 1 + measure: + $ref: '#/components/schemas/Scalar' + minimum: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + selected: + type: object + properties: + count: + type: integer + minimum: 0 + measure: + $ref: '#/components/schemas/Scalar' + Item: + description: Describes an item. Allows for domain extension. + type: object + properties: + id: + description: This is the most unique identifier of a service item. An example of an Item ID could be the SKU of a product. + type: string + format: '#/components/schemas/Item/properties/id' + parent_item_id: + $ref: '#/components/schemas/Item/properties/id' + descriptor: + $ref: '#/components/schemas/Descriptor' + price: + $ref: '#/components/schemas/Price' + category_id: + $ref: '#/components/schemas/Category/properties/id' + fulfillment_id: + $ref: '#/components/schemas/Fulfillment/properties/id' + rating: + $ref: '#/components/schemas/Rating/properties/value' + location_id: + $ref: '#/components/schemas/Location/properties/id' + time: + $ref: '#/components/schemas/Time' + rateable: + $ref: '#/components/schemas/Rateable' + matched: + type: boolean + related: + type: boolean + recommended: + type: boolean + tags: + $ref: '#/components/schemas/Tags' + Language: + description: indicates language code. Beckn supports country codes as per ISO 639.2 standard + type: object + properties: + code: + type: string + Location: + description: Describes the location of a runtime object. + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + gps: + $ref: '#/components/schemas/Gps' + address: + $ref: '#/components/schemas/Address' + station_code: + type: string + city: + $ref: '#/components/schemas/City' + country: + $ref: '#/components/schemas/Country' + circle: + $ref: '#/components/schemas/Circle' + polygon: + type: string + 3dspace: + type: string + time: + $ref: '#/components/schemas/Time' + Name: + type: string + description: 'Describes the name of a person in format: ./{given_name}/{honorific_prefix}/{first_name}/{middle_name}/{last_name}/{honorific_suffix}' + pattern: ^\./[^/]+/[^/]*/[^/]*/[^/]*/[^/]*/[^/]*$ + Offer: + description: Describes an offer + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + location_ids: + type: array + items: + $ref: '#/components/schemas/Location/properties/id' + category_ids: + type: array + items: + $ref: '#/components/schemas/Category/properties/id' + item_ids: + type: array + items: + $ref: '#/components/schemas/Item/properties/id' + time: + $ref: '#/components/schemas/Time' + Operator: + description: Describes the agent of a service + allOf: + - $ref: '#/components/schemas/Person' + - properties: + experience: + type: object + properties: + label: + type: string + value: + type: string + unit: + type: string + Option: + description: Describes a selectable option + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + Order: + description: Describes the details of an order + type: object + properties: + id: + type: string + description: Hash of order object without id + state: + type: string + provider: + type: object + properties: + id: + $ref: '#/components/schemas/Provider/properties/id' + locations: + type: array + maxItems: 1 + items: + type: object + properties: + id: + $ref: '#/components/schemas/Location/properties/id' + required: + - id + items: + type: array + items: + allOf: + - $ref: '#/components/schemas/Item' + - properties: + quantity: + $ref: '#/components/schemas/ItemQuantity/properties/selected' + type: object + required: + - id + add_ons: + type: array + items: + type: object + properties: + id: + $ref: '#/components/schemas/AddOn/properties/id' + required: + - id + offers: + type: array + items: + type: object + properties: + id: + $ref: '#/components/schemas/Offer/properties/id' + required: + - id + documents: + type: array + items: + $ref: '#/components/schemas/Document' + billing: + $ref: '#/components/schemas/Billing' + fulfillment: + $ref: '#/components/schemas/Fulfillment' + quote: + $ref: '#/components/schemas/Quotation' + payment: + $ref: '#/components/schemas/Payment' + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + Organization: + description: Describes an organization + type: object + properties: + name: + type: string + cred: + type: string + Page: + description: Describes a page in a search result + type: object + properties: + id: + type: string + next_id: + type: string + Payment: + description: Describes a payment + type: object + properties: + uri: + type: string + description: 'A payment uri to be called by the BAP. If empty, then the payment is to be done offline. The details of payment should be present in the params object. If ```tl_method``` = http/get, then the payment details will be sent as url params. Two url param values, ```$transaction_id``` and ```$amount``` are mandatory. And example url would be : https://www.example.com/pay?txid=$transaction_id&amount=$amount&vpa=upiid&payee=shopez&billno=1234' + format: uri + tl_method: + type: string + enum: + - http/get + - http/post + params: + type: object + properties: + transaction_id: + type: string + description: This value will be placed in the the $transaction_id url param in case of http/get and in the requestBody http/post requests + transaction_status: + type: string + amount: + $ref: '#/components/schemas/Price/properties/value' + currency: + $ref: '#/components/schemas/Price/properties/currency' + additionalProperties: + type: string + required: + - currency + type: + type: string + enum: + - ON-ORDER + - PRE-FULFILLMENT + - ON-FULFILLMENT + - POST-FULFILLMENT + status: + type: string + enum: + - PAID + - NOT-PAID + time: + $ref: '#/components/schemas/Time' + Person: + description: Describes a person. + type: object + properties: + name: + $ref: '#/components/schemas/Name' + image: + $ref: '#/components/schemas/Image' + dob: + type: string + format: date + gender: + type: string + description: Gender of something, typically a Person, but possibly also fictional characters, animals, etc. While Male and Female may be used, text strings are also acceptable for people who do not identify as a binary gender + cred: + type: string + tags: + $ref: '#/components/schemas/Tags' + Policy: + description: Describes a policy. Allows for domain extension. + type: object + properties: + id: + type: string + descriptor: + $ref: '#/components/schemas/Descriptor' + parent_policy_id: + $ref: '#/components/schemas/Policy/properties/id' + time: + $ref: '#/components/schemas/Time' + Price: + description: Describes the price of an item. Allows for domain extension. + type: object + properties: + currency: + type: string + value: + $ref: '#/components/schemas/DecimalValue' + estimated_value: + $ref: '#/components/schemas/DecimalValue' + computed_value: + $ref: '#/components/schemas/DecimalValue' + listed_value: + $ref: '#/components/schemas/DecimalValue' + offered_value: + $ref: '#/components/schemas/DecimalValue' + minimum_value: + $ref: '#/components/schemas/DecimalValue' + maximum_value: + $ref: '#/components/schemas/DecimalValue' + Provider: + description: Describes a service provider. This can be a restaurant, a hospital, a Store etc + type: object + properties: + id: + type: string + description: Id of the provider + descriptor: + $ref: '#/components/schemas/Descriptor' + category_id: + type: string + description: Category Id of the provider + rating: + $ref: '#/components/schemas/Rating/properties/value' + time: + $ref: '#/components/schemas/Time' + categories: + type: array + items: + $ref: '#/components/schemas/Category' + fulfillments: + type: array + items: + $ref: '#/components/schemas/Fulfillment' + payments: + type: array + items: + $ref: '#/components/schemas/Payment' + locations: + type: array + items: + allOf: + - $ref: '#/components/schemas/Location' + - type: object + properties: + rateable: + $ref: '#/components/schemas/Rateable' + offers: + type: array + items: + $ref: '#/components/schemas/Offer' + items: + type: array + items: + $ref: '#/components/schemas/Item' + exp: + type: string + description: Time after which catalog has to be refreshed + format: date-time + rateable: + $ref: '#/components/schemas/Rateable' + tags: + $ref: '#/components/schemas/Tags' + Quotation: + description: Describes a quote + type: object + properties: + price: + $ref: '#/components/schemas/Price' + breakup: + type: array + items: + type: object + properties: + title: + type: string + price: + $ref: '#/components/schemas/Price' + ttl: + $ref: '#/components/schemas/Duration' + Rateable: + description: If the entity can be rated or not + type: boolean + Rating: + description: Describes the rating of a person or an object. + type: object + properties: + rating_category: + description: Category of the object being rated + type: string + id: + description: Id of the object being rated + type: string + value: + description: Rating value given to the object + type: number + minimum: 0 + feedback_form: + $ref: '#/components/schemas/FeedbackForm' + feedback_id: + $ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id' + RatingAck: + type: object + properties: + feedback_ack: + description: If feedback has been recorded or not + type: boolean + rating_ack: + description: If rating has been recorded or not + type: boolean + Scalar: + description: An object representing a scalar quantity. + type: object + properties: + type: + type: string + enum: + - CONSTANT + - VARIABLE + value: + type: number + estimated_value: + type: number + computed_value: + type: number + range: + type: object + properties: + min: + type: number + max: + type: number + unit: + type: string + required: + - value + - unit + Schedule: + description: Describes a schedule + type: object + properties: + frequency: + $ref: '#/components/schemas/Duration' + holidays: + type: array + items: + type: string + format: date-time + times: + type: array + items: + type: string + format: date-time + State: + description: Describes a state + type: object + properties: + descriptor: + $ref: '#/components/schemas/Descriptor' + updated_at: + type: string + format: date-time + updated_by: + type: string + description: ID of entity which changed the state + Subscriber: + type: object + description: Any entity which wants to authenticate itself on a network. This can be a BAP, BPP, BG, BPPR or a BGR. + properties: + subscriber_id: + type: string + description: Registered domain name of the subscriber. Must have a valid SSL certificate issued by a Certificate Authority of the operating region + type: + type: string + enum: + - bap + - bpp + - bg + - bppr + - bgr + cb_url: + type: string + description: Callback URL of the subscriber. The Registry will call this URL's on_subscribe API to validate the subscriber\'s credentials + domain: + $ref: '#/components/schemas/Domain' + city: + $ref: '#/components/schemas/City/properties/code' + country: + $ref: '#/components/schemas/Country/properties/code' + signing_public_key: + type: string + description: Signing Public key of the subscriber.

Any subscriber platform (BAP, BPP, BG) who wants to transact on the network must digitally sign the ```requestBody``` using the corresponding private key of this public key and send it in the transport layer header. In case of ```HTTP``` it is the ```Authorization``` header.

The ```Authorization``` will be used to validate the signature of a BAP or BPP.

Furthermore, if an API call is being proxied or multicast by a Beckn Gateway, the BG must use it\'s signing key to digitally sign the ```requestBody``` using the corresponding private key of this public key and send it in the ```X-Gateway-Authorization``` header. + encryption_public_key: + type: string + description: Encryption public key of the BAP subscriber. Any BPP must encrypt the ```requestBody.message``` value of the ```on_search``` API using this public key. + status: + type: string + enum: + - INITIATED + - UNDER_SUBSCRIPTION + - SUBSCRIBED + - INVALID_SSL + - UNSUBSCRIBED + created: + type: string + description: Timestamp when a subscriber was added to the registry with status = INITIATED + format: date-time + updated: + type: string + format: date-time + expires: + type: string + description: Expiry timestamp in UTC derived from the ```lease_time``` of the subscriber + format: date-time + Support: + description: Customer support + type: object + properties: + type: + type: string + enum: + - order + - billing + - fulfillment + ref_id: + type: string + channels: + $ref: '#/components/schemas/Tags' + Tags: + description: A simple key-value store which is used to contain extended metadata. However, grouped tags can be created using the recommendations provided in docs/protocol-drafts/BECKN-The-Tags-Schema-Draft-01.md + additionalProperties: + type: string + Time: + description: Describes time in its various forms. It can be a single point in time; duration; or a structured timetable of operations + type: object + properties: + label: + type: string + timestamp: + type: string + format: date-time + duration: + $ref: '#/components/schemas/Duration' + range: + type: object + properties: + start: + type: string + format: date-time + end: + type: string + format: date-time + days: + type: string + description: comma separated values representing days of the week + schedule: + $ref: '#/components/schemas/Schedule' + TrackingData: + description: Describes tracking data object during live tracking of an order + $ref: '#/components/schemas/Location/properties/gps' + Tracking: + description: Describes the tracking info of an object + type: object + properties: + url: + type: string + format: uri + status: + type: string + enum: + - active + - inactive + Vehicle: + description: Describes the properties of a vehicle used in a mobility service + type: object + properties: + category: + type: string + capacity: + type: integer + make: + type: string + model: + type: string + size: + type: string + variant: + type: string + color: + type: string + energy_type: + type: string + registration: + type: string \ No newline at end of file diff --git a/docs/mobility-core/archive/0.8.0.yaml b/docs/mobility-core/archive/0.8.0.yaml new file mode 100644 index 0000000..db98ea5 --- /dev/null +++ b/docs/mobility-core/archive/0.8.0.yaml @@ -0,0 +1,825 @@ +openapi: 3.0.0 +info: + title: Beckn Mobility API + description: Extension of core API for the mobility domain + version: 0.8.0 + license: + name: CC-BY-ND + url: 'https://github.com/beckn/protocol-specifications/blob/master/LICENSE.md' +paths: + /search: + post: + tags: + - Beckn Provider Platform API + - Beckn Gateway API + description: Search by intent + requestBody: + description: BAP searches for mobility services + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + intent: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_intent.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + ack: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /catalog: + post: + tags: + - Beckn Provider Platform API + description: Fetch catalog of a service based on filters + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + id: + type: string + service_id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/service.json#/properties/id' + brand_id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/brand.json#/properties/id' + model_id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/model.json#/properties/id' + offer_id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/offer.json#/properties/id' + item_id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/item.json#/properties/id' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /select: + post: + tags: + - Beckn Provider Platform API + description: Initializing the trip + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + service: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/service.json#/properties/id' + trip: + type: object + properties: + fare_product: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_fare_product.json#/properties/id' + fare_media: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_fare_media.json#/properties/id' + travellers: + description: Details of travellers on this trip + type: array + items: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_traveller.json' + stops: + type: array + items: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_stop.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /confirm: + post: + tags: + - Beckn Provider Platform API + description: Confirm a Trip + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_order.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /checkout: + post: + tags: + - Beckn Provider Platform API + description: Send transaction id to BPP to confirm payment + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + order: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/order.json#/properties/id' + payment: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/payment.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /cancel: + post: + tags: + - Beckn Provider Platform API + description: Cancel a Service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + cancellation: + type: object + properties: + id: + type: string + reason: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/descriptor.json' + order: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/order.json#/properties/id' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /update: + post: + tags: + - Beckn Provider Platform API + description: Update a Trip + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + update_action: + type: string + enum: + - UPDATE-PICKUP + - UPDATE-DROP + - ADD-STOP + service: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/service.json#/properties/id' + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_order.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /feedback: + post: + tags: + - Beckn Provider Platform API + description: Provide feedback on a service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/feedback.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /support: + post: + tags: + - Beckn Provider Platform API + description: Fetch customer support details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/support.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /status: + post: + tags: + - Beckn Provider Platform API + description: Fetch the status of an order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + service: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/service.json#/properties/id' + order: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/order.json#/properties/id' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /track: + post: + tags: + - Beckn Provider Platform API + description: Track an item during an active service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + order: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/order.json#/properties/id' + tracking: + type: object + properties: + id: + type: string + description: ID of the trackable item + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_search: + post: + tags: + - Beckn App Platform API + - Beckn Gateway API + description: Callback response to search + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + services: + type: array + items: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_service.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_select: + post: + tags: + - Beckn App Platform API + description: Callback response to select/service. The trip object is updated with price + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + service: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/service.json#/properties/id' + trip: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_trip.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_confirm: + post: + tags: + - Beckn App Platform API + description: Callback response to confirm/service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_checkout: + post: + tags: + - Beckn App Platform API + description: Callback response to checkout. Returns a mobility order. This contains the trip object with the updated state + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_cancel: + post: + tags: + - Beckn App Platform API + description: Response to cancel service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + cancellation_id: + type: string + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_update: + post: + tags: + - Beckn App Platform API + description: Returns updated service with updated runtime object + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/mobility/schema/0.8.0/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_feedback: + post: + tags: + - Beckn App Platform API + description: Provide feedback on a service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + feedback: + type: object + properties: + service: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/service.json#/properties/id' + service_items: + type: array + items: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/item.json#/properties/id' + message: + type: string + communication: + type: string + enum: + - CHAT + - CALLBACK + - CALL + - EMAIL + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_support: + post: + tags: + - Beckn App Platform API + description: Fetch customer support details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/support.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_track: + post: + tags: + - Beckn App Platform API + description: Provide tracking info + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + tracking: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/tracking.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + /on_status: + post: + tags: + - Beckn App Platform API + description: Fetch order info + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/master/core/schema/0.8.0/error.json' \ No newline at end of file diff --git a/docs/mobility-core/archive/0.8.2.yaml b/docs/mobility-core/archive/0.8.2.yaml new file mode 100644 index 0000000..8483886 --- /dev/null +++ b/docs/mobility-core/archive/0.8.2.yaml @@ -0,0 +1,1720 @@ +openapi: 3.0.0 +info: + title: Beckn Mobility API + description: Extension of core API for the mobility domain + version: 0.8.2 + license: + name: CC-BY-ND + url: 'https://github.com/beckn/protocol-specifications/blob/master/LICENSE.md' +paths: + /search: + post: + tags: + - Beckn Provider Platform API + - Beckn Gateway API + description: Search by intent + requestBody: + description: BAP searches for Mobility services + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + intent: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_intent.json' + required: + - context + - message + examples: + On Demand Search: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: search + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + intent: + pickups: + - location: + gps: + lat: '22.374394' + lon: '77.987982' + drops: + - location: + gps: + lat: '22.858762' + lon: '77.456712' + payload: + traveller_count: 1 + Scheduled Search: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: search + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + intent: + pickups: + - location: + gps: + lat: '22.374394' + lon: '77.987982' + time: '2020-08-18 15:22:31+05:30' + drops: + - location: + gps: + lat: '22.858762' + lon: '77.456712' + time: '2020-08-18 15:23:50+05:30' + payload: + traveller_count: 1 + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + ack: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /select: + post: + tags: + - Beckn Provider Platform API + description: Select the item and build order. This can be called multiple times. The on_select callback sends an updated quotation everytime the order is updated. + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + required: + - context + - message + examples: + Provide trip details: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: select + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + trip: + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + payload: + traveller_count: 1 + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /init: + post: + tags: + - Beckn Provider Platform API + description: Initialize an Order. At this stage the BAP should send an updated order object with billing and fulfillment details if necessary + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + required: + - context + - message + examples: + Provide billing details: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: init + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: '' + items: + - id: 91e5cf38-8b07-4194-83de-40560679fd49 + trip: + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + payload: + traveller_count: 1 + billing: + customer: + name: + given_name: John Doe + email: john.doe@example.com + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /confirm: + post: + tags: + - Beckn Provider Platform API + description: Send transaction id to BPP to confirm payment + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + required: + - context + - message + examples: + Provide ALL details to confirm Trip: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: confirm + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: '' + items: + - id: 91e5cf38-8b07-4194-83de-40560679fd49 + trip: + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + payload: + traveller_count: 1 + travellers: + - name: + given_name: John Doe + phones: + - '919897866754' + billing: + customer: + name: + given_name: John Doe + email: john.doe@example.com + payment: + payer: + type: person + person: + name: + given_name: John Doe + method: CASH + amount: + value: + integral: '125' + fractional: '0' + supported_currencies: + - INR + payment_type: POST-FULFILLMENT + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /cancel: + post: + tags: + - Beckn Provider Platform API + description: Cancel a Trip + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/order.json#/properties/id' + cancellation_reason_id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/option.json#/properties/id' + required: + - context + - message + examples: + Cancel Trip: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: cancel + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: 136551c9-d543-4373-a900-1a56390f6803 + cancellation_reason_id: 8b07 + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /update: + post: + tags: + - Beckn Provider Platform API + description: Update a Trip + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + update_action: + type: string + enum: + - update_pickup + - update_drop + - update_traveller + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + required: + - context + - message + examples: + Update drop: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: update + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + update_action: update_drop + order: + id: 136551c9-d543-4373-a900-1a56390f6803 + trip: + drop: + gps: + lat: '22.514251' + lon: '77.089876' + Update Traveller(s) Details: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: update + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + update_action: update_traveller + order: + id: 136551c9-d543-4373-a900-1a56390f6803 + payload: + traveller_count: 1 + travellers: + - name: + given_name: John Doe + phones: + - '919897866754' + Update Billing Details: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: update + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + update_action: update_billing + order: + id: 136551c9-d543-4373-a900-1a56390f6803 + billing: + customer: + name: + given_name: John Doe + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /status: + post: + tags: + - Beckn Provider Platform API + description: Fetch the status of an order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + type: object + properties: + id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/order.json#/properties/id' + required: + - context + - message + examples: + Get Status of Order: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: status + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: 136551c9-d543-4373-a900-1a56390f6803 + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /track: + post: + tags: + - Beckn Provider Platform API + description: Track an order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order_id: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/order.json#/properties/id' + callback_url: + type: string + format: uri + required: + - context + - message + examples: + Track Order - Pull: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: track + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order_id: d035fabe-96a4-4935-a822-d9da52fa322e + Track Order - Push: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: track + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: '' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order_id: d035fabe-96a4-4935-a822-d9da52fa322e + callback_url: 'ws://bap.example.com/order/d035fabe-96a4-4935-a822-d9da52fa322e/track:4000' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /feedback: + post: + tags: + - Beckn Provider Platform API + description: Provide feedback on a service + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/feedback.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + ack: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /support: + post: + tags: + - Beckn Provider Platform API + description: Fetch customer support details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/support.json' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + ack: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_search: + post: + tags: + - Beckn App Platform API + - Beckn Gateway API + description: Callback response to search + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + catalog: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_catalog.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Simple Cab Service: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_search + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + catalog: + categories: + - id: ae982481-1e54-448d-8085-aae195e1bc67 + parent_category_id: null + descriptor: + name: Cab services + code: AUTORICKSHAW + items: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: Single Cab + category_id: '2' + brand_id: '1' + - id: 91e5cf38-8b07-4194-83de-40765t6r7766 + descriptor: + name: Shared Cab + category_id: '2' + brand_id: '1' + brands: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: Society Cabs Pvt Ltd + fare_products: + - id: 136551c9-d543-4373-a900-1a56390f6803 + descriptor: + name: SINGLE-JOURNEY + short_desc: Single Journey + Autorickshaw Service: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_search + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + catalog: + categories: + - id: ae982481-1e54-448d-8085-aae195e1bc67 + parent_category_id: null + descriptor: + name: Autorickshaw services + code: AUTORICKSHAW + - id: 2bc22b1b-8c75-410d-a93d-03e8c909c83e + parent_category_id: '1' + descriptor: + name: Daily commute + code: DAILY + - id: a5ac8ec5-58db-4edf-aabc-a8dc5f912212 + parent_category_id: '1' + descriptor: + name: Rental + code: RENTAL + items: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: Single Auto + category_id: '2' + brand_id: '1' + - id: 91e5cf38-8b07-4194-83de-40765t6r7766 + descriptor: + name: Share Auto + category_id: '2' + brand_id: '1' + - id: b584f536-a9c7-4e65-be56-51c9c52a13f0 + descriptor: + name: Daily Rental Auto + category_id: '3' + brand_id: '1' + brands: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: The Electric Auto Company + offers: + - id: a1e1809a-0224-4ff2-a3f8-e1342846dce1 + descriptor: + code: MONSOON + short_desc: 'Rides at 25% off till August 31st, 2020' + applies_to: BRAND + ids: + - 617c9ecf-669c-4693-b137-aa05e12e48f2 + start_date: '2020-08-15 00:00:00' + end_date: '2020-10-15 23:59:59' + - id: a1e1809a-0224-4ff2-a3f8-e1342846dce1 + descriptor: + code: INDIA74 + short_desc: 'Rides at 40% off on August 15th, 2020' + applies_to: ITEM + ids: + - 617c9ecf-669c-4693-b137-aa05e12e48f2 + start_date: '2020-08-15 00:00:00' + end_date: '2020-10-15 23:59:59' + fare_products: + - id: 136551c9-d543-4373-a900-1a56390f6803 + descriptor: + name: SINGLE-JOURNEY + short_desc: Single Journey + - id: 136551c9-d543-4373-a900-1a56390f6803 + descriptor: + name: MONTHLY-PASS + short_desc: Monthly pass + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + ack: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_search/end: + post: + tags: + - Beckn App Platform API + description: End of search results + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + examples: + End of callback: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_search/end + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + ack: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_select: + post: + tags: + - Beckn App Platform API + description: Send updated quote based on draft order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Updated quote: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_select + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: '' + items: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: Single Cab + category_id: '2' + brand_id: '1' + fare_product: + id: 136551c9-d543-4373-a900-1a56390f6803 + descriptor: + name: SINGLE-JOURNEY + short_desc: Single Journey + trip: + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + cancellation_reasons: + - id: '1' + descriptor: + short_desc: Changed my mind + - id: '2' + descriptor: + short_desc: Driver taking too long + - id: '3' + descriptor: + short_desc: Driver asked me to cancel + - id: '4' + descriptor: + short_desc: Could not contact driver + quotation: + id: 53248d02-6ba0-458e-8bd3-01e3a89e1f88 + price: + currency: INR + estimated_value: + integral: '128' + ttl: PT10M + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_init: + post: + tags: + - Beckn App Platform API + description: Send payment terms as per billing details + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Draft Order with CASH payment: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_init + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: '' + items: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: Single Cab + category_id: '2' + brand_id: '1' + fare_product: + id: 136551c9-d543-4373-a900-1a56390f6803 + descriptor: + name: SINGLE-JOURNEY + short_desc: Single Journey + cancellation_reasons: + - id: '1' + descriptor: + short_desc: Changed my mind + - id: '2' + descriptor: + short_desc: Driver taking too long + - id: '3' + descriptor: + short_desc: Driver asked me to cancel + - id: '4' + descriptor: + short_desc: Could not contact driver + trip: + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + quotation: + id: 53248d02-6ba0-458e-8bd3-01e3a89e1f88 + price: + currency: INR + estimated_value: + integral: '128' + ttl: PT5M + billing: + customer: + name: + given_name: John Doe + payment: + payer: + type: person + person: + name: + given_name: John + payee: + type: person + method: CASH + amount: + value: + integral: '125' + fractional: '0' + supported_currencies: + - INR + payment_type: POST-FULFILLMENT + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_confirm: + post: + tags: + - Beckn App Platform API + description: Callback response to checkout. Returns a mobility order. This contains the trip object with the updated state + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Confirmed Order with Trip Details: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_confirm + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: 7d770f4a-a93e-4860-9ae6-d197cd0d298e + items: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: Single Cab + category_id: '2' + brand_id: '1' + fare_product: + id: 136551c9-d543-4373-a900-1a56390f6803 + descriptor: + name: SINGLE-JOURNEY + short_desc: Single Journey + quotation: + id: 53248d02-6ba0-458e-8bd3-01e3a89e1f88 + price: + currency: INR + estimated_value: + integral: '128' + billing: + customer: + name: + given_name: John + email: john.doe@example.com + payment: + payer: + type: person + person: + name: + given_name: John + payee: + type: person + person: + name: + given_name: Jevin Samuel + method: CASH + amount: + value: + integral: '128' + fractional: '0' + supported_currencies: + - INR + payment_type: POST-FULFILLMENT + trip: + id: a5ac8ec5-58db-4edf-aabc-a8dc5f912212 + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + vehicle: + category: CAR + capacity: 4 + make: Toyota + model: Etios + variant: Liva + color: White + registration: + category: COMMERCIAL + number: KA01TA1243 + payload: + traveller_count: 1 + travellers: + - phones: + - '919897866754' + route: + edge: + path: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + duration: 22m + distance: + value: '9.5' + unit: km + driver: + name: + given_name: Jevin Samuel + rating: + value: '4.5' + unit: STARS + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_cancel: + post: + tags: + - Beckn App Platform API + description: Send cancelled order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + cancellation_id: + type: string + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Cancellation of Order without Payment: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_cancel + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: 7d770f4a-a93e-4860-9ae6-d197cd0d298e + state: + descriptor: + code: CANCELLED + updated_by: TRAVELLER + cancellation_reason_id: 8b07 + items: + - id: 91e5cf38-8b07-4194-83de-40560679fd49 + descriptor: + name: Society Cabs + category_id: '1' + price: + currency: INR + offered_value: + integral: '122' + trip: + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + vehicle: + category: CAR + capacity: 4 + make: Toyota + model: Etios + variant: Liva + color: White + registration: + type: object + properties: + category: COMMERCIAL + number: KA01TA1243 + payload: + traveller_count: 1 + travellers: + - phones: + - '919897866754' + route: + edge: + path: '' + duration: 22m + distance: + value: '9.5' + unit: km + driver: + name: + given_name: Jevin Samuel + rating: + value: '4.5' + unit: STARS + billing: + customer: + name: + given_name: John Doe + payment: + payer: + type: person + person: + name: + given_name: Ravi Prakash + payee: + type: vpa + vpa: uber@okaxis + method: UPI + amount: + value: + integral: '20' + fractional: '0' + supported_currencies: + - INR + type: CANCELLATION-CHARGES + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_update: + post: + tags: + - Beckn App Platform API + description: Returns updated order + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/b84f362f6a4965bb01891a15f17397660e25b939/mobility/v0/schema/mobility_order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Updated order: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_update + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + update_action: on_update_drop + order: + id: 7d770f4a-a93e-4860-9ae6-d197cd0d298e + items: + - id: 91e5cf38-8b07-4194-83de-40560679fd49 + descriptor: + name: Society Cabs + category_id: '1' + price: + currency: INR + offered_value: + integral: '122' + trip: + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + vehicle: + category: CAR + capacity: 4 + make: Toyota + model: Etios + variant: Liva + color: White + registration: + type: object + properties: + category: COMMERCIAL + number: KA01TA1243 + payload: + traveller_count: 1 + travellers: + - phones: + - '919897866754' + route: + edge: + path: '' + duration: 22m + distance: + value: '9.5' + unit: km + driver: + name: + given_name: Jevin Samuel + rating: + value: '4.5' + unit: STARS + billing: + customer: + name: + given_name: John Doe + payment: + payer: + type: person + person: + name: + given_name: John Doe + payee: + type: person + person: + name: + given_name: Jevin Samuel + method: CASH + amount: + value: + integral: '125' + fractional: '0' + supported_currencies: + - INR + payment_type: POST-FULFILLMENT + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_status: + post: + tags: + - Beckn App Platform API + description: Fetch order info + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + order: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/order.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Confirmed Order with Trip Details: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_confirm + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + order: + id: 7d770f4a-a93e-4860-9ae6-d197cd0d298e + items: + - id: 617c9ecf-669c-4693-b137-aa05e12e48f2 + descriptor: + name: Single Cab + category_id: '2' + brand_id: '1' + fare_product: + id: 136551c9-d543-4373-a900-1a56390f6803 + descriptor: + name: SINGLE-JOURNEY + short_desc: Single Journey + quotation: + id: 53248d02-6ba0-458e-8bd3-01e3a89e1f88 + price: + currency: INR + estimated_value: + integral: '128' + billing: + customer: + name: + given_name: John + email: john.doe@example.com + payment: + payer: + type: person + person: + name: + given_name: John + payee: + type: person + person: + name: + given_name: Jevin Samuel + method: CASH + amount: + value: + integral: '128' + fractional: '0' + supported_currencies: + - INR + payment_type: POST-FULFILLMENT + trip: + id: a5ac8ec5-58db-4edf-aabc-a8dc5f912212 + pickup: + gps: + lat: '22.374394' + lon: '77.456712' + drop: + gps: + lat: '22.514251' + lon: '77.089876' + vehicle: + category: CAR + capacity: 4 + make: Toyota + model: Etios + variant: Liva + color: White + registration: + category: COMMERCIAL + number: KA01TA1243 + payload: + traveller_count: 1 + travellers: + - phones: + - '919897866754' + route: + edge: + path: _p~iF~ps|U_ulLnnqC_mqNvxq`@ + duration: 22m + distance: + value: '9.5' + unit: km + driver: + name: + given_name: Jevin Samuel + rating: + value: '4.5' + unit: STARS + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + /on_track: + post: + tags: + - Beckn App Platform API + description: Provide tracking info + requestBody: + description: TODO + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + type: object + properties: + tracking: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/tracking.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' + examples: + Tracking Details for Pull type tracking: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_track + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + tracking: + method: pull + order: + id: 136551c9-d543-4373-a900-1a56390f6803 + state: + descriptor: + name: active + pull: + url: 'https://api.example.com/order/136551c9-d543-4373-a900-1a56390f6803/track' + Tracking Details for Push type tracking: + value: + context: + domain: MOBILITY + country: IND + city: BLR + action: on_track + core_version: 0.8.2 + domain_version: 0.8.2 + bap_uri: 'http://bap.api.example.com' + bpp_uri: 'http://bpp.api.example.com' + transaction_id: d035fabe-96a4-4935-a822-d9da52fa322e + message_id: 18a42164-c077-4659-9a0f-560a1dfebf9f + timestamp: '2020-07-15T06:43:14.653Z' + message: + tracking: + method: push + order: + id: 136551c9-d543-4373-a900-1a56390f6803 + state: + descriptor: + name: active + push: + url: 'ws://bpp.example.com/order/136551c9-d543-4373-a900-1a56390f6803/track:5000' + responses: + '200': + description: Acknowledgement of message received + content: + application/json: + schema: + type: object + properties: + context: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/context.json' + message: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/ack.json' + error: + $ref: 'https://raw.githubusercontent.com/beckn/protocol-specifications/89e04f8ffbe3ec22f1673edd3af6ca6d7da9cbc5/core/v0/schema/error.json' \ No newline at end of file diff --git a/docs/mobility-core/docs/API-Flows.md b/docs/mobility-core/docs/API-Flows.md new file mode 100644 index 0000000..012d9fd --- /dev/null +++ b/docs/mobility-core/docs/API-Flows.md @@ -0,0 +1,31 @@ +# Discovery flow + +Discovery sequence diagram is as shown below. Discovery in all domains will follow the same sequence diagram as below. + +![discovery-sequence-diagram](./images/sequence-diagram-discovery.png) + +# On Demand Cabs + +The below sequence diagram represents an order flow for on demand cabs. Here the fare will be dynamic based on the exact pickup and drop location of the customer as well as time of the journey. + +![on-demand-cabs-sequence-diagram](./images/sequence-diagram-on-demand-cabs.png) + +In the above example payment happens offline and post fulfillment. Hence the driver allocation logic was triggered as soon as the confirm call was received. + +# Public Transit + +In the case of most public transit systems, the routes will be fixed. + +There can be public transit systems where capacity is critical and you will be buying a ticket for a specific time and vehicle. An example for that can be seen below where the ticket is blocked for a certain period during which the user can complete the payment. Post the time period, if the payment is still not completed the blocked ticket will be unblocked. In the below example the BPP is collecting payment using a payment link. Water taxis are an example of this type of public transit. + +![public-transit-block-ticket-sequence-diagram](./images/sequence-diagram-public-transit-block-ticket.png) + +There can be public transit systems where the general public can book tickets just by specifying a start and end station and the ticket will be valid for any of the trips between the station. There can also be transit passes which will also not be for a specific time or vehicle. The diagram below represents such a transit system where tickets need not be blocked. In the below example the BPP is collecting payment using a payment link. Metros are an example of this type of public transit. + +![public-transit-sequence-diagram](./images/sequence-diagram-public-transit.png) + +# Parking + +Customers can search for parking spots near a location, know their capacity and availability information, and book a parking spot. In the below example the BPP collects payment using a payment link. + +![parking-sequence-diagram](./images/sequence-diagram-parking.png) diff --git a/docs/mobility-core/docs/README.md b/docs/mobility-core/docs/README.md new file mode 100644 index 0000000..d704e17 --- /dev/null +++ b/docs/mobility-core/docs/README.md @@ -0,0 +1,12 @@ +# Overview + +This folder contains all the documentation related to the mobility adaptation of beckn protocol. + +# Table of Contents + +1. Schema Adaptation for the Mobility Domain +2. Transaction Flows for Taxi Booking +3. Transaction Flows for Bus Booking +4. GTFS to Beckn Mapping +5. Standard Tags for Mobility Domain +6. Standard Tag Groups for Mobility Domain diff --git a/docs/mobility-core/docs/images/Ecosystem Architecture.png b/docs/mobility-core/docs/images/Ecosystem Architecture.png new file mode 100644 index 0000000..2038fb0 Binary files /dev/null and b/docs/mobility-core/docs/images/Ecosystem Architecture.png differ diff --git a/docs/mobility-core/docs/images/sequence-diagram-discovery.png b/docs/mobility-core/docs/images/sequence-diagram-discovery.png new file mode 100644 index 0000000..7da47c5 Binary files /dev/null and b/docs/mobility-core/docs/images/sequence-diagram-discovery.png differ diff --git a/docs/mobility-core/docs/images/sequence-diagram-on-demand-cabs.png b/docs/mobility-core/docs/images/sequence-diagram-on-demand-cabs.png new file mode 100644 index 0000000..38f6490 Binary files /dev/null and b/docs/mobility-core/docs/images/sequence-diagram-on-demand-cabs.png differ diff --git a/docs/mobility-core/docs/images/sequence-diagram-parking.png b/docs/mobility-core/docs/images/sequence-diagram-parking.png new file mode 100644 index 0000000..6b692c2 Binary files /dev/null and b/docs/mobility-core/docs/images/sequence-diagram-parking.png differ diff --git a/docs/mobility-core/docs/images/sequence-diagram-public-transit-block-ticket.png b/docs/mobility-core/docs/images/sequence-diagram-public-transit-block-ticket.png new file mode 100644 index 0000000..715f049 Binary files /dev/null and b/docs/mobility-core/docs/images/sequence-diagram-public-transit-block-ticket.png differ diff --git a/docs/mobility-core/docs/images/sequence-diagram-public-transit.png b/docs/mobility-core/docs/images/sequence-diagram-public-transit.png new file mode 100644 index 0000000..1284871 Binary files /dev/null and b/docs/mobility-core/docs/images/sequence-diagram-public-transit.png differ diff --git a/docs/mobility-core/tags/tag-groups-draft-01.md b/docs/mobility-core/tags/tag-groups-draft-01.md new file mode 100644 index 0000000..7bfd24e --- /dev/null +++ b/docs/mobility-core/tags/tag-groups-draft-01.md @@ -0,0 +1,13 @@ +# Tag Groups + +Tag groups are labels under which various tags can be grouped. In the mobility sector, Tag Groups can contains various service-specific information. Tag Groups can be standardized at a domain-level or a network-level depending upon implementer demand for standardizations. Some examples of Tag Groups are shown below. + +Note: The below list is NOT a recommended or required standard. This list will be standardized on the basis of adoption by implementers. + +## Examples: +| Example Name `(groups/[index]/descriptor.name)` | Example Code `groups/[index]/descriptor.code` | Description | +|-----------------------------------------|---------------------------------------|--------------------------------------------------------------------------------------------------------| +| Localization | locale | adapting a software product to the linguistic, cultural and technical requirements of a target market. | +| Fare Policy | fare_policy | Fare calculation rules for a mobility service | +| General Information | general_info | Any information that is applicable to a product, service, or category | +| Route Information | route_info | Information applicable to a specific route | \ No newline at end of file diff --git a/docs/mobility-core/tags/tags-draft-01.md b/docs/mobility-core/tags/tags-draft-01.md new file mode 100644 index 0000000..ce5412e --- /dev/null +++ b/docs/mobility-core/tags/tags-draft-01.md @@ -0,0 +1,107 @@ +# Tags + +Tags are used to transmit product-specific attributes. Mobility service providers can send these values to describe attributes related to fare policies, product features, commercials etc. Tags can be used by BAPs to create filters, to allow sorting, comparison etc. Tags can also be used by BPPs for catalog indexing. +## Examples + +### Item Tags with simple name-value pairs + +``` +[ + { + "id": "5777a0bf-9a08-49aa-a97d-1e5561a9622e", + "descriptor": { + "name": "Economy Plus", + }, + "price": { + "value": "175", + "currency": "INR" + }, + "tags": { + "groups/1/descriptor/name": "Daytime Charges", + "groups/1/display": true, + "groups/1/list/1/descriptor/name": "Min Fare upto 2 km", + "groups/1/list/1/value": "₹ 30 upto 2 km", + "groups/1/list/2/descriptor/name": "Rate above Min. Fare", + "groups/1/list/2/value": "₹15 / km", + "groups/1/list/3/descriptor/name": "Driver Pickup Charges", + "groups/1/list/3/value": "₹ 10", + "groups/1/list/4/descriptor/name": "Nominal Fare", + "groups/1/list/4/descriptor/short_desc": "Driver may quote extra to cover for traffic, chance of return trip, etc.", + "groups/1/list/4/value": "₹ 10", + "groups/1/list/5/descriptor/name": "Waiting Charges", + "groups/1/list/5/descriptor/short_desc": "Driver may quote extra to cover for traffic, chance of return trip, etc.", + "groups/1/list/5/value": "₹ 0 / min" + } + } +] +``` + +### Item Tags with standardized (codified) name-value pairs + +``` +[ + { + "id": "5777a0bf-9a08-49aa-a97d-1e5561a9622e", + "descriptor": { + "name": "Economy", + "code": "RIDE" + }, + "price": { + "value": "175", + "currency": "INR" + }, + "tags": { + "groups/1/descriptor/name": "Daytime Charges", + "groups/1/descriptor/code": "fare_policy", + "groups/1/display": true, + "groups/1/list/1/descriptor/name": "Min Fare upto 2 km", + "groups/1/list/1/value": "₹ 30 upto 2 km", + "groups/1/list/2/descriptor/name": "Rate above Min. Fare", + "groups/1/list/2/descriptor/code": "extra_fare", + "groups/1/list/2/value": "₹15 / km", + "groups/1/list/3/descriptor/name": "Driver Pickup Charges", + "groups/1/list/3/descriptor/code": "pickup_charges", + "groups/1/list/3/value": "₹ 10", + "groups/1/list/4/descriptor/name": "Nominal Fare", + "groups/1/list/4/descriptor/short_desc": "Driver may quote extra to cover for traffic, chance of return trip, etc.", + "groups/1/list/4/descriptor/code": "nominal_fare", + "groups/1/list/4/value": "₹ 10", + "groups/1/list/5/descriptor/name": "Waiting Charges", + "groups/1/list/5/descriptor/short_desc": "Driver may quote extra to cover for traffic, chance of return trip, etc.", + "groups/1/list/5/descriptor/code": "waiting_charges", + "groups/1/list/5/value": "₹ 0 / min" + } + } +] +``` + +**Note:** The above tag list is NOT a recommended or required standard. This list will be standardized on the basis of adoption by implementers across multiple networks. + + +## Contributing to Tags +Tags are standardized by the Mobility Working Group on the basis of community adoption. At the current moment, there are no standard tags recommended by the working group. Eventually a tag list will be created that looks like the table below. Implementers are free to submit tags for consideration via a PR with a row added to the table below along with an attached report on adoption of that tag across the implementer community. It is recommended for contributors to do extensive research on adoption before submitting the PR. + + +## Tag List + +| Name | Code | Description | Type | Format | Examples | +|-----------------------|------------------------|--------------------------------------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| (name) | (code) | (description) | (type) | (format) | (examples) | + + +### An example Tag List with standardizations (NOT A RECOMMENDATION) + +| Name | Code | Description | Type | Format | Examples | +|-----------------------|------------------------|--------------------------------------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| +| Language | lang | Language spoken by a person or entity | string | ISO 639-2 language code | eng, hin | +| Base Fare | min_fare | Minimum fare that has to be paid for a mobility service | string | | 30 iNR | +| Minimum Fare Distance | min_fare_dist | Distance upto which minimum fare is to be paid | string | | 1 km | +| Fare per distance | fare_per_dist | Fare applicable for every unit of distance travelled | string | / | 12 INR / km | +| Fare per time | fare_per_time | Fare applicable for every unit of time travelled | string | /