Menu Close

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
}