openapi: 3.0.0
info:
title: Beckn Energy API Specification
description: Adaptation of Beckn protocol for the Energy sector.
version: 1.1.0
security:
- SubscriberAuth: []
paths:
/search:
post:
tags:
- Beckn Provider Platform (BPP)
- Beckn Gateway (BG)
description: This allows the customer to search for energy service providers.
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- search
message:
type: object
properties:
intent:
$ref: "#/components/schemas/Intent"
required:
- context
- message
examples:
The BAP looks for EV charging providers:
value:
context:
domain: uei:charging
action: search
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
intent:
item:
descriptor:
code: energy
quantity:
required:
value: "4.0"
unit: kWH
category:
descriptor:
code: green-tariff
location:
gps: 12.423423,77.325647
radius:
type: CONSTANT
value: "5"
unit: km
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/select:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP selects a provider and their energy service.
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- select
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
required:
- context
- message
examples:
The BAP selects an EV charging service from a provider:
value:
context:
domain: uei:charging
action: select
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
provider:
id: chargezone.in
items:
- id: pe-charging-01
quantity:
selected:
measure:
value: "4"
unit: kWh
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/init:
post:
tags:
- Beckn Provider Platform (BPP)
description: Initialize an order by providing billing and/or shipping details to the energy service provider
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- init
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
required:
- context
- message
examples:
The BAP initiates an order for the EV charging service from a provider:
value:
context:
domain: uei:charging
action: init
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
provider:
id: chargezone.in
items:
- id: pe-charging-01
billing:
name: John Doe
email: abc@example.com
phone: +91-9876522222
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/confirm:
post:
tags:
- Beckn Provider Platform (BPP)
description: Confirms the order, completes the payment and waits for order confirmation.
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- confirm
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
required:
- context
- message
examples:
The BAP confirms the order to charge the EV:
value:
context:
domain: uei:charging
action: confirm
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
providers:
id: chargezone.in
items:
- id: pe-charging-01
billing:
name: John Doe
email: abc@example.com
number: +91-9876522222
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
payments:
- collected_by: BPP
params:
amount: "40"
currency: INR
status: PAID
type: PRE-ORDER
quote:
price:
value: "40"
currency: INR
breakup:
- item:
descriptor:
name: Estimated units consumed
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "32"
currency: INR
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/status:
post:
tags:
- Beckn Provider Platform (BPP)
description: Fetch the latest order object status
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- status
required:
- action
message:
type: object
properties:
order_id:
$ref: "#/components/schemas/Order/properties/id"
required:
- order_id
required:
- context
- message
examples:
The BAP checks for the status of the charging:
value:
context:
domain: uei:charging
action: status
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order_id: 6743e9e2-4fb5-487c-92b7
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/cancel:
post:
tags:
- Beckn Provider Platform (BPP)
description: Cancel an order
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- cancel
required:
- action
message:
type: object
properties:
order_id:
$ref: "#/components/schemas/Order/properties/id"
cancellation_reason_id:
$ref: "#/components/schemas/Option/properties/id"
descriptor:
$ref: "#/components/schemas/Descriptor"
required:
- order_id
required:
- context
- message
examples:
The BAP cancels the order for the EV charging:
value:
context:
domain: uei:charging
action: cancel
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
cancellation_reason_id: "5"
descriptor:
short_desc: can't attend booking
order_id: 6743e9e2-4fb5-487c-92b7
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/update:
post:
tags:
- Beckn Provider Platform (BPP)
description: Update a criteria of the order
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- update
required:
- action
message:
type: object
properties:
update_target:
description: 'Comma separated values of order objects being updated. For example: ```"update_target":"item,billing,fulfillment"```'
type: string
order:
description: Updated order object
allOf:
- $ref: "#/components/schemas/Order"
required:
- update_target
- order
required:
- context
- message
examples:
The BAP sends an update to start charging the EV:
value:
context:
domain: uei:charging
action: update
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
update_target: order.fulfillments[0].state
order:
fulfillments:
- id: "1"
type: CHARGING
state:
descriptor:
code: start-charging
The BAP sends an update to stop charging the EV:
value:
context:
domain: uei:charging
action: update
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
update_target: order.fulfillments[0].state
order:
fulfillments:
- id: "1"
type: CHARGING
state:
descriptor:
code: end-charging
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/rating:
post:
tags:
- Beckn Provider Platform (BPP)
description: Provide feedback on a service
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- rating
required:
- action
message:
type: object
properties:
ratings:
type: array
items:
$ref: "#/components/schemas/Rating"
required:
- context
- message
examples:
The BAP rates the service provided:
value:
context:
domain: uei:charging
action: rating
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
ratings:
- id: 6743e9e2-4fb5-487c-92b7
rating_category: charger
value: "5"
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/support:
post:
tags:
- Beckn Provider Platform (BPP)
description: Contact support
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- support
required:
- action
message:
type: object
properties:
support:
$ref: "#/components/schemas/Support"
required:
- context
- message
examples:
The BAP wants to contact support:
value:
context:
domain: uei:charging
action: support
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
support:
order_id: 6743e9e2-4fb5-487c-92b7
phone: "+919876543210"
email: john.doe@gmail.com
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_search:
post:
tags:
- Beckn Application Platform (BAP)
- Beckn Gateway (BG)
description: The BPP sends its energy catalog in response to a search request.
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_search
required:
- action
message:
type: object
properties:
catalog:
$ref: "#/components/schemas/Catalog"
required:
- catalog
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The provider returns a list of catalogs:
value:
context:
domain: uei:charging
action: on_search
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
catalog:
providers:
- id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
categories:
- id: "1"
descriptor:
code: green-tariff
name: green tariff
locations:
- id: "1"
gps: 12.345345,77.389754
- id: "2"
gps: 12.247934,77.876987
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR / kWH
quantity:
available:
measure:
value: "100"
unit: kWH
category_ids:
- "1"
location_ids:
- "1"
- "2"
fulfillment_ids:
- "1"
- "2"
add_ons:
- id: pe-charging-01-addon-1
descriptor:
name: Free car wash
price:
value: "0"
currency: INR
fulfillments:
- id: "1"
type: CHARGING
stops:
- type: start
time:
timestamp: 01-06-2023 10:00:00
- type: end
time:
timestamp: 01-06-2023 10:30:00
tags:
- descriptor:
name: Charging Point Specifications
list:
- descriptor:
name: Charger type
code: charger-type
value: AC
- descriptor:
name: Connector type
code: connector-type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
- id: "2"
type: CHARGING
stops:
- type: start
time:
timestamp: 01-06-2023 10:00:00
- type: end
time:
timestamp: 01-06-2023 10:30:00
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
- id: log9.in
descriptor:
name: Log9 Inc
categories:
- id: "1"
descriptor:
code: green-tariff
name: green tariff
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "10"
currency: INR / kWH
quantity:
available: "1000"
category_ids:
- "1"
fulfillment_ids:
- "3"
- "4"
add_ons:
- id: pe-charging-01-addon-1
descriptor:
name: Free tyre pressure check
price:
value: "0"
currency: INR
fulfillments:
- id: "3"
type: BATTERY-SWAP
stops:
- location:
gps: 12.745675, 77.987393
- id: "4"
type: MOBILE-BATTERY-SWAP
stops:
- location:
url: https://log9.in/track/bswap/3234242
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_select:
post:
tags:
- Beckn Application Platform (BAP)
description: Send details along with quoted price for selected items
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_select
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The provider sends the details of the item selected, along with a quote:
value:
context:
domain: uei:charging
action: on_select
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
- id: pe-charging-01-addon-1
descriptor:
code: add-on-item
name: Free car wash
price:
value: "0"
currency: INR
fulfillments:
- id: "1"
type: CHARGING
stops:
- type: start
time:
timestamp: 01-06-2023 10:00:00
- type: end
time:
timestamp: 01-06-2023 10:30:00
tags:
- descriptor:
name: Charging Point Specifications
list:
- descriptor:
name: Charger type
code: charger-type
value: AC
- descriptor:
name: Connector type
code: connector-type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
quote:
price:
value: "32"
currency: INR
breakup:
- item:
descriptor:
name: Estimated units consumed
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "32"
currency: INR
- item:
descriptor:
name: Free car wash
price:
value: "0"
currency: INR
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_init:
post:
tags:
- Beckn Application Platform (BAP)
description: Send draft order object with payment details updated for the service.
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_init
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The BPP intiates the order, sends the payment link:
value:
context:
domain: uei:charging
action: on_init
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
fulfillments:
- "1"
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
type: CHARGING
state:
descriptor:
code: order-initiated
stops:
- type: start
time:
timestamp: 01-06-2023 10:00:00
- type: end
time:
timestamp: 01-06-2023 10:30:00
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
billing:
email: abc@example.com
number: +91-9876522222
quote:
price:
value: "32"
currency: INR
breakup:
- item:
descriptor:
name: Estimated units consumed
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "32"
currency: INR
payments:
- url: https://payment.gateway.in
type: PRE-ORDER
status: NOT-PAID
params:
amount: "40"
currency: INR
time:
range:
start: "2023-08-10T10:00:00Z"
end: "2023-08-10T10:30:00Z"
cancellation_terms:
- fulfillment_state:
descriptor:
code: charging-start
cancellation_fee:
percentage: 30%
external_ref:
mimetype: text/html
url: https://chargezone.in/charge/tnc.html
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_confirm:
post:
tags:
- Beckn Application Platform (BAP)
description: Send active order object with the confirmed order ID
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_confirm
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The BAP sends an order confirmation:
value:
context:
domain: uei:charging
action: on_confirm
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
id: 6743e9e2-4fb5-487c-92b7
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
fulfillments:
- "1"
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
type: CHARGING
state:
descriptor:
code: payment-completed
stops:
- type: start
location:
gps: 12.423423,77.325647
time:
timestamp: 01-06-2023 10:00:00
range:
start: 01-06-2023 10:00:00
end: 01-06-2023 10:10:00
instructions:
name: Charging instructions
short_desc: To start your charging, go to charger number 987, and click on 'start' on your app
- type: end
time:
timestamp: 01-06-2023 10:30:00
range:
start: 01-06-2023 10:30:00
end: 01-06-2023 10:40:00
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
billing:
email: abc@example.com
number: +91-9876522222
quote:
price:
value: "40"
currency: INR
breakup:
- item:
descriptor:
name: Estimated units consumed
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "32"
currency: INR
payments:
- type: PRE-ORDER
status: PAID
params:
amount: "40"
currency: INR
time:
range:
start: "2023-08-10T10:00:00Z"
end: "2023-08-10T10:30:00Z"
cancellation_terms:
- fulfillment_state:
descriptor:
code: charging-start
cancellation_fee:
percentage: 30%
external_ref:
mimetype: text/html
url: https://chargezone.in/charge/tnc.html
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_cancel:
post:
tags:
- Beckn Application Platform (BAP)
description: Sends cancelled order object with the reason.
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_cancel
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The provider cancels the order after the BAP requested for a cancellation:
value:
context:
domain: uei:charging
action: on_cancel
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
id: 6743e9e2-4fb5-487c-92b7
status: CANCELLED
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
fulfillments:
- "1"
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
type: CHARGING
state:
descriptor:
code: order-cancelled
stops:
- time:
range:
start: "10:00"
end: "10:30"
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
billing:
email: abc@example.com
number: +91-9876522222
quote:
price:
value: "-32"
currency: INR
breakup:
- item:
descriptor:
name: payment refund
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "-32"
currency: INR
payments:
- type: PRE-ORDER
status: PAID
params:
amount: "40"
currency: INR
time:
range:
start: "2023-08-10T10:00:00Z"
end: "2023-08-10T10:30:00Z"
cancellation_terms:
- fulfillment_state:
descriptor:
code: charging-start
cancellation_fee:
percentage: 30%
external_ref:
mimetype: text/html
url: https://chargezone.in/charge/tnc.html
The provider cancels the order after the there was an error in the charger:
value:
context:
domain: uei:charging
action: on_cancel
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
id: 6743e9e2-4fb5-487c-92b7
status: CANCELLED
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
allocated:
measure:
value: "2"
unit: kWh
fulfillments:
- "1"
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
type: CHARGING
state:
descriptor:
code: charger-error
stops:
- time:
range:
start: "10:00"
end: "10:30"
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
billing:
email: abc@example.com
number: +91-9876522222
quote:
price:
value: "-12"
currency: INR
breakup:
- item:
descriptor:
name: payment refund
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "-12"
currency: INR
payments:
- type: PRE-ORDER
status: PAID
params:
amount: "40"
currency: INR
time:
range:
start: "2023-08-10T10:00:00Z"
end: "2023-08-10T10:30:00Z"
cancellation_terms:
- fulfillment_state:
descriptor:
code: charging-start
cancellation_fee:
percentage: 30%
external_ref:
mimetype: text/html
url: https://chargezone.in/charge/tnc.html
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_update:
post:
tags:
- Beckn Application Platform (BAP)
description: Returns updated service with updated runtime object
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_update
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The provider sends an updated object to start charging:
value:
context:
domain: uei:charging
action: on_update
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
id: 6743e9e2-4fb5-487c-92b7
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
fulfillments:
- "1"
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
type: CHARGING
state:
descriptor:
code: charging-started
stops:
- type: start
location:
gps: 12.423423,77.325647
time:
timestamp: 01-06-2023 10:00:00
range:
start: 01-06-2023 10:00:00
end: 01-06-2023 10:10:00
- type: end
time:
timestamp: 01-06-2023 10:30:00
range:
start: 01-06-2023 10:30:00
end: 01-06-2023 10:40:00
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
billing:
email: abc@example.com
number: +91-9876522222
quote:
price:
value: "40"
currency: INR
breakup:
- item:
descriptor:
name: Estimated units consumed
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "32"
currency: INR
payments:
- type: PRE-ORDER
status: PAID
params:
amount: "40"
currency: INR
time:
range:
start: "2023-08-10T10:00:00Z"
end: "2023-08-10T10:30:00Z"
cancellation_terms:
- fulfillment_state:
descriptor:
code: charging-start
cancellation_fee:
percentage: 30%
external_ref:
mimetype: text/html
url: https://chargezone.in/charge/tnc.html
The provider sends an updated object to stop charging:
value:
context:
domain: uei:charging
action: on_update
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
id: 6743e9e2-4fb5-487c-92b7
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
fulfillments:
- "1"
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
type: CHARGING
state:
descriptor:
code: charging-ended
stops:
- type: start
location:
gps: 12.423423,77.325647
time:
timestamp: 01-06-2023 10:00:00
range:
start: 01-06-2023 10:00:00
end: 01-06-2023 10:10:00
- type: end
time:
timestamp: 01-06-2023 10:30:00
range:
start: 01-06-2023 10:30:00
end: 01-06-2023 10:40:00
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
billing:
email: abc@example.com
number: +91-9876522222
quote:
price:
value: "40"
currency: INR
breakup:
- item:
descriptor:
name: Estimated units consumed
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "32"
currency: INR
payments:
- type: PRE-ORDER
status: PAID
params:
amount: "40"
currency: INR
time:
range:
start: "2023-08-10T10:00:00Z"
end: "2023-08-10T10:30:00Z"
cancellation_terms:
- fulfillment_state:
descriptor:
code: charging-start
cancellation_fee:
percentage: 30%
external_ref:
mimetype: text/html
url: https://chargezone.in/charge/tnc.html
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_status:
post:
tags:
- Beckn Application Platform (BAP)
description: Fetch the status of a service
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_status
required:
- action
message:
type: object
properties:
order:
$ref: "#/components/schemas/Order"
required:
- order
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The provider sends status of the charging:
value:
context:
domain: uei:charging
action: on_status
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: example-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
order:
id: 6743e9e2-4fb5-487c-92b7
providers:
id: chargezone.in
descriptor:
name: Chargezone
short_desc: Chargezone Technologies Pvt Ltd
images:
- url: https://chargezone.in/images/logo.png
items:
- id: pe-charging-01
descriptor:
code: energy
price:
value: "8"
currency: INR/kWH
quantity:
available:
measure:
value: "100"
unit: kWh
selected:
measure:
value: "4"
unit: kWh
fulfillments:
- "1"
fulfillments:
- id: "1"
customer:
person:
name: John Doe
contact:
phone: +91-9887766554
type: CHARGING
state:
descriptor:
name: vehicle 65% charged
stops:
- type: start
location:
gps: 12.423423,77.325647
time:
timestamp: 01-06-2023 10:00:00
range:
start: 01-06-2023 10:00:00
end: 01-06-2023 10:10:00
- type: end
time:
timestamp: 01-06-2023 10:30:00
range:
start: 01-06-2023 10:30:00
end: 01-06-2023 10:40:00
tags:
- descriptor:
name: Charging Point
list:
- descriptor:
name: Charger type
value: AC
- descriptor:
name: Connector type
value: CCS2
- descriptor:
name: Power Rating
value: greater than 50kW
- descriptor:
name: Availability
value: Available
display: true
billing:
email: abc@example.com
number: +91-9876522222
quote:
price:
value: "32"
currency: INR
breakup:
- item:
descriptor:
name: Estimated units consumed
quantity:
selected:
measure:
value: "4"
unit: kWh
price:
value: "32"
currency: INR
payments:
- type: PRE-ORDER
status: PAID
params:
amount: "40"
currency: INR
time:
range:
start: "2023-08-10T10:00:00Z"
end: "2023-08-10T10:30:00Z"
cancellation_terms:
- fulfillment_state:
descriptor:
code: charging-start
cancellation_fee:
percentage: 30%
external_ref:
mimetype: text/html
url: https://chargezone.in/charge/tnc.html
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_rating:
post:
tags:
- Beckn Application Platform (BAP)
description: Provide feedback on a service
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_rating
required:
- action
message:
type: object
properties:
feedback_form:
description: A feedback form to allow the user to provide additional information on the rating provided
allOf:
- $ref: "#/components/schemas/XInput"
error:
$ref: "#/components/schemas/Error"
required:
- context
- message
examples:
The provider responds with a form URL for rating:
value:
context:
domain: uei:charging
action: on_rating
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
feedback_form:
xinput:
form:
url: https://api.example-bpp.com/pilot/bpp/feedback/portal
required: "false"
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
/on_support:
post:
tags:
- Beckn Application Platform (BAP)
description: Contact Support
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: "#/components/schemas/Context"
- properties:
action:
enum:
- on_support
required:
- action
message:
type: object
properties:
support:
$ref: "#/components/schemas/Support"
error:
$ref: "#/components/schemas/Error"
required:
- context
examples:
The provider returns support details:
value:
context:
domain: uei:charging
action: on_support
location:
country:
name: India
code: IND
city: std:080
version: 1.1.0
bap_id: example-bap.com
bap_uri: https://api.example-bap.com/pilot/bap/energy/v1
bpp_id: chargezone-energy-bpp.com
bpp_uri: https://api.example-bpp.com/pilot/bpp/
transaction_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
message_id: 6743e9e2-4fb5-487c-92b7-13ba8018f176
timestamp: "2023-07-16T04:41:16Z"
message:
support:
order_id: 6743e9e2-4fb5-487c-92b7
phone: 1800 1080
email: customer.care@chargezone.com
url: https://www.chargezone.com/helpdesk
responses:
"200":
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "#/components/schemas/Ack"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "#/components/schemas/Error"
required:
- message
components:
securitySchemes:
SubscriberAuth:
type: apiKey
in: header
name: Authorization
description: 'Signature of message body using BAP or BPP subscriber''s signing public key.
Format:
Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"'
schemas:
Ack:
description: "Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack must be returned in the same session. Every API call to a BPP must be responded to with an Ack whether the BPP intends to respond with a callback or not. This has one property called `status` that indicates the status of the Acknowledgement."
type: object
properties:
status:
type: string
description: "The status of the acknowledgement. If the request passes the validation criteria of the BPP, then this is set to ACK. If a BPP responds with status = `ACK` to a request, it is required to respond with a callback. If the request fails the validation criteria, then this is set to NACK. Additionally, if a BPP does not intend to respond with a callback even after the request meets the validation criteria, it should set this value to `NACK`."
enum:
- ACK
- NACK
tags:
description: A list of tags containing any additional information sent along with the Acknowledgement.
type: array
items:
$ref: "#/components/schemas/TagGroup"
AddOn:
description: Describes an additional item offered as a value-addition to a product or service. This does not exist independently in a catalog and is always associated with an item.
type: object
properties:
id:
description: Provider-defined ID of the add-on
type: string
descriptor:
$ref: "#/components/schemas/Descriptor"
price:
$ref: "#/components/schemas/Price"
Address:
description: Describes a postal address.
type: string
Agent:
description: "Describes the direct performer, driver or executor that fulfills an order. It is usually a person. But in some rare cases, it could be a non-living entity like a drone, or a bot. Some examples of agents are Doctor in the healthcare sector, a driver in the mobility sector, or a delivery person in the logistics sector. This object can be set at any stage of the order lifecycle. This can be set at the discovery stage when the BPP wants to provide details on the agent fulfilling the order, like in healthcare, where the doctor's name appears during search. This object can also used to search for a particular person that the customer wants fulfilling an order. Sometimes, this object gets instantiated after the order is confirmed, like in the case of on-demand taxis, where the driver is assigned after the user confirms the ride."
properties:
person:
$ref: "#/components/schemas/Person"
contact:
$ref: "#/components/schemas/Contact"
organization:
$ref: "#/components/schemas/Organization"
rating:
$ref: "#/components/schemas/Rating/properties/value"
Authorization:
description: "Describes an authorization mechanism used to start or end the fulfillment of an order. For example, in the mobility sector, the driver may require a one-time password to initiate the ride. In the healthcare sector, a patient may need to provide a password to open a video conference link during a teleconsultation."
type: object
properties:
type:
description: Type of authorization mechanism used. The allowed values for this field can be published as part of the network policy.
type: string
token:
description: "Token used for authorization. This is typically generated at the BPP. The BAP can send this value to the user via any channel that it uses to authenticate the user like SMS, Email, Push notification, or in-app rendering."
type: string
valid_from:
description: Timestamp in RFC3339 format from which token is valid
type: string
format: date-time
valid_to:
description: Timestamp in RFC3339 format until which token is valid
type: string
format: date-time
status:
description: Status of the token
type: string
Billing:
description: "Describes the billing details of an entity.
This has properties like name,organization,address,email,phone,time,tax_number, created_at,updated_at"
type: object
properties:
name:
description: Name of the billable entity
type: string
organization:
description: Details of the organization being billed.
allOf:
- $ref: "#/components/schemas/Organization"
address:
description: The address of the billable entity
allOf:
- $ref: "#/components/schemas/Address"
state:
description: The state where the billable entity resides. This is important for state-level tax calculation
allOf:
- $ref: "#/components/schemas/State"
city:
description: The city where the billable entity resides.
allOf:
- $ref: "#/components/schemas/City"
email:
description: Email address where the bill is sent to
type: string
format: email
phone:
description: Phone number of the billable entity
type: string
time:
description: Details regarding the billing period
allOf:
- $ref: "#/components/schemas/Time"
tax_id:
description: ID of the billable entity as recognized by the taxation authority
type: string
Cancellation:
description: Describes a cancellation event
type: object
properties:
time:
description: Date-time when the order was cancelled by the buyer
type: string
format: date-time
cancelled_by:
type: string
enum:
- CONSUMER
- PROVIDER
reason:
description: The reason for cancellation
allOf:
- $ref: "#/components/schemas/Option"
additional_description:
description: Any additional information regarding the nature of cancellation
allOf:
- $ref: "#/components/schemas/Descriptor"
CancellationTerm:
description: Describes the cancellation terms of an item or an order. This can be referenced at an item or order level. Item-level cancellation terms can override the terms at the order level.
type: object
properties:
fulfillment_state:
description: The state of fulfillment during which this term is applicable.
allOf:
- $ref: "#/components/schemas/FulfillmentState"
reason_required:
description: Indicates whether a reason is required to cancel the order
type: boolean
cancel_by:
description: Information related to the time of cancellation.
allOf:
- $ref: "#/components/schemas/Time"
cancellation_fee:
$ref: "#/components/schemas/Fee"
xinput:
$ref: "#/components/schemas/XInput"
external_ref:
$ref: "#/components/schemas/MediaFile"
Catalog:
description: "Describes the products or services offered by a BPP. This is typically sent as the response to a search intent from a BAP. The payment terms, offers and terms of fulfillment supported by the BPP can also be included here. The BPP can show hierarchical nature of products/services in its catalog using the parent_category_id in categories. The BPP can also send a ttl (time to live) in the context which is the duration for which a BAP can cache the catalog and use the cached catalog.
This has properties like bbp/descriptor,bbp/categories,bbp/fulfillments,bbp/payments,bbp/offers,bbp/providers and exp
This is used in the following situations.
- This is typically used in the discovery stage when the BPP sends the details of the products and services it offers as response to a search intent from the BAP.
"
type: object
properties:
descriptor:
$ref: "#/components/schemas/Descriptor"
fulfillments:
description: Fulfillment modes offered at the BPP level. This is used when a BPP itself offers fulfillments on behalf of the providers it has onboarded.
type: array
items:
$ref: "#/components/schemas/Fulfillment"
payments:
description: Payment terms offered by the BPP for all transactions. This can be overriden at the provider level.
type: array
items:
$ref: "#/components/schemas/Payment"
offers:
description: Offers at the BPP-level. This is common across all providers onboarded by the BPP.
type: array
items:
$ref: "#/components/schemas/Offer"
providers:
type: array
items:
$ref: "#/components/schemas/Provider"
exp:
description: Timestamp after which catalog will expire
type: string
format: date-time
ttl:
description: Duration in seconds after which this catalog will expire
type: string
Category:
description: A label under which a collection of items can be grouped.
type: object
properties:
id:
description: ID of the category
type: string
parent_category_id:
$ref: "#/components/schemas/Category/properties/id"
descriptor:
$ref: "#/components/schemas/Descriptor"
time:
$ref: "#/components/schemas/Time"
ttl:
description: Time to live for an instance of this schema
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
Circle:
description: Describes a circular region of a specified radius centered at a specified GPS coordinate.
type: object
properties:
gps:
$ref: "#/components/schemas/Gps"
radius:
-allOf
- $ref: "#/components/schemas/Scalar"
- properties:
type:
type: string
value:
type: string
unit:
type: string
required:
- type
- value
allOf:
- anyOf:
- not:
properties:
type:
const: CONSTANT
required:
- type
- required:
- unit
City:
description: Describes a city
type: object
properties:
name:
description: Name of the city
type: string
code:
description: City code
type: string
Contact:
description: Describes the contact information of an entity
type: object
properties:
phone:
type: string
email:
type: string
jcard:
type: object
description: A Jcard object as per draft-ietf-jcardcal-jcard-03 specification
Context:
description: "Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the BAP that sets the transaction context based on the consumer's location and action on their UI. But sometimes, during unsolicited callbacks, the BPP also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the BAP and the BPP. The context object contains four types of fields. - Demographic information about the transaction using fields like `domain`, `country`, and `region`.
- Addressing details like the sending and receiving platform's ID and API URL.
- Interoperability information like the protocol version that implemented by the sender and,
- Transaction details like the method being called at the receiver's endpoint, the transaction_id that represents an end-to-end user session at the BAP, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.
This object must be passed in every interaction between a BAP and a BPP. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions,"
type: object
properties:
domain:
description: Domain code that is relevant to this transaction context
allOf:
- $ref: "#/components/schemas/Domain/properties/code"
location:
description: The location where the transaction is intended to be fulfilled.
allOf:
- $ref: "#/components/schemas/Location"
action:
description: The Beckn protocol method being called by the sender and executed at the receiver.
type: string
version:
type: string
description: Version of transaction protocol being used by the sender.
bap_id:
description: Subscriber ID of the BAP
allOf:
- description: "A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform."
type: string
bap_uri:
description: Subscriber URL of the BAP for accepting callbacks from BPPs.
allOf:
- description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``.
type: string
format: uri
bpp_id:
description: Subscriber ID of the BPP
allOf:
- $ref: "#/components/schemas/Context/properties/bap_id/allOf/0"
bpp_uri:
description: Subscriber URL of the BPP for accepting calls from BAPs.
allOf:
- $ref: "#/components/schemas/Context/properties/bap_uri/allOf/0"
transaction_id:
description: "This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The BPPs can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the BAP."
type: string
format: uuid
message_id:
description: "This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, BAPs need a common value to match an incoming callback from a BPP to an earlier call. This value can also be used to ignore duplicate messages coming from the BPP. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, BPPs must generate a new message_id."
type: string
format: uuid
timestamp:
description: Time of request generation in RFC3339 format
type: string
format: date-time
key:
description: The encryption public key of the sender
type: string
ttl:
description: The duration in ISO8601 format after timestamp for which this message holds valid
type: string
Country:
description: Describes a country
type: object
properties:
name:
type: string
description: Name of the country
code:
type: string
description: Country code as per ISO 3166-1 and ISO 3166-2 format
Credential:
description: Describes a credential of an entity - Person or Organization
type: object
properties:
id:
type: string
type:
type: string
default: VerifiableCredential
url:
description: URL of the credential
type: string
format: uri
Customer:
description: Describes a customer buying/availing a product or a service
type: object
properties:
person:
$ref: "#/components/schemas/Person"
contact:
$ref: "#/components/schemas/Contact"
DecimalValue:
description: Describes a numerical value in decimal form
type: string
pattern: "[+-]?([0-9]*[.])?[0-9]+"
Descriptor:
description: Physical description of something.
type: object
properties:
name:
type: string
code:
type: string
short_desc:
type: string
long_desc:
type: string
additional_desc:
type: object
properties:
url:
type: string
content_type:
type: string
enum:
- text/plain
- text/html
- application/json
media:
type: array
items:
$ref: "#/components/schemas/MediaFile"
images:
type: array
items:
$ref: "#/components/schemas/Image"
Domain:
description: "Described the industry sector or sub-sector. The network policy should contain codes for all the industry sectors supported by the network. Domains can be created in varying levels of granularity. The granularity of a domain can be decided by the participants of the network. Too broad domains will result in irrelevant search broadcast calls to BPPs that don't have services supporting the domain. Too narrow domains will result in a large number of registry entries for each BPP. It is recommended that network facilitators actively collaborate with various working groups and network participants to carefully choose domain codes keeping in mind relevance, performance, and opportunity cost. It is recommended that networks choose broad domains like mobility, logistics, healthcare etc, and progressively granularize them as and when the number of network participants for each domain grows large."
type: object
properties:
name:
description: Name of the domain
type: string
code:
description: "Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network."
additional_info:
description: A url that contains addtional information about that domain.
allOf:
- $ref: "#/components/schemas/MediaFile"
Duration:
description: Describes duration as per ISO8601 format
type: string
Error:
description: "Describes an error object that is returned by a BAP, BPP or BG as a response or callback to an action by another network participant. This object is sent when any request received by a network participant is unacceptable. This object can be sent either during Ack or with the callback."
type: object
properties:
code:
type: string
description: 'Standard error code. For full list of error codes, refer to docs/protocol-drafts/BECKN-005-ERROR-CODES-DRAFT-01.md of this repo"'
paths:
type: string
description: Path to json schema generating the error. Used only during json schema validation errors
message:
type: string
description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user.
Fee:
description: A fee applied on a particular entity
type: object
properties:
percentage:
description: Percentage of a value
allOf:
- $ref: "#/components/schemas/DecimalValue"
amount:
description: A fixed value
allOf:
- $ref: "#/components/schemas/Price"
Form:
description: Describes a form
type: object
properties:
url:
description: "The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form."
type: string
format: uri
data:
description: The form submission data
type: object
additionalProperties:
type: string
mime_type:
description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838.
type: string
enum:
- text/html
- application/xml
submission_id:
type: string
format: uuid
Fulfillment:
description: Describes how a an order will be rendered/fulfilled to the end-customer
type: object
properties:
id:
description: Unique reference ID to the fulfillment of an order
type: string
type:
description: "A code that describes the mode of fulfillment. This is typically set when there are multiple ways an order can be fulfilled. For example, a retail order can be fulfilled either via store pickup or a home delivery. Similarly, a medical consultation can be provided either in-person or via tele-consultation. The network policy must publish standard fulfillment type codes for the different modes of fulfillment."
type: string
rateable:
description: Whether the fulfillment can be rated or not
type: boolean
rating:
description: The rating value of the fulfullment service.
allOf:
- $ref: "#/components/schemas/Rating/properties/value"
state:
description: The current state of fulfillment. The BPP must set this value whenever the state of the order fulfillment changes and fire an unsolicited `on_status` call.
allOf:
- $ref: "#/components/schemas/FulfillmentState"
tracking:
type: boolean
description: Indicates whether the fulfillment allows tracking
default: false
customer:
description: The person that will ultimately receive the order
allOf:
- $ref: "#/components/schemas/Customer"
agent:
description: The agent that is currently handling the fulfillment of the order
allOf:
- $ref: "#/components/schemas/Agent"
contact:
$ref: "#/components/schemas/Contact"
vehicle:
$ref: "#/components/schemas/Vehicle"
stops:
description: The list of logical stops encountered during the fulfillment of an order.
type: array
items:
$ref: "#/components/schemas/Stop"
path:
description: The physical path taken by the agent that can be rendered on a map. The allowed format of this property can be set by the network.
type: string
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
FulfillmentState:
description: Describes the state of fulfillment
type: object
properties:
descriptor:
$ref: "#/components/schemas/Descriptor"
updated_at:
type: string
format: date-time
updated_by:
type: string
description: ID of entity which changed the state
Gps:
description: Describes a GPS coordinate
type: string
pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$'
Image:
description: Describes an image
type: object
properties:
url:
description: URL to the image. This can be a data url or an remote url
type: string
format: uri
size_type:
description: The size of the image. The network policy can define the default dimensions of each type
type: string
enum:
- xs
- sm
- md
- lg
- xl
- custom
width:
description: Width of the image in pixels
type: string
height:
description: Height of the image in pixels
type: string
Intent:
description: "The intent to buy or avail a product or a service. The BAP can declare the intent of the consumer containing - What they want (A product, service, offer)
- Who they want (A seller, service provider, agent etc)
- Where they want it and where they want it from
- When they want it (start and end time of fulfillment
- How they want to pay for it
This has properties like descriptor,provider,fulfillment,payment,category,offer,item,tags
This is typically used by the BAP to send the purpose of the user's search to the BPP. This will be used by the BPP to find products or services it offers that may match the user's intent.
For example, in Mobility, the mobility consumer declares a mobility intent. In this case, the mobility consumer declares information that describes various aspects of their journey like,- Where would they like to begin their journey (intent.fulfillment.start.location)
- Where would they like to end their journey (intent.fulfillment.end.location)
- When would they like to begin their journey (intent.fulfillment.start.time)
- When would they like to end their journey (intent.fulfillment.end.time)
- Who is the transport service provider they would like to avail services from (intent.provider)
- Who is traveling (This is not recommended in public networks) (intent.fulfillment.customer)
- What kind of fare product would they like to purchase (intent.item)
- What add-on services would they like to avail
- What offers would they like to apply on their booking (intent.offer)
- What category of services would they like to avail (intent.category)
- What additional luggage are they carrying
- How would they like to pay for their journey (intent.payment)
For example, in health domain, a consumer declares the intent for a lab booking the describes various aspects of their booking like,- Where would they like to get their scan/test done (intent.fulfillment.start.location)
- When would they like to get their scan/test done (intent.fulfillment.start.time)
- When would they like to get the results of their test/scan (intent.fulfillment.end.time)
- Who is the service provider they would like to avail services from (intent.provider)
- Who is getting the test/scan (intent.fulfillment.customer)
- What kind of test/scan would they like to purchase (intent.item)
- What category of services would they like to avail (intent.category)
- How would they like to pay for their journey (intent.payment)
"
type: object
properties:
descriptor:
description: "A raw description of the search intent. Free text search strings, raw audio, etc can be sent in this object."
allOf:
- $ref: "#/components/schemas/Descriptor"
provider:
description: The provider from which the customer wants to place to the order from
allOf:
- $ref: "#/components/schemas/Provider"
fulfillment:
description: Details on how the customer wants their order fulfilled
allOf:
- $ref: "#/components/schemas/Fulfillment"
location:
description: Location of the request that needs fulfillment.
allOf:
- $ref: "#/components/schemas/Location"
payment:
description: Details on how the customer wants to pay for the order
allOf:
- $ref: "#/components/schemas/Payment"
category:
description: Details on the item category
allOf:
- $ref: "#/components/schemas/Category"
offer:
description: details on the offer the customer wants to avail
allOf:
- $ref: "#/components/schemas/Offer"
item:
description: Details of the item that the consumer wants to order
allOf:
- $ref: "#/components/schemas/Item"
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
ItemQuantity:
description: Describes the count or amount of an item
type: object
properties:
allocated:
description: This represents the exact quantity allocated for purchase of the item.
type: object
properties:
count:
type: integer
minimum: 0
measure:
$ref: "#/components/schemas/Scalar"
available:
description: This represents the exact quantity available for purchase of the item. The buyer can only purchase multiples of this
type: object
properties:
count:
type: integer
minimum: 0
measure:
$ref: "#/components/schemas/Scalar"
maximum:
description: This represents the maximum quantity allowed for purchase of the item
type: object
properties:
count:
type: integer
minimum: 1
measure:
$ref: "#/components/schemas/Scalar"
minimum:
description: This represents the minimum quantity allowed for purchase of the item
type: object
properties:
count:
type: integer
minimum: 0
measure:
$ref: "#/components/schemas/Scalar"
selected:
description: This represents the quantity selected for purchase of the item
type: object
properties:
count:
type: integer
minimum: 0
measure:
$ref: "#/components/schemas/Scalar"
unitized:
description: This represents the quantity available in a single unit of the item
type: object
properties:
count:
type: integer
minimum: 1
maximum: 1
measure:
$ref: "#/components/schemas/Scalar"
Item:
description: "Describes a product or a service offered to the end consumer by the provider. In the mobility sector, it can represent a fare product like one way journey. In the logistics sector, it can represent the delivery service offering. In the retail domain it can represent a product like a grocery item."
type: object
properties:
id:
description: ID of the item.
type: string
parent_item_id:
description: "ID of the item, this item is a variant of"
allOf:
- $ref: "#/components/schemas/Item/properties/id"
parent_item_quantity:
description: The number of units of the parent item this item is a multiple of
allOf:
- $ref: "#/components/schemas/ItemQuantity"
descriptor:
description: Physical description of the item
allOf:
- $ref: "#/components/schemas/Descriptor"
creator:
description: The creator of this item
allOf:
- $ref: "#/components/schemas/Organization"
price:
description: "The price of this item, if it has intrinsic value"
allOf:
- $ref: "#/components/schemas/Price"
quantity:
description: The selling quantity of the item
allOf:
- $ref: "#/components/schemas/ItemQuantity"
category_ids:
description: Categories this item can be listed under
type: array
items:
allOf:
- $ref: "#/components/schemas/Category/properties/id"
fulfillment_ids:
description: Modes through which this item can be fulfilled
type: array
items:
allOf:
- $ref: "#/components/schemas/Fulfillment/properties/id"
location_ids:
description: Provider Locations this item is available in
type: array
items:
allOf:
- $ref: "#/components/schemas/Location/properties/id"
payment_ids:
description: Payment modalities through which this item can be ordered
type: array
items:
allOf:
- $ref: "#/components/schemas/Payment/properties/id"
add_ons:
type: array
items:
$ref: "#/components/schemas/AddOn"
cancellation_terms:
description: Cancellation terms of this item
type: array
items:
$ref: "#/components/schemas/CancellationTerm"
refund_terms:
description: Refund terms of this item
type: array
items:
description: Refund term of an item or an order
type: object
properties:
fulfillment_state:
description: The state of fulfillment during which this term is applicable.
allOf:
- $ref: "#/components/schemas/State"
refund_eligible:
description: Indicates if cancellation will result in a refund
type: boolean
refund_within:
description: Time within which refund will be processed after successful cancellation.
allOf:
- $ref: "#/components/schemas/Time"
refund_amount:
$ref: "#/components/schemas/Price"
replacement_terms:
description: Terms that are applicable be met when this item is replaced
type: array
items:
$ref: "#/components/schemas/ReplacementTerm"
return_terms:
description: Terms that are applicable when this item is returned
type: array
items:
$ref: "#/components/schemas/ReturnTerm"
xinput:
description: Additional input required from the customer to purchase / avail this item
allOf:
- $ref: "#/components/schemas/XInput"
time:
description: Temporal attributes of this item. This property is used when the item exists on the catalog only for a limited period of time.
allOf:
- $ref: "#/components/schemas/Time"
rateable:
description: Whether this item can be rated
type: boolean
rating:
description: The rating of the item
allOf:
- $ref: "#/components/schemas/Rating/properties/value"
matched:
description: Whether this item is an exact match of the request
type: boolean
related:
description: Whether this item is a related item to the exactly matched item
type: boolean
recommended:
description: Whether this item is a recommended item to a response
type: boolean
ttl:
description: Time to live in seconds for an instance of this schema
type: string
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
Location:
description: The physical location of something
type: object
properties:
id:
type: string
descriptor:
$ref: "#/components/schemas/Descriptor"
map_url:
description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy.
type: string
format: uri
gps:
description: The GPS co-ordinates of this location.
allOf:
- $ref: "#/components/schemas/Gps"
address:
description: The address of this location.
allOf:
- $ref: "#/components/schemas/Address"
city:
description: "The city this location is, or is located within"
allOf:
- $ref: "#/components/schemas/City"
district:
description: "The state this location is, or is located within"
type: string
state:
description: "The state this location is, or is located within"
allOf:
- $ref: "#/components/schemas/State"
country:
description: "The country this location is, or is located within"
allOf:
- $ref: "#/components/schemas/Country"
area_code:
type: string
circle:
$ref: "#/components/schemas/Circle"
polygon:
description: The boundary polygon of this location
type: string
3dspace:
description: The three dimensional region describing this location
type: string
rating:
description: The rating of this location
allOf:
- $ref: "#/components/schemas/Rating/properties/value"
MediaFile:
description: This object contains a url to a media file.
type: object
properties:
mimetype:
description: "indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF's RFC 6838"
type: string
url:
description: The URL of the file
type: string
format: uri
signature:
description: The digital signature of the file signed by the sender
type: string
dsa:
description: The signing algorithm used by the sender
type: string
Offer:
description: An offer associated with a catalog. This is typically used to promote a particular product and enable more purchases.
type: object
properties:
id:
type: string
descriptor:
$ref: "#/components/schemas/Descriptor"
location_ids:
type: array
items:
$ref: "#/components/schemas/Location/properties/id"
category_ids:
type: array
items:
$ref: "#/components/schemas/Category/properties/id"
item_ids:
type: array
items:
$ref: "#/components/schemas/Item/properties/id"
time:
$ref: "#/components/schemas/Time"
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
Option:
description: Describes a selectable option
type: object
properties:
id:
type: string
descriptor:
$ref: "#/components/schemas/Descriptor"
Order:
description: Describes a legal purchase order. It contains the complete details of the legal contract created between the buyer and the seller.
type: object
properties:
id:
type: string
description: Human-readable ID of the order. This is generated at the BPP layer. The BPP can either generate order id within its system or forward the order ID created at the provider level.
ref_order_ids:
description: A list of order IDs to link this order to previous orders.
type: array
items:
type: string
description: ID of a previous order
status:
description: Status of the order. Allowed values can be defined by the network policy
type: string
enum:
- ACTIVE
- COMPLETE
- CANCELLED
type:
description: "This is used to indicate the type of order being created to BPPs. Sometimes orders can be linked to previous orders, like a replacement order in a retail domain. A follow-up consultation in healthcare domain. A single order part of a subscription order. The list of order types can be standardized at the network level."
type: string
default: DEFAULT
enum:
- DRAFT
- DEFAULT
provider:
description: Details of the provider whose catalog items have been selected.
allOf:
- $ref: "#/components/schemas/Provider"
items:
description: The items purchased / availed in this order
type: array
items:
$ref: "#/components/schemas/Item"
add_ons:
description: The add-ons purchased / availed in this order
type: array
items:
$ref: "#/components/schemas/AddOn"
offers:
description: The offers applied in this order
type: array
items:
$ref: "#/components/schemas/Offer"
billing:
description: The billing details of this order
allOf:
- $ref: "#/components/schemas/Billing"
fulfillments:
description: The fulfillments involved in completing this order
type: array
items:
$ref: "#/components/schemas/Fulfillment"
cancellation:
description: The cancellation details of this order
allOf:
- $ref: "#/components/schemas/Cancellation"
cancellation_terms:
description: Cancellation terms of this item
type: array
items:
$ref: "#/components/schemas/CancellationTerm"
refund_terms:
description: Refund terms of this item
type: array
items:
$ref: "#/components/schemas/Item/properties/refund_terms/items"
replacement_terms:
description: Replacement terms of this item
type: array
items:
$ref: "#/components/schemas/ReplacementTerm"
return_terms:
description: Return terms of this item
type: array
items:
$ref: "#/components/schemas/ReturnTerm"
quote:
description: The mutually agreed upon quotation for this order.
allOf:
- $ref: "#/components/schemas/Quotation"
payments:
description: The terms of settlement for this order
type: array
items:
$ref: "#/components/schemas/Payment"
created_at:
description: The date-time of creation of this order
type: string
format: date-time
updated_at:
description: The date-time of updated of this order
type: string
format: date-time
xinput:
description: Additional input required from the customer to confirm this order
allOf:
- $ref: "#/components/schemas/XInput"
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
Organization:
description: An organization. Usually a recognized business entity.
type: object
properties:
descriptor:
$ref: "#/components/schemas/Descriptor"
address:
description: The postal address of the organization
allOf:
- $ref: "#/components/schemas/Address"
state:
description: The state where the organization's address is registered
allOf:
- $ref: "#/components/schemas/State"
city:
description: The city where the the organization's address is registered
allOf:
- $ref: "#/components/schemas/City"
contact:
$ref: "#/components/schemas/Contact"
Payment:
description: "Describes the terms of settlement between the BAP and the BPP for a single transaction. When instantiated, this object contains - 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
collected_by:
description: "This field indicates who is the collector of payment. The BAP can set this value to 'bap' if it wants to collect the payment first and settle it to the BPP. If the BPP agrees to those terms, the BPP should not send the payment url. Alternatively, the BPP can set this field with the value 'bpp' if it wants the payment to be made directly."
url:
type: string
description: "A payment url to be called by the BAP. If empty, then the payment is to be done offline. The details of payment should be present in the params object. If tl_method = http/get, then the payment details will be sent as url params. Two url param values, ```$transaction_id``` and ```$amount``` are mandatory."
format: uri
params:
type: object
properties:
transaction_id:
type: string
description: The reference transaction ID associated with a payment activity
amount:
type: string
currency:
type: string
bank_code:
type: string
bank_account_number:
type: string
virtual_payment_address:
type: string
source_bank_code:
type: string
source_bank_account_number:
type: string
source_virtual_payment_address:
type: string
type:
type: string
enum:
- PRE-ORDER
- PRE-FULFILLMENT
- ON-FULFILLMENT
- POST-FULFILLMENT
status:
type: string
enum:
- PAID
- NOT-PAID
time:
$ref: "#/components/schemas/Time"
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
Person:
description: Describes a person as any individual
type: object
properties:
id:
type: string
description: Describes the identity of the person
url:
description: Profile url of the person
type: string
format: uri
name:
description: the name of the person
type: string
image:
$ref: "#/components/schemas/Image"
age:
description: Age of the person
allOf:
- $ref: "#/components/schemas/Duration"
dob:
description: Date of birth of the person
type: string
format: date
gender:
type: string
description: "Gender of something, typically a Person, but possibly also fictional characters, animals, etc. While Male and Female may be used, text strings are also acceptable for people who do not identify as a binary gender.Allowed values for this field can be published in the network policy"
creds:
type: array
items:
$ref: "#/components/schemas/Credential"
languages:
type: array
items:
description: Describes a language known to the person.
type: object
properties:
code:
type: string
name:
type: string
skills:
type: array
items:
description: Describes a skill of the person.
type: object
properties:
code:
type: string
name:
type: string
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
Price:
description: Describes the price of a product or service
type: object
properties:
currency:
type: string
value:
$ref: "#/components/schemas/DecimalValue"
estimated_value:
$ref: "#/components/schemas/DecimalValue"
computed_value:
$ref: "#/components/schemas/DecimalValue"
listed_value:
$ref: "#/components/schemas/DecimalValue"
offered_value:
$ref: "#/components/schemas/DecimalValue"
minimum_value:
$ref: "#/components/schemas/DecimalValue"
maximum_value:
$ref: "#/components/schemas/DecimalValue"
Provider:
description: Describes the catalog of a business.
type: object
properties:
id:
type: string
description: Id of the provider
descriptor:
$ref: "#/components/schemas/Descriptor"
category_id:
type: string
description: Category Id of the provider at the BPP-level catalog
rating:
$ref: "#/components/schemas/Rating/properties/value"
time:
$ref: "#/components/schemas/Time"
categories:
type: array
items:
$ref: "#/components/schemas/Category"
fulfillments:
type: array
items:
$ref: "#/components/schemas/Fulfillment"
payments:
type: array
items:
$ref: "#/components/schemas/Payment"
locations:
type: array
items:
$ref: "#/components/schemas/Location"
offers:
type: array
items:
$ref: "#/components/schemas/Offer"
items:
type: array
items:
$ref: "#/components/schemas/Item"
exp:
type: string
description: Time after which catalog has to be refreshed
format: date-time
rateable:
description: Whether this provider can be rated or not
type: boolean
ttl:
description: "The time-to-live in seconds, for this object. This can be overriden at deeper levels. A value of -1 indicates that this object is not cacheable."
type: integer
minimum: -1
tags:
type: array
items:
$ref: "#/components/schemas/TagGroup"
Quotation:
description: "Describes a quote. It is the estimated price of products or services from the BPP.
This has properties like price, breakup, ttl"
type: object
properties:
id:
description: ID of the quote.
type: string
format: uuid
price:
description: The total quoted price
allOf:
- $ref: "#/components/schemas/Price"
breakup:
description: the breakup of the total quoted price
type: array
items:
type: object
properties:
item:
$ref: "#/components/schemas/Item"
title:
type: string
price:
$ref: "#/components/schemas/Price"
ttl:
$ref: "#/components/schemas/Duration"
Rating:
description: Describes the rating of an entity
type: object
properties:
rating_category:
description: Category of the entity being rated
type: string
enum:
- Item
- Order
- Fulfillment
- Provider
- Agent
- Support
id:
description: Id of the object being rated
type: string
value:
description: "Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||."
type: string
Region:
description: Describes an arbitrary region of space. The network policy should contain a published list of supported regions by the network.
type: object
properties:
dimensions:
description: "The number of dimensions that are used to describe any point inside that region. The most common dimensionality of a region is 2, that represents an area on a map. There are regions on the map that can be approximated to one-dimensional regions like roads, railway lines, or shipping lines. 3 dimensional regions are rarer, but are gaining popularity as flying drones are being adopted for various fulfillment services."
type: string
enum:
- "1"
- "2"
- "3"
type:
description: "The type of region. This is used to specify the granularity of the region represented by this object. Various examples of two-dimensional region types are city, country, state, district, and so on. The network policy should contain a list of all possible region types supported by the network."
type: string
name:
type: string
description: Name of the region as specified on the map where that region exists.
code:
type: string
description: A standard code representing the region. This should be interpreted in the same way by all network participants.
boundary:
type: string
description: "A string representing the boundary of the region. One-dimensional regions are represented by polylines. Two-dimensional regions are represented by polygons, and three-dimensional regions can represented by polyhedra."
map_url:
type: string
description: The url to the map of the region. This can be a globally recognized map or the one specified by the network policy.
ReplacementTerm:
description: The replacement policy of an item or an order
type: object
properties:
fulfillment_state:
description: The state of fulfillment during which this term is applicable.
allOf:
- $ref: "#/components/schemas/State"
replace_within:
description: "Applicable only for buyer managed returns where the buyer has to replace the item before a certain date-time, failing which they will not be eligible for replacement"
allOf:
- $ref: "#/components/schemas/Time"
external_ref:
$ref: "#/components/schemas/MediaFile"
ReturnTerm:
description: Describes the return policy of an item or an order
type: object
properties:
fulfillment_state:
description: The state of fulfillment during which this term IETF''s applicable.
allOf:
- $ref: "#/components/schemas/State"
return_eligible:
description: Indicates whether the item is eligible for return
type: boolean
return_time:
description: "Applicable only for buyer managed returns where the buyer has to return the item to the origin before a certain date-time, failing which they will not be eligible for refund."
allOf:
- $ref: "#/components/schemas/Time"
return_location:
description: The location where the item or order must / will be returned to
allOf:
- $ref: "#/components/schemas/Location"
fulfillment_managed_by:
description: The entity that will perform the return
type: string
enum:
- CONSUMER
- PROVIDER
Scalar:
description: Describes a scalar
type: object
properties:
type:
type: string
enum:
- CONSTANT
- VARIABLE
value:
$ref: "#/components/schemas/DecimalValue"
estimated_value:
$ref: "#/components/schemas/DecimalValue"
computed_value:
$ref: "#/components/schemas/DecimalValue"
range:
type: object
properties:
min:
$ref: "#/components/schemas/DecimalValue"
max:
$ref: "#/components/schemas/DecimalValue"
unit:
type: string
Schedule:
description: "Describes schedule as a repeating time period used to describe a regularly recurring event. At a minimum a schedule will specify frequency which describes the interval between occurrences of the event. Additional information can be provided to specify the schedule more precisely. This includes identifying the timestamps(s) of when the event will take place. Schedules may also have holidays to exclude a specific day from the schedule.
This has properties like frequency, holidays, times"
type: object
properties:
frequency:
$ref: "#/components/schemas/Duration"
holidays:
type: array
items:
type: string
format: date-time
times:
type: array
items:
type: string
format: date-time
State:
description: A bounded geopolitical region of governance inside a country.
type: object
properties:
name:
type: string
description: Name of the state
code:
type: string
description: State code as per country or international standards
Stop:
description: A logical point in space and time during the fulfillment of an order.
type: object
properties:
id:
type: string
parent_stop_id:
type: string
location:
description: Location of the stop
allOf:
- $ref: "#/components/schemas/Location"
type:
description: The type of stop. Allowed values of this property can be defined by the network policy.
type: string
time:
description: Timings applicable at the stop.
allOf:
- $ref: "#/components/schemas/Time"
instructions:
description: Instructions that need to be followed at the stop
allOf:
- $ref: "#/components/schemas/Descriptor"
contact:
description: Contact details of the stop
allOf:
- $ref: "#/components/schemas/Contact"
person:
description: The details of the person present at the stop
allOf:
- $ref: "#/components/schemas/Person"
authorization:
$ref: "#/components/schemas/Authorization"
Support:
description: Details of customer support
type: object
properties:
ref_id:
type: string
callback_phone:
type: string
format: phone
phone:
type: string
format: phone
email:
type: string
format: email
url:
type: string
format: uri
Tag:
description: "Describes a tag. This is used to contain extended metadata. This object can be added as a property to any schema to describe extended attributes. For BAPs, tags can be sent during search to optimize and filter search results. BPPs can use tags to index their catalog to allow better search functionality. Tags are sent by the BPP as part of the catalog response in the `on_search` callback. Tags are also meant for display purposes. Upon receiving a tag, BAPs are meant to render them as name-value pairs. This is particularly useful when rendering tabular information about a product or service."
type: object
properties:
descriptor:
description: "Description of the Tag, can be used to store detailed information."
allOf:
- $ref: "#/components/schemas/Descriptor"
value:
description: The value of the tag. This set by the BPP and rendered as-is by the BAP.
type: string
display:
description: "This value indicates if the tag is intended for display purposes. If set to `true`, then this tag must be displayed. If it is set to `false`, it should not be displayed. This value can override the group display value."
type: boolean
TagGroup:
description: "A collection of tag objects with group level attributes. For detailed documentation on the Tags and Tag Groups schema go to https://github.com/beckn/protocol-specifications/discussions/316"
type: object
properties:
display:
description: "Indicates the display properties of the tag group. If display is set to false, then the group will not be displayed. If it is set to true, it should be displayed. However, group-level display properties can be overriden by individual tag-level display property. As this schema is purely for catalog display purposes, it is not recommended to send this value during search."
type: boolean
default: true
descriptor:
description: "Description of the TagGroup, can be used to store detailed information."
allOf:
- $ref: "#/components/schemas/Descriptor"
list:
description: "An array of Tag objects listed under this group. This property can be set by BAPs during search to narrow the `search` and achieve more relevant results. When received during `on_search`, BAPs must render this list under the heading described by the `name` property of this schema."
type: array
items:
$ref: "#/components/schemas/Tag"
Time:
description: "Describes time in its various forms. It can be a single point in time; duration; or a structured timetable of operations
This has properties like label, time stamp,duration,range, days, schedule"
type: object
properties:
label:
type: string
timestamp:
type: string
format: date-time
duration:
$ref: "#/components/schemas/Duration"
range:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
days:
type: string
description: comma separated values representing days of the week
schedule:
$ref: "#/components/schemas/Schedule"
Tracking:
description: Contains tracking information that can be used by the BAP to track the fulfillment of an order in real-time. which is useful for knowing the location of time sensitive deliveries.
type: object
properties:
id:
description: A unique tracking reference number
type: string
url:
description: "A URL to the tracking endpoint. This can be a link to a tracking webpage, a webhook URL created by the BAP where BPP can push the tracking data, or a GET url creaed by the BPP which the BAP can poll to get the tracking data. It can also be a websocket URL where the BPP can push real-time tracking data."
type: string
format: uri
location:
description: "In case there is no real-time tracking endpoint available, this field will contain the latest location of the entity being tracked. The BPP will update this value everytime the BAP calls the track API."
allOf:
- $ref: "#/components/schemas/Location"
status:
description: "This value indicates if the tracking is currently active or not. If this value is `active`, then the BAP can begin tracking the order. If this value is `inactive`, the tracking URL is considered to be expired and the BAP should stop tracking the order."
type: string
enum:
- active
- inactive
Vehicle:
description: "Describes a vehicle is a device that is designed or used to transport people or cargo over land, water, air, or through space.
This has properties like category, capacity, make, model, size,variant,color,energy_type,registration"
type: object
properties:
category:
type: string
capacity:
type: integer
make:
type: string
model:
type: string
size:
type: string
variant:
type: string
color:
type: string
energy_type:
type: string
registration:
type: string
wheels_count:
type: string
cargo_volumne:
type: string
wheelchair_access:
type: string
code:
type: string
emission_standard:
type: string
XInput:
description: "Contains any additional or extended inputs required to confirm an order. This is typically a Form Input. Sometimes, selection of catalog elements is not enough for the BPP to confirm an order. For example, to confirm a flight ticket, the airline requires details of the passengers along with information on baggage, identity, in addition to the class of ticket. Similarly, a logistics company may require details on the nature of shipment in order to confirm the shipping. A recruiting firm may require additional details on the applicant in order to confirm a job application. For all such purposes, the BPP can choose to send this object attached to any object in the catalog that is required to be sent while placing the order. This object can typically be sent at an item level or at the order level. The item level XInput will override the Order level XInput as it indicates a special requirement of information for that particular item. Hence the BAP must render a separate form for the Item and another form at the Order level before confirmation."
type: object
properties:
form:
$ref: "#/components/schemas/Form"
required:
description: Indicates whether the form data is mandatorily required by the BPP to confirm the order.
type: boolean