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))"'
+ 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)"'
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:
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))"'
+ 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(signing string)"'
+
schemas:
Ack:
- description: Describes the ACK response
+ description: Describes the acknowledgement message a BPP, BAP or BG sends as response to any beckn API calls. This can represent the acknowledged or not acknowledged status response. This has one property status This schema is used in the response of all the beckn API calls This is used to convey the acknowledgement status of a beckn API call received by a network participant. If the network participant received the API call successfuly and has validated the request is as per protocol specifications and signature verified it can send back an ACK as status. Or else it will send NACK as status. The validation done at this point is only technical in nature (validating if the schema is as per specification, if the signature and caller is valid, if the endpoint itself is implemented) and no functional validation (as per business logic) needs to be done before sending this.
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
+ description: Describe the status of the ACK response. If schema validation passes, status is ACK else it is NACK
required:
- status
+
AddOn:
- description: Describes an add-on
+ description: Describes an ancillary item (products/services) sold to the buyer of a main product or service This has properties like id,descriptor,price This schema is used in the addons array in the Order schema object. This does not exist independently in a catalog and is always associated with an item.
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 '
+ description: "ID of the add-on"
descriptor:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
price:
- $ref: '#/components/schemas/Price'
+ $ref: "#/components/schemas/Price"
+
Address:
- description: Describes an address
+ description: Describes the postal address of a location.
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:
+ full:
type: string
- description: Country name
- area_code:
+ description: Full unformatted address of a location.
+ format:
type: string
- description: 'Area code. This can be Pincode, ZIP code or any equivalent'
+ description: Defines the address formatting standard
+
Agent:
- description: Describes an order executor
- allOf:
- - $ref: '#/components/schemas/Person'
- - $ref: '#/components/schemas/Contact'
- - type: object
- properties:
- rateable:
- $ref: '#/components/schemas/Rateable'
+ description: Describes the direct performer, driver or executor of the fulfillment of an order. In the healthcare domain it can be a doctor while in the mobility domain it can be a taxi driver.
This is used in the discovery stage when the BPP wants to convey details of the person who will be fulfilling the order so that the customer can make an informed decision about the product or service they need to purchase
This is used in the fulfillment stage when the BPP assigns an agent to fulfill the order post confirmation
+ properties:
+ person:
+ $ref: "#/components/schemas/Person"
+ contact:
+ $ref: "#/components/schemas/Contact"
+ organization:
+ $ref: "#/components/schemas/Organization"
+
Authorization:
- description: Describes an authorization mechanism
+ description: Describes an authorization mechanism used in the order lifecycle. Can be used to attach authorization token to any interaction. This has properties like type, token, valid_from, valid_to and status This is used in the following situations.
Typically in the fulfillment stage when BPP sends an authorization mechanism that the BAP needs to use for authorizing any interaction
This is used to allow a user to authorize the validity of their order with a person executing the order so that fulfillment of the order can start/end. This is also used as proof of presence of the customer so that a person executing the order can start/end the fulfillment. This can be used by the user to start fulfillment by providing the token as proof of presence. This can be used by the user as a proof of purchase of service to a person executing the order at start/end of fulfillment This can be used by the user to end fulfillment by providing the token as proof of completion of service.
The authorization mechanism can be used in several ways to authorize the start or end of a fulfillment. In the mobility domain a BPP which renders taxi services may give an OTP to the BAP after confirming the order. The end user will give the OTP to the taxi driver as proof of presence to start the taxi service In the logistics domain a BPP that renders courier services can give an OTP to the BAP while the delivery service is being performed by a delivery agent. The end user will give the OTP to the delivery agent so that they can mark the package as successfuly delivered. In the mobility domain a public transit BPP can send a signed QR code string to the BAP. The BAP will render it as a QR code which the end user will present to a ticketing employee who can read the QR code using their device and authenticate the validity of the ticket
type: object
properties:
- type:
+ type:
type: string
description: Type of authorization mechanism used
token:
@@ -1420,131 +2678,143 @@ components:
description: Token used for authorization
valid_from:
type: string
- format: date-time
+ format: date-time
description: Timestamp in RFC3339 format from which token is valid
valid_to:
type: string
- format: date-time
+ 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
+ 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: Personal details of the customer needed for billing.
+ description: Name of the billable entity
type: string
organization:
- $ref: '#/components/schemas/Organization'
+ $ref: "#/components/schemas/Organization"
address:
- $ref: '#/components/schemas/Address'
+ description: The address of the billable entity
+ allOf:
+ - $ref: "#/components/schemas/Address"
email:
type: string
format: email
phone:
type: string
time:
- $ref: '#/components/schemas/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
+ description: ID of the billable entity as recognized by the taxation authority
+
Cancellation:
- description: Describes the ACK response
+ description: Describes a cancellation event
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'
+ $ref: "#/components/schemas/Person"
+ reason:
+ $ref: "#/components/schemas/Option"
additional_description:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
+
+ CancellationTerm:
+ description: Describes the cancellation policy of an item or an order. This can be referenced at an item or order level.
+ type: object
+ properties:
+ refund_eligible:
+ description: Indicates if cancellation will result in a refund
+ type: boolean
+ return_eligible:
+ description: Indicates if cancellation will result in a return to origin
+ type: boolean
+ replacement_eligible:
+ description: Indicates if cancellation will result in a replacement
+ type: boolean
+ fulfillment_state:
+ description: The state of fulfillment during which these terms are applicable.
+ allOf:
+ - $ref: "#/components/schemas/State"
+ cancel_by:
+ description: Information related to the time of cancellation.
+ allOf:
+ - $ref: "#/components/schemas/Time"
+ cancellation_fee:
+ $ref: "#/components/schemas/Fee"
+ external_ref:
+ $ref: "#/components/schemas/MediaFile"
+
Catalog:
- description: Describes a BPP 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:
- bpp/descriptor:
- $ref: '#/components/schemas/Descriptor'
- bpp/categories:
+ descriptor:
+ $ref: "#/components/schemas/Descriptor"
+ categories:
type: array
items:
- $ref: '#/components/schemas/Category'
- bpp/fulfillments:
+ $ref: "#/components/schemas/Category"
+ fulfillments:
type: array
items:
- $ref: '#/components/schemas/Fulfillment'
- bpp/payments:
+ $ref: "#/components/schemas/Fulfillment"
+ payments:
type: array
items:
- $ref: '#/components/schemas/Payment'
- bpp/offers:
+ $ref: "#/components/schemas/Payment"
+ offers:
type: array
items:
- $ref: '#/components/schemas/Offer'
- bpp/providers:
+ $ref: "#/components/schemas/Offer"
+ providers:
type: array
items:
- $ref: '#/components/schemas/Provider'
+ $ref: "#/components/schemas/Provider"
exp:
type: string
description: Time after which catalog has to be refreshed
format: date-time
+
Category:
- description: Describes a category
+ description: Describes a type or division of providers or items regarded as having one or more shared characteristics This has properties like id,parent_category_id,descriptor,time,tags This is used in the following situations.
This is typically used in the discovery stage when the BPP wants to categorize the products or services in its catalog as additional information about the product or service
This is typically used in the discovery stage when the BPP wants to categorize the products or services in its catalog because the price of the same product or service can change based on the category
This is typically used in the discovery stage when the BPP wants to categorize the products or services in its catalog as additional information about the product or service
type: object
properties:
id:
type: string
- description: Unique id of the category
+ description: ID of the category
parent_category_id:
- $ref: '#/components/schemas/Category/properties/id'
+ $ref: "#/components/schemas/Category/properties/id"
descriptor:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
time:
- $ref: '#/components/schemas/Time'
+ $ref: "#/components/schemas/Time"
+ ttl:
+ description: Time to live for an instance of this schema
tags:
- $ref: '#/components/schemas/Tags'
+ $ref: "#/components/schemas/Tags"
+
Circle:
- description: Describes a circular area on the map
+ description: Describes a circular region of a specified radius centered at a specified GPS coordinate. This has properties like gps,radius This is used when a circular area needs to be represented as a location.
type: object
properties:
gps:
- $ref: '#/components/schemas/Gps'
+ $ref: "#/components/schemas/Gps"
radius:
- $ref: '#/components/schemas/Scalar'
+ $ref: "#/components/schemas/Scalar"
required:
- gps
- radius
+
City:
- description: Describes a city
+ description: Describes a city or a town This has properties like name,code
type: object
properties:
name:
@@ -1553,55 +2823,57 @@ components:
code:
type: string
description: City code
+
+ ConfirmationTerms:
+ description: Describes the terms required to be fulfilled confirm an order
+ type: object
+ properties:
+ req_media:
+ type: array
+ items:
+ $ref: "#/components/schemas/MediaFile"
+ req_formdata:
+ $ref: "#/components/schemas/Form"
+ req_formdata_url:
+ type: string
+ format: uri
+
Contact:
+ description: Describes the contact information of an entity including phone number or an email ID This has properties like phone,email,tags This is used to allow the BPP or BAP to send contact details of a person.
type: object
properties:
+ name:
+ $ref: "#/components/schemas/Name"
+ address:
+ $ref: "#/components/schemas/Address"
phone:
type: string
email:
type: string
+ jcard:
+ type: object
+ description: A Jcard object as per draft-ietf-jcardcal-jcard-03 specification
tags:
- $ref: '#/components/schemas/Tags'
+ $ref: "#/components/schemas/Tags"
+
Context:
- description: Describes a beckn message context
+ description: Describes the context header of the message being sent. This has properties like domain,country,city,action,code_version,bap_id,bap_uri,bpp_id,bpp_uri,transaction_id,message-id,timestamp,key,ttl
type: object
properties:
domain:
- $ref: '#/components/schemas/Domain'
+ $ref: "#/components/schemas/Domain"
country:
- $ref: '#/components/schemas/Country/properties/code'
+ $ref: "#/components/schemas/Country/properties/code"
city:
- $ref: '#/components/schemas/City/properties/code'
+ $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
@@ -1609,7 +2881,6 @@ components:
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
@@ -1642,8 +2913,9 @@ components:
- bap_id
- bap_uri
- timestamp
+
Country:
- description: Describes a country.
+ description: Describes a country. This has properties like name,code
type: object
properties:
name:
@@ -1652,49 +2924,75 @@ components:
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"
+ issuer:
+ type: string
+ issuance_date:
+ type: string
+ format: date-time
+ credential_subject:
+ type: object
+ properties:
+ id:
+ type: string
+ additionalProperties:
+ type: object
+ credential_schema:
+ type: object
+ properties:
+ id:
+ type: string
+ type:
+ type: string
+
DecimalValue:
- description: Describes a decimal value
+ description: Describes a numerical value in decimal form
type: string
- pattern: '[+-]?([0-9]*[.])?[0-9]+'
+ pattern: "[+-]?([0-9]*[.])?[0-9]+"
Descriptor:
- description: Describes the description of a real-world object.
+ description: Describes the description used to describe or identify a real world object This has properties like name,code,symbol,short_desc,long_desc,images,audio,3d_render
type: object
properties:
name:
type: string
code:
type: string
- symbol:
- 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'
- audio:
- type: string
- format: uri
- 3d_render:
- type: string
- format: uri
+ $ref: "#/components/schemas/Image"
- 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
+ description: Describes a piece of written or printed matter in electronic form that provides information or evidence or that serves as an official record. This will be given as a URL. In the case of sensitive information being exchanged, such documents may be encrypted and additional authorization such as an an OTP or password may be implemented when the URL is accessed. This has properties like url,label This is used in the following situations.
This is typically used in the order stage if any documents from the user are needed by the BPP to confirm the order
This is typically used in the fulfilment and post fulfillment stage if the BPP needs to send any documents related to the order to the user
This is used to allow documents to be exchanged between the BAP and the BPP
type: object
properties:
url:
@@ -1702,9 +3000,9 @@ components:
format: uri
label:
type: string
-
+
Domain:
- description: Describes the domain of an object
+ description: Described the sector, industry or field for which the current beckn transaction is for. Examples of domains are mobility, local retail, logistics etc. Each network can choose its own codes for specifying a domain within the network.
type: string
Duration:
@@ -1712,7 +3010,7 @@ components:
type: string
Error:
- description: Describes an error object
+ 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 has properties like type,code,path,message This schema is used in the response of all the beckn API calls as well as the callback beckn APIs This is used to return the details of an error that happened while processing a beckn API call received by a network participant.
type: object
properties:
type:
@@ -1725,7 +3023,7 @@ components:
- 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'
+ description: "Beckn specific error code. 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
@@ -1736,72 +3034,37 @@ components:
- 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.
+ Fee:
type: object
+ description: A fee applied on a particular entity
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
+ percentage:
+ description: Percentage of a value
+ allOf:
+ - $ref: "#/components/schemas/DecimalValue"
+ amount:
+ description: A fixed amount applied on the total order value
+ allOf:
+ - $ref: "#/components/schemas/Price"
+
+ 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: feedback URL sent by the BPP
+ 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 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 BAP can process the form data and reproduce it as per the standard specified in the form.
type: string
format: uri
- tl_method:
+ data:
+ description: Sometimes, the BPP can directly send the form content instead of a URL. This content will again follow the mime_type field for processing. Typically forms should be sent as an html string starting with tags. The application must render this form after removing any css or javascript code if necessary. The `action` attribute in the form should have a url where the form needs to be submitted.
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
-
-
-
+ 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
+
Fulfillment:
- description: Describes how a single product/service will be rendered/fulfilled to the end customer
+ description: Describes how a single product/service will be rendered/fulfilled to the end customer This has properties like id,type,provider_id,rating,state,tracking, customer,agent,person,contact,vehicle,start,end,rateable,tags This is used in the following situations.
This is typically used in the discovery stage when the BPP sends the fulfillment terms to the BAP
This is typically used in the order stage when the BPP sends the fulfillment terms to the BAP
This is typically used in the fulfillment stage when the BPP sends the status and current details of fulfillment to the BAP
An image can also be sent as a data string. For example :
```data:js87y34ilhriuho84r3i4```'
+ 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
+ description: Intent of a user. Used in the discovery stage for declaring the intent of the user. BAP can declare the intent of the consumer including
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:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
provider:
- $ref: '#/components/schemas/Provider'
+ $ref: "#/components/schemas/Provider"
fulfillment:
- $ref: '#/components/schemas/Fulfillment'
+ $ref: "#/components/schemas/Fulfillment"
payment:
- $ref: '#/components/schemas/Payment'
+ $ref: "#/components/schemas/Payment"
category:
- $ref: '#/components/schemas/Category'
+ $ref: "#/components/schemas/Category"
offer:
- $ref: '#/components/schemas/Offer'
+ $ref: "#/components/schemas/Offer"
item:
- $ref: '#/components/schemas/Item'
+ $ref: "#/components/schemas/Item"
tags:
- $ref: '#/components/schemas/Tags'
-
+ $ref: "#/components/schemas/Tags"
+
ItemQuantity:
- description: Describes count or amount of an item
+ description: Describes the count or amount of an item This has properties like allocated,available,maximum,minimum,selected
type: object
properties:
allocated:
@@ -1910,221 +3195,263 @@ components:
type: integer
minimum: 0
measure:
- $ref: '#/components/schemas/Scalar'
+ $ref: "#/components/schemas/Scalar"
available:
type: object
+ description: This represents the exact quantity available for purchase of the item. The buyer can only purchase multiples of this
properties:
count:
type: integer
minimum: 0
measure:
- $ref: '#/components/schemas/Scalar'
+ $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'
+ $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'
+ $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'
+ $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 an item. Allows for domain extension.
+ description: Describes a product or a service offered to the end consumer by the provider. In the mobility domain item can represent a fare product like one way journey while in the logistics domain it can represent the delivery service offering while in the local retail domain it can represent a product like a grocery item. This has properties like id,parent_item_id,descriptor,price,category_id,fulfillment_id,rating,time,location_id,time,rateable,matched,related,recommended, tags This is used in the following situations.
This is typically used in the discovery stage when the BPP sends the catalog of products or services it offers to the BAP in the items array
This is typically used in the order stage when the BAP sends the details of the item the user wants to purchase
This is typically used in the fulfillment stage when the BPP/BAP sends the order object containing the details of the products or services purchased in the order
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.
+ description: This is the most unique identifier of a service item.
type: string
- format: '#/components/schemas/Item/properties/id'
parent_item_id:
- $ref: '#/components/schemas/Item/properties/id'
+ $ref: "#/components/schemas/Item/properties/id"
descriptor:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
+ manufacturer:
+ $ref: "#/components/schemas/Organization"
price:
- $ref: '#/components/schemas/Price'
+ $ref: "#/components/schemas/Price"
+ quantity:
+ $ref: "#/components/schemas/ItemQuantity"
category_id:
- $ref: '#/components/schemas/Category/properties/id'
+ $ref: "#/components/schemas/Category/properties/id"
fulfillment_id:
- $ref: '#/components/schemas/Fulfillment/properties/id'
+ $ref: "#/components/schemas/Fulfillment/properties/id"
rating:
- $ref: '#/components/schemas/Rating/properties/value'
+ $ref: "#/components/schemas/Rating/properties/value"
location_id:
- $ref: '#/components/schemas/Location/properties/id'
+ $ref: "#/components/schemas/Location/properties/id"
+ payment_id:
+ $ref: "#/components/schemas/Payment/properties/id"
+ cancellation_terms:
+ type: array
+ items:
+ $ref: "#/components/schemas/CancellationTerm"
+ return_terms:
+ type: array
+ items:
+ $ref: "#/components/schemas/ReturnTerm"
+ replacement_terms:
+ type: array
+ items:
+ $ref: "#/components/schemas/ReplacementTerm"
+ xinput_required:
+ $ref: "#/components/schemas/XInput"
time:
- $ref: '#/components/schemas/Time'
- rateable:
- $ref: '#/components/schemas/Rateable'
+ $ref: "#/components/schemas/Time"
+ rating_policy:
+ $ref: "#/components/schemas/RatingPolicy"
matched:
type: boolean
related:
type: boolean
recommended:
type: boolean
+ ttl:
+ description: Time to live for an instance of this schema
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
+ $ref: "#/components/schemas/Tags"
+ domain_extns:
+ type: object
+ properties:
+ domain:
+ type: string
+ additionalProperties:
+ type: string
+
Location:
- description: Describes the location of a runtime object.
+ description: Describes the location of something, for example, where an event is happening, where a store is located, or where an action takes place This has properties like id,descriptor,gps,address,station code,city,country,circle,polygon,3d space,time
type: object
properties:
id:
type: string
descriptor:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
gps:
- $ref: '#/components/schemas/Gps'
+ $ref: "#/components/schemas/Gps"
address:
- $ref: '#/components/schemas/Address'
- station_code:
- type: string
+ $ref: "#/components/schemas/Address"
city:
- $ref: '#/components/schemas/City'
+ $ref: "#/components/schemas/City"
country:
- $ref: '#/components/schemas/Country'
+ $ref: "#/components/schemas/Country"
circle:
- $ref: '#/components/schemas/Circle'
+ $ref: "#/components/schemas/Circle"
polygon:
type: string
3dspace:
type: string
time:
- $ref: '#/components/schemas/Time'
+ $ref: "#/components/schemas/Time"
+ updated_at:
+ type: string
+ format: date-time
+
+ MediaFile:
+ 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
+
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: '^\./[^/]+/[^/]*/[^/]*/[^/]*/[^/]*/[^/]*$'
+ description: "Describes the name of a person"
Offer:
- description: Describes an offer
+ description: Describes how a product or a service will be rendered at a reduced price to the user This has properties like id,descriptor,location_ids,category_ids,item_ids,time
type: object
properties:
id:
type: string
descriptor:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
location_ids:
type: array
items:
- $ref: '#/components/schemas/Location/properties/id'
+ $ref: "#/components/schemas/Location/properties/id"
category_ids:
type: array
items:
- $ref: '#/components/schemas/Category/properties/id'
+ $ref: "#/components/schemas/Category/properties/id"
item_ids:
type: array
items:
- $ref: '#/components/schemas/Item/properties/id'
+ $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
+ $ref: "#/components/schemas/Time"
Option:
- description: Describes a selectable option
+ description: Describes a selectable option This has properties like id,description
type: object
properties:
id:
type: string
descriptor:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
+
Order:
- description: Describes the details of an order
+ description: Describes an order which contains the terms, details, status and identifier of a transaction between a BAP and a BPP. This is usually an exchange of goods or services for money. This has properties like id,state,provider,items,add_ons,offers,documents,billings,fulfillment,quote,payment,created_at,updated_at This is used in the following situations.
This is typically used in the order stage when the BAP sends the details of the order it wishes to create
This is typically used in the fulfillment stage when the BPP/BAP sends the order details
type: object
properties:
id:
type: string
- description: Hash of order object without id
- state:
- 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
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
+ description: Details of the provider whose catalog items have been selected.
+ allOf:
+ - $ref: "#/components/schemas/Provider"
items:
type: array
items:
- type: object
- properties:
- id:
- $ref: '#/components/schemas/Item/properties/id'
- quantity:
- $ref: '#/components/schemas/ItemQuantity/properties/selected'
- required:
- - id
+ $ref: "#/components/schemas/Item"
add_ons:
type: array
items:
- type: object
- properties:
- id:
- $ref: '#/components/schemas/AddOn/properties/id'
- required:
- - id
+ $ref: "#/components/schemas/AddOn"
offers:
type: array
items:
- type: object
- properties:
- id:
- $ref: '#/components/schemas/Offer/properties/id'
- required:
- - id
+ $ref: "#/components/schemas/Offer"
documents:
type: array
items:
- $ref: '#/components/schemas/Document'
+ $ref: "#/components/schemas/Document"
billing:
- $ref: '#/components/schemas/Billing'
- fulfillment:
- $ref: '#/components/schemas/Fulfillment'
+ $ref: "#/components/schemas/Billing"
+ fulfillments:
+ type: array
+ items:
+ $ref: "#/components/schemas/Fulfillment"
+ cancellation:
+ $ref: "#/components/schemas/Cancellation"
+ cancellation_terms:
+ type: array
+ items:
+ $ref: "#/components/schemas/CancellationTerm"
+ return_terms:
+ type: array
+ items:
+ $ref: "#/components/schemas/ReturnTerm"
+ replacement_terms:
+ type: array
+ items:
+ $ref: "#/components/schemas/ReplacementTerm"
+ refund_terms:
+ type: array
+ items:
+ $ref: "#/components/schemas/RefundTerm"
+ rating_policy:
+ $ref: "#/components/schemas/RatingPolicy"
quote:
- $ref: '#/components/schemas/Quotation'
- payment:
- $ref: '#/components/schemas/Payment'
+ $ref: "#/components/schemas/Quotation"
+ payments:
+ type: array
+ items:
+ $ref: "#/components/schemas/Payment"
created_at:
type: string
format: date-time
@@ -2133,53 +3460,44 @@ components:
format: date-time
Organization:
- description: Describes an organization
type: object
properties:
- name:
- type: string
- cred:
- type: string
+ descriptor:
+ $ref: "#/components/schemas/Descriptor"
+ address:
+ $ref: "#/components/schemas/Address"
+ contact:
+ $ref: "#/components/schemas/Contact"
- Page:
- description: Describes a page in a search result
+ Payment:
+ description: Describes the terms of settlement between the BAP and the BPP for a single transaction. When instantiated, this object contains
the amount that has to be settled,
The payment destination destination details
When the settlement should happen, and
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
- next_id:
- type: string
-
-
- Payment:
- description: Describes a payment
- type: object
- properties:
- uri:
+ 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 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'
+ 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. 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'
+ $ref: "#/components/schemas/Price/properties/value"
currency:
- $ref: '#/components/schemas/Price/properties/currency'
- additionalProperties:
- type: string
- required:
- - currency
+ $ref: "#/components/schemas/Price/properties/currency"
+ bank_code:
+ type: string
+ bank_account_number:
+ type: string
+ virtual_payment_address:
+ type: string
type:
type: string
enum:
@@ -2193,167 +3511,211 @@ components:
- PAID
- NOT-PAID
time:
- $ref: '#/components/schemas/Time'
+ $ref: "#/components/schemas/Time"
Person:
- description: Describes a person.
+ description: Describes a person as any individual This has the properties like name,image,dob,gender,cred,tags
type: object
properties:
+ id:
+ type: string
+ description: Describes the identity of the person
name:
- $ref: '#/components/schemas/Name'
+ $ref: "#/components/schemas/Name"
image:
- $ref: '#/components/schemas/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
+ 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"
+ creds:
+ type: array
+ items:
+ $ref: "#/components/schemas/Credential"
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'
+ $ref: "#/components/schemas/Tags"
Price:
- description: Describes the price of an item. Allows for domain extension.
+ description: Describes the price of a product or service This has properties like currency_value,estimated_value,computed_value,listed_value,offered_value,Minimum_value,maximum_value
type: object
properties:
currency:
type: string
value:
- $ref: '#/components/schemas/DecimalValue'
+ $ref: "#/components/schemas/DecimalValue"
estimated_value:
- $ref: '#/components/schemas/DecimalValue'
+ $ref: "#/components/schemas/DecimalValue"
computed_value:
- $ref: '#/components/schemas/DecimalValue'
+ $ref: "#/components/schemas/DecimalValue"
listed_value:
- $ref: '#/components/schemas/DecimalValue'
+ $ref: "#/components/schemas/DecimalValue"
offered_value:
- $ref: '#/components/schemas/DecimalValue'
+ $ref: "#/components/schemas/DecimalValue"
minimum_value:
- $ref: '#/components/schemas/DecimalValue'
+ $ref: "#/components/schemas/DecimalValue"
maximum_value:
- $ref: '#/components/schemas/DecimalValue'
-
+ $ref: "#/components/schemas/DecimalValue"
+
Provider:
- description: 'Describes a service provider. This can be a restaurant, a hospital, a Store etc'
+ description: Describes a service provider. This can be a restaurant, a hospital, a Store etc This has properties like id,descriptor,category_id,rating,time,categories,fulfillment,payments,locations,offers,items,exp,rateables,tags
type: object
properties:
id:
type: string
- description: 'Id of the provider'
+ description: "Id of the provider"
descriptor:
- $ref: '#/components/schemas/Descriptor'
+ $ref: "#/components/schemas/Descriptor"
category_id:
type: string
- description: 'Category Id of the provider'
+ description: "Category Id of the provider"
rating:
- $ref: '#/components/schemas/Rating/properties/value'
+ $ref: "#/components/schemas/Rating/properties/value"
time:
- $ref: '#/components/schemas/Time'
+ $ref: "#/components/schemas/Time"
categories:
type: array
items:
- $ref: '#/components/schemas/Category'
+ $ref: "#/components/schemas/Category"
fulfillments:
type: array
items:
- $ref: '#/components/schemas/Fulfillment'
+ $ref: "#/components/schemas/Fulfillment"
payments:
type: array
items:
- $ref: '#/components/schemas/Payment'
+ $ref: "#/components/schemas/Payment"
locations:
type: array
items:
allOf:
- - $ref: '#/components/schemas/Location'
- - type: object
- properties:
- rateable:
- $ref: '#/components/schemas/Rateable'
+ - $ref: "#/components/schemas/Location"
+ - type: object
+ properties:
+ rateable:
+ $ref: "#/components/schemas/Rateable"
offers:
type: array
items:
- $ref: '#/components/schemas/Offer'
+ $ref: "#/components/schemas/Offer"
items:
type: array
items:
- $ref: '#/components/schemas/Item'
+ $ref: "#/components/schemas/Item"
exp:
type: string
description: Time after which catalog has to be refreshed
format: date-time
rateable:
- $ref: '#/components/schemas/Rateable'
+ $ref: "#/components/schemas/Rateable"
+ ttl:
+ description: Time to live in seconds for an instance of this schema
+ type: integer
tags:
- $ref: '#/components/schemas/Tags'
+ $ref: "#/components/schemas/Tags"
Quotation:
- description: Describes a quote
+ 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:
price:
- $ref: '#/components/schemas/Price'
+ $ref: "#/components/schemas/Price"
breakup:
type: array
items:
type: object
properties:
+ item:
+ $ref: "#/components/schemas/Item"
title:
type: string
price:
- $ref: '#/components/schemas/Price'
+ $ref: "#/components/schemas/Price"
ttl:
- $ref: '#/components/schemas/Duration'
+ $ref: "#/components/schemas/Duration"
Rateable:
- description: If the entity can be rated or not
+ description: Describes if the entity can be rated or not
type: boolean
Rating:
- description: Describes the rating of a person or an object.
+ description: Describes the rating of a person or an object This has properties like rating category,id,value, feedback_id,feedback_form
type: object
properties:
rating_category:
- description: Category of the object being rated
+ 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
- type: number
- minimum: 0
- feedback_form:
- $ref: '#/components/schemas/FeedbackForm'
- feedback_id:
- $ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id'
-
- RatingAck:
+ type: string
+
+ RatingPolicy:
+ description: Describes the rating policy of an object. This can be set in various places to indicate whether the object can be rated or not.
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
+ properties:
+ rateable:
type: boolean
+ default: false
+ range:
+ type: array
+ items:
+ type: object
+ properties:
+ value:
+ type: string
+ descriptor:
+ $ref: "#/components/schemas/Descriptor"
+
+ RefundTerm:
+ type: object
+ properties:
+ refund_within:
+ description: Time within which refund will be processed.
+ allOf:
+ - $ref: "#/components/schemas/Time"
+ external_ref:
+ $ref: "#/components/schemas/MediaFile"
+
+ ReplacementTerm:
+ type: object
+ properties:
+ 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:
+ return_within:
+ 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"
+ fulfillment_managed_by:
+ enum:
+ - CUSTOMER
+ - PROVIDER
+ return_location:
+ $ref: "#/components/schemas/Location"
+ external_ref:
+ $ref: "#/components/schemas/MediaFile"
Scalar:
- description: An object representing a scalar quantity.
+ description: Describes a scalar quantity. This has properties like value, estimated_value, computed_value,range, unit
type: object
properties:
type:
@@ -2362,30 +3724,27 @@ components:
- CONSTANT
- VARIABLE
value:
- type: number
+ $ref: "#/components/schemas/DecimalValue"
estimated_value:
- type: number
+ $ref: "#/components/schemas/DecimalValue"
computed_value:
- type: number
+ $ref: "#/components/schemas/DecimalValue"
range:
type: object
properties:
min:
- type: number
+ $ref: "#/components/schemas/DecimalValue"
max:
- type: number
+ $ref: "#/components/schemas/DecimalValue"
unit:
type: string
- required:
- - value
- - unit
Schedule:
- description: Describes a 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'
+ $ref: "#/components/schemas/Duration"
holidays:
type: array
items:
@@ -2396,89 +3755,44 @@ components:
items:
type: string
format: date-time
+
State:
- description: Describes a state
+ description: Describes the state of an order or fulfillment This has properties like descriptor, updated_at,updated_by
type: object
properties:
descriptor:
- $ref: '#/components/schemas/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:
+
+ Support:
+ description: Customer support
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:
+ callback:
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:
+ format: phone
+ phone:
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:
+ format: phone
+ email:
type: string
- format: date-time
- expires:
+ format: email
+ url:
type: string
- description: Expiry timestamp in UTC derived from the ```lease_time``` of the subscriber
- format: date-time
+ format: uri
- 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: Describes a tag. This is a simple key-value store which is used to contain extended metadata
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
+ 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:
@@ -2487,7 +3801,7 @@ components:
type: string
format: date-time
duration:
- $ref: '#/components/schemas/Duration'
+ $ref: "#/components/schemas/Duration"
range:
type: object
properties:
@@ -2501,27 +3815,45 @@ components:
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'
+ $ref: "#/components/schemas/Schedule"
Tracking:
- description: Describes the tracking info of an object
+ 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:
+ type: string
url:
type: string
format: uri
+ mime_type:
+ type: string
+ location:
+ $ref: "#/components/schemas/Location"
status:
type: string
enum:
- active
- inactive
+ UpdateTerms:
+ type: object
+ properties:
+ id:
+ type: string
+ description: ID of the update terms
+ update_by:
+ type: string
+ format: date-time
+ other_terms:
+ type: array
+ items:
+ type: string
+ external_ref:
+ $ref: "#/components/schemas/MediaFile"
+
Vehicle:
- description: Describes the properties of a vehicle used in a mobility service
+ 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:
@@ -2542,3 +3874,9 @@ components:
type: string
registration:
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.
+ allOf:
+ - $ref: "#/components/schemas/Form"
+
diff --git a/docs/images/rating handshake.png b/docs/images/rating handshake.png
new file mode 100644
index 00000000..374c88d5
Binary files /dev/null and b/docs/images/rating handshake.png differ
diff --git a/docs/images/sample.png b/docs/images/sample.png
new file mode 100644
index 00000000..97b5266a
Binary files /dev/null and b/docs/images/sample.png differ
diff --git a/docs/proposals/BECKN-RFC-Rating and Reputation on Beckn Protocol.md b/docs/proposals/BECKN-RFC-Rating and Reputation on Beckn Protocol.md
new file mode 100644
index 00000000..99060a11
--- /dev/null
+++ b/docs/proposals/BECKN-RFC-Rating and Reputation on Beckn Protocol.md
@@ -0,0 +1,171 @@
+# Rating and Reputation on Beckn Protocol
+
+*Draft 01*
+
+Author:
+=======
+
+Ravi Prakash (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/proposals/Sample-proposal.md b/docs/proposals/Sample-proposal.md
new file mode 100644
index 00000000..a4175d4d
--- /dev/null
+++ b/docs/proposals/Sample-proposal.md
@@ -0,0 +1,42 @@
+# Enter Proposal Title Here
+
+## Status:
+Proposal
+
+## Affected Protocol Versions (Active release versions ONLY, REQUIRED)
+* 0.9.3
+* 0.9.2
+* ALL
+
+## Authors:
+
+#### John Doe
+* _Email address_ : john.doe@example.com
+* _Github username_ : [john.doe](https://github.com/john.doe)
+
+#### Jane Doe
+* _Email address_ : jane.doe@example.com
+* _Github username_ : [jane.doe](https://github.com/jane.doe)
+
+# Abstract (150 words max, REQUIRED)
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis a feugiat odio. Pellentesque in vehicula leo. Integer commodo dapibus tortor, sed vehicula enim condimentum ut. Phasellus in ornare nunc. Fusce convallis eros sed neque elementum aliquam. Fusce mauris purus, aliquam in turpis non, egestas eleifend augue. Aliquam sem libero, aliquam sit amet congue sed, faucibus ut arcu. Nam elit felis, vehicula vel ornare et, ultrices id tellus. Phasellus accumsan eleifend ante, ac fringilla erat pharetra tincidunt. Sed pharetra, magna sed feugiat rutrum, orci nulla volutpat mi, non tempor sem ligula tristique dolor. Nullam id justo efficitur, ornare enim id, lobortis sem.
+
+# Heading (REQUIRED)
+
+Pellentesque consequat purus ac urna lobortis condimentum. Nullam dignissim justo id turpis gravida tincidunt. Aenean a malesuada augue, nec consectetur lacus. In dapibus eu lectus eget imperdiet. Aenean ut nisl fermentum, interdum est quis, pharetra tellus. Nullam gravida augue ac diam auctor, laoreet viverra enim interdum. Donec eget leo eu lectus sodales fermentum. Duis quis dui pharetra, viverra justo at, dapibus arcu.
+
+## Subheading
+Fusce in luctus mi. Ut sagittis, lectus at varius sollicitudin, est tellus tincidunt nisi, vel vestibulum nisi libero a enim. Duis leo neque, accumsan sed suscipit sed, tempus sed dolor. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Nunc sit amet odio semper leo mollis pretium quis ac ante.
+
+
+
+
+### Sub-subheading
+Aenean tincidunt sollicitudin sem a sodales. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Maecenas a eros lacus. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Vestibulum nisi sapien, varius ut luctus sit amet, venenatis vitae nisi. Etiam ut magna vitae tortor scelerisque finibus. Duis arcu libero, facilisis non ultrices at, molestie ut ipsum.
+
+
+# References (REQUIRED)
+
+1. [Name of reference 1](https://URL/to/reference)
+2. [Name of reference 2](https://URL/to/reference)
diff --git a/docs/protocol-drafts/BECKN-RFC-001-Layering-Network-Policy-Draft-01.md b/docs/protocol-drafts/BECKN-001-Layering-Network-Policy-Draft-01.md
similarity index 100%
rename from docs/protocol-drafts/BECKN-RFC-001-Layering-Network-Policy-Draft-01.md
rename to docs/protocol-drafts/BECKN-001-Layering-Network-Policy-Draft-01.md
diff --git a/docs/protocol-drafts/BECKN-RFC-002-Payments-On-Beckn-Enabled-Networks.md b/docs/protocol-drafts/BECKN-002-Payments-On-Beckn-Enabled-Networks.md
similarity index 94%
rename from docs/protocol-drafts/BECKN-RFC-002-Payments-On-Beckn-Enabled-Networks.md
rename to docs/protocol-drafts/BECKN-002-Payments-On-Beckn-Enabled-Networks.md
index 87e30399..2c6984cd 100644
--- a/docs/protocol-drafts/BECKN-RFC-002-Payments-On-Beckn-Enabled-Networks.md
+++ b/docs/protocol-drafts/BECKN-002-Payments-On-Beckn-Enabled-Networks.md
@@ -133,7 +133,7 @@ Payment Collection by a BAP and settled at the end of the month to a bank accoun
{
"collected_by": "bap",
"uri": "payto://bank/98273982749428?amount=$currency:$value&ifsc=$ifsc&message=hello",
- "method": "PAYTO",
+ "tl_method": "PAYTO",
"type": "POST_FULFILLMENT",
"status": "NOT-PAID",
"params": {
@@ -155,7 +155,7 @@ Immediate payment on order placement to a UPI Endpoint
```
{
"uri": "payto://upi/example@upi?amount=$currency:$value&message=hello",
- "method": "PAYTO",
+ "tl_method": "PAYTO",
"type": "ON-ORDER",
"status": "NOT-PAID",
"params": {
@@ -171,7 +171,7 @@ Transfer to a Payment Gateway Endpoint
```
{
"uri": "https://pay.example.com?amount=$value&cur=$currency",
- "method": "PAYTO",
+ "tl_method": "HTTP/POST",
"type": "ON-ORDER",
"status": "NOT-PAID",
"params": {
@@ -181,7 +181,27 @@ Transfer to a Payment Gateway Endpoint
}
```
+## Example 4
+Payment Collection by a BAP and settled at the end of the month using UPI before 15th of February 2022
+```
+{
+ "collected_by": "bap",
+ "uri": "upi://pay?pa=UPIID@oksbi&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/protocol-drafts/BECKN-RFC-003-Beckn-Protocol-Communication-Draft-01.md b/docs/protocol-drafts/BECKN-003-Beckn-Protocol-Communication-Draft-01.md
similarity index 100%
rename from docs/protocol-drafts/BECKN-RFC-003-Beckn-Protocol-Communication-Draft-01.md
rename to docs/protocol-drafts/BECKN-003-Beckn-Protocol-Communication-Draft-01.md
diff --git a/docs/protocol-drafts/BECKN-RFC-004-Policy-Administration-On-Beckn-Enabled-Networks.md b/docs/protocol-drafts/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md
similarity index 100%
rename from docs/protocol-drafts/BECKN-RFC-004-Policy-Administration-On-Beckn-Enabled-Networks.md
rename to docs/protocol-drafts/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md
diff --git a/docs/protocol-drafts/BECKN-RFC-005-Error-Codes-Draft-01.md b/docs/protocol-drafts/BECKN-RFC-005-Error-Codes-Draft-01.md
new file mode 100644
index 00000000..10d9a60b
--- /dev/null
+++ b/docs/protocol-drafts/BECKN-RFC-005-Error-Codes-Draft-01.md
@@ -0,0 +1,76 @@
+# Error Codes for BPP
+
+## ID:
+BECKN-RFC-034
+
+## Draft ID
+Draft-01
+
+## Title:
+Error Codes
+
+## Category:
+Network Policy
+
+## Status:
+Protocol Draft
+
+## Published on:
+January 21, 2022
+
+## Expires on:
+January 20, 2023 or Date of publication of next draft which ever is earlier
+
+## License:
+CC-BY-ND
+
+## Authors:
+1. Ravi Prakash : ravi@becknfoundation.org
+
+## Reviewers:
+1. Sujith Nair : sujith@becknfoundation.org
+2. Pramod Varma : pramod@ekstep.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/protocol-drafts/BECKN-RFC-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md b/docs/protocol-drafts/BECKN-RFC-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md
new file mode 100644
index 00000000..b38df75b
--- /dev/null
+++ b/docs/protocol-drafts/BECKN-RFC-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md
@@ -0,0 +1,360 @@
+# Signing Beckn APIs in HTTP
+## Introduction
+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))"`
+
+## 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 hash 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 [hash](https://en.wikipedia.org/wiki/BLAKE_(hash_function)#BLAKE2b_algorithm) :
+
+`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 singing 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|bap1234|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:**
+1. The difference between the `created` and the `expires` field should be equal to the TTL of the request context.
+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 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|bap1234|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 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 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"
+}
+}
+}`
+
+
+
+### 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 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
+
+`hJ5sCmbe7s9Wateq6QAdBGloVSkLuLHWOXcRkzrMcVLthFldV4gnT9Vrnq9iDNPVSKuDqaercVjQwFlj0Ml+3Q==`
+
+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|bg3456|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 `|`. As we know, the subscriber ID is the registered domain name of the subscriber and follows the format{subdomain}.{domain}.{extension}.
+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 by retrieving a cached copy of the subscriber's public key matching the subscriber_id and unique_key_id. It will get the BG’s public key :
+
+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 get the BG’s public key :
+
+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|bpp5678|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|bg3456|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"
+}
+}
+}`
+