Transaction Management

Create a new transaction

Request a new charging session to be started at the specified EVSE port. A queue_uuid and transaction_uuid are returned that can be used to check the status of the request and the transaction later, respectively. Additionally, an invoice_id can be optionally added to the transaction for future reference.

Arguments

Name	Description	Type
port_uuid	EVSE to start transaction at	string
expires	ISO 8601 Timestamp - must be in UTC and in the future	string
invoice_id	(Optional) An invoice ID to reference in the future for any given reason	string

Arguments are passed in the payload with the following format:

{
  "port_uuid": "f1985d47-a946-4400-ba52-c00bb0c2cc0f",
  "expires": "2022-09-24T20:40:00+0000",
  "invoice_id": "c77ef908-61cd-4787-934f-753b34eaee63"
}

HTTP Response

Code	Reason
201	Successfully created
400	Argument issues: Time must be in future Missing fields Wrong types
401	Incorrect credentials
404	EVSE not found

POST /transactions

Example Request

curl -X POST -H "x-api-key: <api_key>" \
  --H "Content-Type: application/json" \
  -v --data '{"expires":"2022-09-24T19:05:00+0000","port_uuid":"f1985d47-a946-4400-ba52-c00bb0c2cc0f", "invoice_id": "c77ef908-61cd-4787-934f-753b34eaee63"}' \
  https://api.ocpp.swyched.com/1.2/transactions

Response

Successful Example

{
  "href": "/queue/b24asde-05e5-46ad-bawa9-1871eaasbd6",
  "queue_uuid": "b24asde-05e5-46ad-bawa9-1871eaasbd6",
  "transaction_uuid": "4852c8fe-2c53-4117-aaaf-e80370325507" 
}

Failure Example

{
  "message": "Expiry time must be in the future. Please ensure the time you have entered is in the correct timezone (UTC) and try again. Current UTC time is 2022-02-03T23:39:48. Received UTC time is 2022-01-05 20:40:00+00:00."
}

Staging Arguments

Name	Description	Type
stg	Staging indicator. Set to: true	boolean

Argument is passed in the payload. Example:

{
    "stg": true
}

Get result from queue

This endpoint is what you need to call to check the status of the request to start a charging transaction. On a successful start, the API will return the details of the transaction. If the transaction failed to start or is still in progress, the API will return the status of the process.

Arguments

Name	Description	Type
queue_uuid	Queue to inspect - Must be a valid UUID	string

Argument is passed as a route parameter with the following format:

/queue/<queue_uuid>

HTTP Response

Code	Reason
200	Current status of transaction in queue returned (unless it has already started)
400	Invalid queue uuid (not UUID)
401	Incorrect credentials
404	Queue item not found

GET /queue/<queue_uuid>

Example Request

curl -H "x-api-key: <api_key>"  -v https://api.ocpp.swyched.com/1.2/queue/b24asde-05e5-46ad-bawa9-1871eaasbd6

Response

On success

{
  "transaction_uuid": "5fbfc769-da14-46de-a37d-a1802ba0cdd6",
  "port_uuid": "f1985d47-a946-4400-ba52-c00bb0c2cc0f",
  "state": "Open", 
  "started": "2022-09-24T22:15:13",
  "ended": null,
  "expires": "2022-09-24T23:15:13"
}

On failure

{
  "id": "f1985d47-a946-4400-ba52-c00bb0c2cc0f", 
  "status": "FAILURE",
  "reason": (reason for failure is displayed here)
}

Task in progress

{
  "id": "f1985d47-a946-4400-ba52-c00bb0c2cc0f", 
  "status": "IN PROGRESS"
}

Staging Arguments

Name	Description	Type
stg	Staging indicator. Set to: true	boolean
stg_input	Staging input. Set to one of the following: "Success", "Failure", "InProgress"	string

Argument is passed in the payload. Example:

{
    "stg": true,
    "stg_input": "Success"
}

Get one or more transactions of an EVSE

Use this method to obtain a specific amount of transactions for an EVSE port, including the transaction_uuid. Specify the number of transactions to pull from a port by setting the value of the required payload argument limit to an integer. Set it to 0 to pull all the transactions from that port. The result displays the transactions in descending order, showing the latest transactions first.

Arguments

Name	Description	Type
port_uuid	EVSE to get all transactions from	string
limit	Number of transactions to pull: 0 for all transactions of that port 1 or higher for the latest one or more transactions	integer

Arguments are passed in the payload with the following format:

{
  "port_uuid": "f1985d47-a946-4400-ba52-c00bb0c2cc0f",
  "limit": 2
}

HTTP Response

Code	Reason
200	Records found
400	Argument error: Missing field(s) Invalid type(s)
401	Incorrect credentials
404	No transactions exist for the EVSE

GET /transactions

Example Request

curl -H "x-api-key: <api_key>" -v --data '{"port_uuid": "f1985d47-a946-4400-ba52-c00bb0c2cc0f", "limit": 2}' https://api.ocpp.swyched.com/1.2/transactions

Response

Example: Latest two transactions of a specific port, i.e. "limit": 2

[
   {
       "transaction_uuid": "251dcc08-aa22-4f4c-9e18-19b39404622d",
       "port_uuid": "f1985d47-a946-4400-ba52-c00bb0c2cc0f",
       "state": "Closed",
       "started": "2022-07-23T20:29:07",
       "ended": "2022-07-23T23:01:47",
       "expires": "2022-07-23T23:00:00"
   },
   {
       "transaction_uuid": "bb2a1898-9c37-4540-aefb-73dca29be99b",
       "port_uuid": "f1985d47-a946-4400-ba52-c00bb0c2cc0f",
       "state": "Closed",
       "started": "2022-07-21T18:43:54",
       "ended": "2022-07-21T23:01:51",
       "expires": "2022-07-21T23:01:00"
   }
]

Staging Arguments

Name	Description	Type
stg	Staging indicator. Set to: true	boolean

Argument is passed in the payload. Example:

{
    "stg": true
}

Get a specific transaction

Use this method to obtain the details of a specific transaction using its transaction_uuid.

Arguments

Name	Description	Type
transaction_uuid	Transaction to get the details of	string

Arguments are passed in the payload with the following format:

/transactions/<transaction_uuid>

HTTP Response

Code	Reason
200	Records found
400	Argument error: Missing field(s) Invalid type(s)
401	Incorrect credentials
404	No transactions exist with the provided UUID

GET /transactions/<transaction_uuid>

Example Request

curl -H "x-api-key: <api_key>" -v https://api.ocpp.swyched.com/1.2/transactions/251dcc08-aa22-4f4c-9e18-19b39404622d

Response

Example: Latest two transactions of a specific port, i.e. "limit": 2

{
      "transaction_uuid": "251dcc08-aa22-4f4c-9e18-19b39404622d",
      "port_uuid": "f1985d47-a946-4400-ba52-c00bb0c2cc0f",
      "state": "Closed",
      "started": "2022-07-22T23:29:07",
      "ended": "2022-07-23T23:01:47",
      "expires": "2022-07-23T23:00:00"
}

Staging Arguments

Name	Description	Type
stg	Staging indicator. Set to: true	boolean

Argument is passed in the payload. Example:

{
    "stg": true
}

Modify an existing transaction

Use this method to terminate a transaction immediately OR extend the expires time. Only one modification can be included in the payload (i.e. either terminating a transaction or extending its expiration time). Use case example for the latter: users pay for additional charging minutes from their app.

Arguments (Route Parameters)

Name	Description	Type
transaction_uuid	The ID of the transaction at the EVSE to modify, obtained by using GET /transactions	integer

The above argument is passed as a route parameter with the following format:

/transactions/<transaction_uuid>

Arguments (Payload)

Name	Description	Type
expires	ISO 8601 Timestamp - must be in UTC and in the future; Mutually exclusive with state	string
state	State to set the transaction to; Only closed allowed; Pass closed to terminate the transaction immediately; Mutually exclusive with expires	string

Note: Only one of expires and state can be included in the payload. Otherwise, 400 will be returned.

The above arguments are passed in the payload with the following format:

{
  "state": "closed"
}

HTTP Response

Code	Reason
204	Successfully patched with expires
202	Request to stop charging transaction received. Check the status of stop charging transaction with the queue ID.
400	Issues with arguments; Check if payload was sent with both expires and state
401	Incorrect credentials
403	Transaction already ended, cannot modify
404	Transaction not found

PATCH /transactions/<transaction_uuid>

Example Request

curl -X PATCH -H "x-api-key: <api_key>" \
  --header "Content-Type: application/json" \
  -v --data '{"expires":"2022-09-24T19:05:00+0000"}' \
https://api.ocpp.swyched.com/1.2/transactions/251dcc08-aa22-4f4c-9e18-19b39404622d

Response

If expires was passed in payload:

No content on successful patch HTTP_STATUS = 204

If state was passed in payload:

{
  "href": "/queue/b220da0e-05e5-46ad-bba9-1871e5b29bd6",
  "id": "b220da0e-05e5-46ad-bba9-1871e5b29bd6"
}

Staging Arguments

Name	Description	Type
stg	Staging indicator. Set to: true	boolean

Argument is passed in the payload. Example:

{
    "stg": true
}

Swyched API

On this page