Stop a charge

Description#

When a charge has been succesfully stopped or has been rejected by the chargebox, Thor will send a notification to your system. To receive this message you'll have to configure the Stop charge section of the API integration.

If you want to know more about the remote charge workflow, take a look to this guide or this guide.

Request format#

Method: POST

Body format: JSON

Key	Type	Description
type	String	Specifies that this message is a stop charge notification. For this request it will be always equal to "stop_transaction".
msg	String	Like "type" specifies the type of the message. It will be always equal to `stop`. Used only when notifying an unlock connector or a rejected remote stop
accepted	Boolean	`true` if the transaction has succesfully finished.
unlocked	Boolean	`true` if the connector was unlocked.
chargebox	String	The chargebox identifier.
idTag	String	The RFID value or the value generated by the server returned here (`""` when `unlocked = true`).
connector	Integer	The connector where the charge has been stopped or rejected.
transaction_id	Integer	The transaction progressive (`0` when `accepted = false` or `unlocked = true`).
kwh	Integer	The total energy consumed by the vehicle (might be `0` if the chargebox doesn't have a dedicated metering reader for each connector).
energy	Integer	The total energy consumed by the vehicle (might be `0` if the chargebox doesn't have a dedicated metering reader for each connector). Used only with msg.
time	Integer	The total time used by the transaction from the start
payment	Payment	(if available for client) The settings of the payment choosen by client to calculate che total price

Request schema:

{
    "$schema": "http://json-schema.org/draft-07/schema",
    "id": "http://example.com/example.json",
    "type": "object",
    "title": "The root schema",
    "description": "The root schema comprises the entire JSON document.",
    "default": {},
    "examples": [
        {
            "type": "stop_transaction",
            "chargebox": "EaJ7cU9NJ3YkTNgy",
            "transaction_id": 52,
            "id_tag": "0012847382",
            "kwh": 240,
            "unlocked": false,
            "accepted": true
        },
        {
            "msg": "stop",
            "chargebox": "XPHiIU27EFMViHat",
            "connector": 1,
            "transaction_id": 0,
            "id_tag": "172osiu83hys82shy28j",
            "energy": 0,
            "unlocked": true,
            "accepted": true
        }
    ],
    "required": [
        "msg",
        "chargebox",
        "connector",
        "transaction_id",
        "id_tag",
        "energy",
        "unlocked",
        "accepted"
    ],
    "properties": {
        "msg": {
            "$id": "http://example.com/properties/type",
            "type": "string",
            "enum":[
                "stop"
            ],
            "title": "The type schema",
            "description": "Specifies that this message is a stop charge notification.",
            "default": "",
            "examples": [
                "stop_transaction"
            ]
        },
        "chargebox": {
            "id": "http://example.com/properties/chargebox",
            "type": "string",
            "title": "The chargebox schema",
            "description": "The chargebox identifier.",
            "default": "",
            "examples": [
                "EaJ7cU9NJ3YkTNgy",
                "XPHiIU27EFMViHat"
            ]
        },
        "connector": {
            "id": "http://example.com/properties/connector",
            "type": "integer",
            "title": "The connector schema",
            "description": "The connector where the charge has been stopped or rejected.",
            "default": 0,
            "examples": [
                1,
                2,
                3,
                4
            ]
        },
        "transaction_id": {
            "id": "http://example.com/properties/transaction_id",
            "type": "integer",
            "title": "The transaction_id schema",
            "description": "The transaction progressive.",
            "default": 0,
            "examples": [
                75,
                22,
                458
            ]
        },
        "idTag": {
            "id": "http://example.com/properties/idTag",
            "type": "string",
            "title": "The idTag schema",
            "description": "The RFID value or the value generated by the server.",
            "default": "",
            "examples": [
                "0012847382",
                "172osiu83hys82shy28j"
            ]
        },
        "kwh": {
            "id": "http://example.com/properties/kwh",
            "type": "integer",
            "title": "The kwh schema",
            "description": "The total energy consumed by the vehicle.",
            "default": 0,
            "examples": [
                0,
                240,
                1485
            ]
        },
        "time": {
            "id": "http://example.com/properties/time",
            "type": "integer",
            "title": "The time schema",
            "description": "The total time used by the vehicle for the charge in milliseconds.",
            "default": 0,
            "examples": [
                0,
                240,
                1485
            ]
        },
        "unlocked": {
            "id": "http://example.com/properties/unlocked",
            "type": "boolean",
            "title": "The unlocked schema",
            "description": "true if the connector was unlocked.",
            "default": false,
            "examples": [
                false,
                true
            ]
        },
        "accepted": {
            "id": "http://example.com/properties/accepted",
            "type": "boolean",
            "title": "The accepted schema",
            "description": "true if the transaction has succesfully finished.",
            "default": false,
            "examples": [
                false,
                true
            ]
        }
    },
    "additionalProperties": true
}

Expected response#

A nice 200 - OK is more than enough for Thor. If you choose the API payment management Thor expects to receive 200 - OK and the amount in a JSON in this format:

{
    "amount": "12.3"
}

How can a charge be stopped?#

There are 4 way that cause the stop of a charge:

An API call as described here and here.
The user has shown the RFID card used to start the charge locally (more info).
The administrator sent a Stop charge to the chargebox through Thor's administration dashboard.
The administrator sent an Unlock connector to the chargebox through Thor's administration dashboard.

The difference between the last two points described above is subtle, but basically those are two different OCPP messages, and the unlock connector is more drastic. On Thor we use the Unlock connector feature in case a chargebox keeps rejecting the stop message because something went wrong and we don't want the user to pay for the charge.