Skip to content

Fix pump statuses in pre-auth workflow documentation #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jpwenzel wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Fix pump statuses in pre-auth workflow documentation #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2824d9a
Fix pump statuses in pre-auth workflow documentation
jpwenzel Apr 15, 2026
9d9d6a6
Improving documentation about default pump status
jpwenzel Apr 15, 2026
bcde2d5
Update walkthrough/part-3.md
jpwenzel Apr 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 29 additions & 16 deletions walkthrough/part-3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,16 +129,16 @@ Pre-Auth is used outside Germany and for unmanned stations. The payment is pre-a
### Flow Overview

```
Pump status: free
Pump status: locked ← pre-auth idle state (default for Pre-Auth pumps)
↓ server sends UNLOCKPUMP
Pump status: locked
Pump status: free ← pump is now open for this specific customer to fuel
↓ customer starts fueling
Pump status: in-use
↓ customer finishes fueling
Pump status: locked ← back to locked, not ready-to-pay
Pump status: locked ← session still active, awaiting CLEAR (not ready-to-pay)
↓ client sends TRANSACTION (open, using FSCTransactionID)
↓ server sends CLEAR
Pump status: free
Pump status: locked ← back to pre-auth idle, available for the next mobile reservation / next Pre-Auth session
```

### Handling UNLOCKPUMP
Expand Down Expand Up @@ -169,7 +169,7 @@ S5 OK

Then update the pump status:
```
* PUMP 3 locked
* PUMP 3 free
```

Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section says that after a successful UNLOCKPUMP the client should publish * PUMP 3 free, but Part 4’s “Pre-Auth Flow with TRANSACTIONINFO” example currently publishes * PUMP 1 locked immediately after UNLOCKPUMP (walkthrough/part-4.md:204-207). Please align the docs (either update Part 4’s example/status or add a clarifying note here about the correct status transition).

Suggested change
> **Clarification:** Immediately after a successful `UNLOCKPUMP`, the pump should be published as `free` so the customer can begin fueling. If you see an example elsewhere in the walkthrough showing `locked` immediately after `UNLOCKPUMP`, treat that as outdated — `locked` is not the correct post-unlock status transition here.

Copilot uses AI. Check for mistakes.
**Errors to return:**
Expand Down Expand Up @@ -199,10 +199,10 @@ The server may cancel a Pre-Auth session before fueling begins by sending `LOCKP
S6 LOCKPUMP 3
```

Lock the pump, cancel the pending authorization on your side, and respond:
Cancel the pending authorization on your side and respond:
```
S6 OK
* PUMP 3 free
* PUMP 3 locked
```

Errors to return:
Expand All @@ -225,7 +225,14 @@ The `Reason` argument must be one of:
- `aborted` — zero fueling / customer walked away
- `timeout` — the system aborted due to timeout

The server responds `OK` if accepted, or one of:
The server responds `OK` if accepted. Once you receive that acknowledgement, send a pump status update to return the pump to its pre-auth idle state:

```
Server: C7 OK
Client: * PUMP 3 locked
```

Or the server returns one of these errors:

| Code | Meaning |
|---|---|
Expand All @@ -239,7 +246,7 @@ The server responds `OK` if accepted, or one of:

## Step 6: Implement CLEAR

`CLEAR` is the server's instruction to mark a transaction as paid and free the pump. It is used in both the Post-Pay and Pre-Auth flows.
`CLEAR` is the server's instruction to mark a transaction as paid and release the pump. It is used in both the Post-Pay and Pre-Auth flows. The pump status after a successful `CLEAR` differs between the two: Post-Pay pumps return to `free`; Pre-Auth pumps return to `locked` (their idle state).

**Incoming request:**
```
Expand All @@ -257,13 +264,18 @@ Arguments:

**On success:**
1. Mark the transaction as cleared in your POS.
2. Free the pump.
3. Reply `OK`.
4. Send a proactive pump status update:
2. Reply `OK`.
3. Send a proactive pump status update. The status to report depends on the flow:
- **Post-Pay:** return the pump to `free` — it is now idle and available for any customer.
- **Pre-Auth:** return the pump to `locked` — this is the Pre-Auth idle state, signalling it is available for the next mobile reservation.

```
S5 OK
* PUMP 3 free
* PUMP 3 free ← Post-Pay
```
```
S5 OK
* PUMP 3 locked ← Pre-Auth
```

**Important:** Mark cleared transactions in your reconciliation lists with "Clearance source: Connected Fueling" and the PaymentMethod used. This is required for back-office reconciliation with the payment operator.
Expand Down Expand Up @@ -346,7 +358,7 @@ Client: * PUMP 3 free

Server: S1 UNLOCKPUMP 3 EUR 100.00 e2f74ef5-f427-4ae6-bdd3-70a96709992f pace
Client: S1 OK
Client: * PUMP 3 locked
Client: * PUMP 3 free

→ Customer starts fueling

Expand All @@ -361,18 +373,19 @@ Client: * TRANSACTION 3 e2f74ef5-f427-4ae6-bdd3-70a96709992f open 0100 EUR 86.83

Server: S2 CLEAR 3 e2f74ef5-f427-4ae6-bdd3-70a96709992f e2f74ef5-f427-4ae6-bdd3-70a96709992f pace
Client: S2 OK
Client: * PUMP 3 free
Client: * PUMP 3 locked
Comment on lines 374 to +376
Copy link

Copilot AI Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the Pre-Auth full example, after CLEAR the pump status is updated to locked, but Step 6 describes CLEAR as freeing the pump and shows * PUMP 3 free on success (walkthrough/part-3.md:249-274). Please reconcile these two descriptions (e.g., document that Post-Pay returns to free while Pre-Auth returns to locked idle, and adjust the Step 6 guidance accordingly).

Copilot uses AI. Check for mistakes.

---

→ Alternative: Customer walks away without fueling

Server: S1 UNLOCKPUMP 3 EUR 100.00 e2f74ef5-f427-4ae6-bdd3-70a96709992f pace
Client: S1 OK
Client: * PUMP 3 locked
Client: * PUMP 3 free

Client: C2 LOCKEDPUMP 3 e2f74ef5-f427-4ae6-bdd3-70a96709992f aborted
Server: C2 OK
Client: * PUMP 3 locked
```

---
Expand Down
2 changes: 1 addition & 1 deletion walkthrough/part-4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,7 +203,7 @@ Server: * TRANSACTIONINFO 70644955-ef32-4d33-a88b-67b500a7c00d Mileage 176439

Server: S2 UNLOCKPUMP 1 EUR 100.00 70644955-ef32-4d33-a88b-67b500a7c00d pace
Client: S2 OK
Client: * PUMP 1 locked
Client: * PUMP 1 free
```

### Implementation Notes
Expand Down