The Transactions API from Sheeva — 3 operation(s) for transactions.
openapi: 3.0.3
info:
title: SheevaConnect Authentication Transactions API
version: '2.0'
description: 'This SheevaConnect™ API Specification 2.0 is © 2024 Parkofon Inc. (d/b/a Sheeva.AI) and is proprietary information that may not be duplicated, redistributed, form the basis of derivative works, or publicly performed/displayed without the expressed written permission of Sheeva.AI. If you wish to use the SheevaConnect™ API Specification 2.0 and use the SheevaConnect™ cloud platform, please contact Sheeva.AI for a license.
SheevaConnect APIs enable connected vehicle payments & last-mile services for various use cases including Fueling, EV Charging, Parking and Retail. This solution allows automated & contactless payment in addition to proactive identification of user needs and last-mile navigation to the nearest Sheeva Pay enabled outlets.
All APIs follow HTTP status codes, return HTTP 200 OK when successful and following HTTP errors with a message. The message is self explaining to indicate the error in request. The example error codes include :
Error Code
Message
400
Bad Request : Check the parameter values
404
Resource not found
500
Internal Server Error
SheevaConnect creates a session when system detects that vehicle requires a service (FUEL, CHARGING, PARKING). Each session goes through various statuses.
Session Status Codes
Status
Description
LOW_FUEL_DETECTED
If vehicle was low on fuel and system has sent the notification to driver for low fuel or if vehicle is not low on fuel but driver clicks on fuel icon to pay.
LOW_CHARGE_DETECTED
If vehicle was low on charge and system has sent the notification to driver for low charged or if vehicle is not low on chrage but driver clicks on charge icon to pay.
AT_SERVICE_HUB
The driver has reached the fuel station / EV charge station / etc.
AT_SERVICE_POINT
The driver is at fuel pump / charging bay.
SERVICE_POINT_CONFIRMED
Driver confirms the fuel pump / charging bay.
SERVICE_IN_PROGRESS
When driver uses a parking service and vehicle is parked
SERVICE_COMPLETE
When user marks the fuel, charging, parking complete
SERVICE_CANCELLED_BY_DRIVER
When user cancel the service at the pump/ charging bay
SERVICE_ABORTED_BY_SYSTEM
When user does opt for service and move away from fuel pump/ charging bay
Payment Status Codes
Status
Description
PAYMENT_AUTHORIZED
When a payment is authorized. Only applicable for Credit Card, Wallet and Rewards.
PAYMENT_INITIATED
When a payment is in progress. Only applicable for UPI in India.
PAYMENT_COMPLETE
Payment has been processed for a g'
contact:
name: Sheeva.AI
url: https://sheeva.ai/contact-us
x-company: Parkofon Inc. (d/b/a Sheeva.AI)
servers:
- url: https://us-apis.sheeva.ai
description: Production (USA)
- url: https://in-apis.sheeva.ai
description: Production (India)
- url: https://dev-us-apis.sheeva.ai
description: Sandbox (USA)
- url: https://dev-in-apis.sheeva.ai
description: Sandbox (India)
security:
- bearerAuth: []
tags:
- name: Transactions
paths:
/v2/partner-apis/transactions:
get:
summary: Get Payment Transactions
operationId: getPaymentTransactions
tags:
- Transactions
responses:
'200':
description: Response
content:
application/json:
example:
transactions:
- paymentId: pay_2y2aDe6BEqbLCYJlgLcd
transactionId: 10261296-166853171260
sessionId: fuel_BOuBK76KoPMICbp14Ute
serviceHub:
name: ICar Port
streetAddress: 10B, Ram Nagar, Chennai
vehicle:
licensePlate: MH 01 AB 1234
model: Compass
make: Jeep
year: 2023
color: RED
status: SERVICE_COMPLETE
paymentStatus: PAYMENT_COMPLETE
serviceType: FUEL
currency: INR
amount: 100.0
paymentType: upi
createdAt: 1668531651000
metadata:
result_set:
count: 25
offset: 0
limit: 25
total: 77
description: 'This request returns payment transactions done by the driver or by the vin/vehicle. This API supports pagination.
Response Body Field Descriptions :
Field
Description
paymentId
Sheeva.AI unique paymentId
transactionId
Order number for this transaction
driverId
Sheeva.AI unique driverId
vin
Unique vehicle identifier
sessionId
Service type session identifier
poiName
Point of Interest (POI) name - station name for fuel service
licensePlate
Vehicle registration number
status
Session status code (Refer definitions of Session Status Codes above)
paymentStatus
Payment status (Refer definitions of Payment Status Codes above)
serviceType
Service availed with this transaction
currency
Currency code
model
Vehicle model
amount
Transaction amount
rewardAmount
Reward amo'
parameters:
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
/v2/partner-apis/transactions/details:
get:
summary: Get Payment Transactions Details
operationId: getPaymentTransactionsDetails
tags:
- Transactions
responses:
'200':
description: OK
content:
application/json:
example:
driver:
driverId: dri_dafa233
firstName: Lokesh
lastName: Kumar
transaction:
vehicle:
vin: HUT242424242
licensePlate: MH 01 AB 1234
model: Compass
make: Jeep
year: 2023
color: RED
fuelTypes:
- diesel
connectorType: J1772
active: true
serviceHub:
id: fst_dbe5bcc470b1cb3e5375
name: ICar Port
pump: '3'
location: 19.102809,72.873848
logoUrl: https://dev-in-sheeva-tandc.s3.ap-south-1.amazonaws.com/iocl_logo.png
addressDetails:
streetAddress: Aarey Colony, Goregaon
city: Mumbai
state: Maharashtra
zipCode: '400065'
country: India
paymentId: pay_2y2aDe6BEqbLCYJlgLcd
transactionId: 10261296-166853171260
sessionId: fuel_BOuBK76KoPMICbp14Ute
status: SERVICE_COMPLETE
paymentStatus: PAYMENT_COMPLETE
serviceType: FUEL
currency: INR
amount: 100.0
paymentInstruments:
- type: upi
amount: 50.0
transactionId: AXI59bc02049a9447c0bf53e8367175ac42
- type: rewards
name: Sheeva Rewards
organization: Sheeva
serviceProviderCode: Sheeva
serviceProviderName: Sheeva
amount: 20.0
transactionId: rewards-sheeva-1213141
- type: rewards
name: IOCL XtraRewards
organization: IOCL
serviceProviderCode: IOCL
serviceProviderName: Indian Oil Corporation
amount: 30.0
transactionId: rewards-iocl-xtra-12412412
rewardsEarned:
- type: rewards
name: Sheeva Rewards
organization: Sheeva
serviceProviderCode: Sheeva
serviceProviderName: Sheeva
points: 100
amount: 10
transactionId: rewards-sheeva-1213142
createdAt: 1668531651000
description: 'This request returns the details of a single payment transaction.
If successful, returns: HTTP 200 OK.
Response Body Field Description:
Field
Description
paymentId
Sheeva.AI unique paymentId
transactionId
Order number for this transaction
driverId
Sheeva.AI unique driverId
vehicleId
Unique vehicle identifier
sessionId
Service type session identifier
poiName
Point of Interest (POI) name - station name for fuel service
licensePlate
Vehicle registration number
status
Transaction status: COMPLETED Transaction was completed successfully FAILED Transaction failed DISCARDED Transaction was not attempted within the time limit, hence discarded.
serviceType
Service availed with this transaction: [FUEL, CHARGING, PARKING, TOLL, etc.]
currency
Currency code: [E.g.: USD, INR'
parameters:
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
/v2/partner-apis/transactions/receipt:
get:
summary: Get Payment Receipt
operationId: getPaymentReceipt
tags:
- Transactions
responses:
'200':
description: Response
content:
application/json:
example:
receiptStatus: NOT_AVAILABLE
description: 'This request triggers sending the PDF receipt URL to a messaging channel, currently WhatsApp.
If successful, returns: HTTP 200 OK.
'
parameters:
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Access token obtained from GET /v2/auth (exchange client-id/client-secret), sent in the Authorization header.
clientCredentials:
type: apiKey
in: header
name: client-id
description: client-id + client-secret headers on GET /v2/auth to obtain an access token.