{"openapi":"3.0.3","info":{"title":"2i Mobile Apps Backend API","description":"REST API exposed by the 2i Mobile Apps Backend to allow third-party\nclients to consume fuelling services from petrol stations connected through the\n2i backend platform.\n\nThe fuelling flow is asynchronous: after a fuelling process is created, the\n2iBE notifies the client of every state change by means of HTTP POST callbacks\nagainst a URL agreed during on-boarding. See the `callbacks` section in\n`POST /fueling-processes`.\n\nAuthentication:\n  - `POST /auth/token` uses HTTP Basic Authentication.\n  - The rest of the endpoints expect a JWT Bearer Token returned by `/auth/token`.\n","version":"1.4","contact":{"name":"2i Online","url":"https://app.swaggerhub.com/apis-docs/2ionline/2i-mobile-payment-API/1.0.0"}},"servers":[{"url":"{protocol}://{host}{basePath}","description":"Configurable server","variables":{"protocol":{"enum":["https","http"],"default":"https"},"host":{"default":"ryd.example.com","description":"Host where the RYD backend is deployed."},"basePath":{"default":"/api","description":"Value of the `HOME_PATH` environment variable on the server."}}}],"tags":[{"name":"Auth","description":"Token issuance."},{"name":"Petrol Stations","description":"Information about stations, pumps and products."},{"name":"Fueling Processes","description":"Lifecycle of a fuelling transaction."}],"security":[{"bearerAuth":[]}],"paths":{"/auth/token":{"post":{"tags":["Auth"],"summary":"Issue a new JWT","description":"Returns a JWT to be used as Bearer token in the rest of the endpoints.\nThe request must carry valid credentials in the `Authorization` header\nusing HTTP Basic Authentication.\n","security":[{"basicAuth":[]}],"responses":{"200":{"description":"Token issued correctly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"},"examples":{"default":{"value":{"auth":true,"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","expiresIn":3600}}}}}},"401":{"description":"Invalid credentials."}}}},"/petrol-stations":{"get":{"tags":["Petrol Stations"],"summary":"List petrol stations","description":"Returns the list of petrol stations connected to the 2iBE.\nOptionally filtered by distance (`lat`, `lon`, `radius`) and paginated\nwith `limit` / `offset`.\n","parameters":[{"name":"lat","in":"query","required":false,"schema":{"type":"number","format":"float"},"description":"Latitude of the reference point."},{"name":"lon","in":"query","required":false,"schema":{"type":"number","format":"float"},"description":"Longitude of the reference point."},{"name":"radius","in":"query","required":false,"schema":{"type":"number","format":"float"},"description":"Search radius in meters."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"List of matching stations.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FuelStation"}}}}},"204":{"description":"No stations match the filter."},"400":{"description":"Invalid query parameters."},"401":{"description":"Missing or expired token."}}}},"/petrol-stations/{stationId}":{"get":{"tags":["Petrol Stations"],"summary":"Get a single station","parameters":[{"$ref":"#/components/parameters/StationIdPath"}],"responses":{"200":{"description":"Station returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelStation"}}}},"204":{"description":"Station not found."},"400":{"description":"Invalid `stationId`."},"401":{"description":"Missing or expired token."}}}},"/petrol-stations/{stationId}/pumps":{"get":{"tags":["Petrol Stations"],"summary":"List pumps of a station","description":"Returns the pumps available at a station, with the products each one dispenses.","parameters":[{"$ref":"#/components/parameters/StationIdPath"}],"responses":{"200":{"description":"List of pumps returned.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Pump"}}}}},"400":{"description":"Invalid `stationId`."},"401":{"description":"Missing or expired token."}}}},"/fueling-processes":{"post":{"tags":["Fueling Processes"],"summary":"Create a new fuelling process","description":"Creates a new fuelling process and reserves the requested pump.\nThe lifecycle of the process is communicated asynchronously to the client\nvia the callback declared below.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFuelingProcessRequest"},"examples":{"default":{"value":{"senderFuelingProcessId":"TX-2026-0001","callbackAccessToken":"eyJhbGciOi...","authorizationInfo":{"stan":"123456","batchId":"000123","rrn":"612345678901","authCode":"A1B2C3"},"stationId":"ES-MAD-001","pumpNumber":"3","fuelProductId":"DIESEL","amount":{"currency":"EUR","amount":50.0},"matchingReference":"CARD-REF-ABC"}}}}}},"responses":{"201":{"description":"Process created and pump reserved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFuelingProcessResponse"}}}},"400":{"description":"Validation error. Common causes:\n  - station / pump / product does not exist\n  - the pump does not dispense the requested product\n  - transaction with the same `senderFuelingProcessId` already exists.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or expired token."},"404":{"description":"Station rejected the lock / preset request."}},"callbacks":{"onFuelingProcessEvent":{"{$request.body#/callbackAccessToken}":{"post":{"summary":"State change notification","description":"Notifies the client of a state change of the fuelling process.\nThe 2iBE sends an `Authorization: Bearer <callbackAccessToken>`\nheader reusing the token provided in the originating request body.\nThe client MUST validate this token in every received callback.\n\nDelivery is at-least-once, so the client must be idempotent: use\n`fuelingProcessId` + `state.code` as idempotency key.\n","security":[{"callbackAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackEvent"},"examples":{"created":{"value":{"fuelingProcessId":"1234567","senderFuelingProcessId":"TX-2026-0001","state":{"code":"created","filledQuantity":0}}},"pumpReady":{"value":{"fuelingProcessId":"1234567","senderFuelingProcessId":"TX-2026-0001","state":{"code":"pumpReady"}}},"tanking":{"value":{"fuelingProcessId":"1234567","senderFuelingProcessId":"TX-2026-0001","state":{"code":"tanking","filledQuantity":12.4}}},"processed":{"value":{"fuelingProcessId":"1234567","senderFuelingProcessId":"TX-2026-0001","state":{"code":"processed","receipt":{"product":{"productId":"DIESEL","name":"Diesel A","type":"fuel","price":{"currency":"EUR","amount":1.499},"vatRate":21},"quantity":33.32,"amount":{"currency":"EUR","amount":49.95},"vatRate":21,"vatAmount":{"currency":"EUR","amount":8.67}}}}},"rejected":{"value":{"fuelingProcessId":"1234567","senderFuelingProcessId":"TX-2026-0001","state":{"code":"rejected","rejectionReasonCode":"tankingNotStarted"}}}}}}},"responses":{"200":{"description":"Event acknowledged.","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"boolean"}}}}}}}}}}}}},"/fueling-processes/{fuelingProcessId}":{"get":{"tags":["Fueling Processes"],"summary":"Get fuelling process information","description":"Returns the original information of a fuelling process: identifiers,\nstation, pump, product and authorised amount. Use `/state` to obtain\nthe current status.\n","parameters":[{"$ref":"#/components/parameters/FuelingProcessIdPath"}],"responses":{"200":{"description":"Process information returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelingProcessInfo"}}}},"400":{"description":"Invalid `fuelingProcessId`."},"401":{"description":"Missing or expired token."},"404":{"description":"Process not found."}}}},"/fueling-processes/{fuelingProcessId}/state":{"get":{"tags":["Fueling Processes"],"summary":"Get fuelling process state","description":"Returns the current state of a fuelling process. This endpoint can be\npolled as an alternative or complement to the callback flow.\n","parameters":[{"$ref":"#/components/parameters/FuelingProcessIdPath"}],"responses":{"200":{"description":"State returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuelingProcessState"}}}},"204":{"description":"Process not found."},"400":{"description":"Invalid `fuelingProcessId`."},"401":{"description":"Missing or expired token."}}}},"/fueling-processes/{fuelingProcessId}/cancel":{"post":{"tags":["Fueling Processes"],"summary":"Cancel a fuelling process","description":"Cancels a fuelling process. Only allowed if tanking has not effectively\nstarted. If the process is already in `COMPLETE` state, the call is\nacknowledged but no cancellation is performed (idempotent).\n","parameters":[{"$ref":"#/components/parameters/FuelingProcessIdPath"}],"responses":{"204":{"description":"Process cancelled or already completed."},"400":{"description":"Station refused to release the pump or other error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or expired token."},"409":{"description":"Process does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic Authentication used only by `POST /auth/token`."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT issued by `POST /auth/token`."},"callbackAuth":{"type":"http","scheme":"bearer","description":"Bearer token sent by 2iBE when invoking the client callback URL.\nThe token value is the `callbackAccessToken` provided by the client\nin the body of `POST /fueling-processes`.\n"}},"parameters":{"StationIdPath":{"name":"stationId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of a petrol station."},"FuelingProcessIdPath":{"name":"fuelingProcessId","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the fuelling process returned by `POST /fueling-processes`."}},"schemas":{"TokenResponse":{"type":"object","properties":{"auth":{"type":"boolean"},"token":{"type":"string","description":"JWT, used as Bearer token."},"expiresIn":{"type":"integer","description":"Lifetime of the token in seconds."}},"required":["auth","token","expiresIn"]},"Money":{"type":"object","properties":{"currency":{"type":"string","example":"EUR"},"amount":{"type":"number","example":50.0}},"required":["currency","amount"]},"Product":{"type":"object","properties":{"productId":{"type":"string"},"type":{"type":"string","example":"fuel"},"name":{"type":"string"},"price":{"$ref":"#/components/schemas/Money"},"vatRate":{"type":"number"}}},"FuelStation":{"type":"object","properties":{"stationId":{"type":"string"},"dateTime":{"type":"string","format":"date-time"},"name":{"type":"string"},"fullAddress":{"type":"string"},"location":{"type":"object","properties":{"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"}}},"fuelPumpsQty":{"type":"integer"},"brand":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"}}},"fuelProducts":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"available":{"type":"boolean"}}},"Pump":{"type":"object","properties":{"number":{"type":"string"},"state":{"type":"string","example":"free"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}},"AuthorizationInfo":{"type":"object","properties":{"stan":{"type":"string"},"batchId":{"type":"string"},"rrn":{"type":"string"},"authCode":{"type":"string"}},"required":["stan","batchId","rrn","authCode"]},"CreateFuelingProcessRequest":{"type":"object","required":["senderFuelingProcessId","callbackAccessToken","authorizationInfo","stationId","pumpNumber","fuelProductId","amount","matchingReference"],"properties":{"senderFuelingProcessId":{"type":"string","description":"Process identifier on the client side."},"callbackAccessToken":{"type":"string","description":"Bearer token that 2iBE will use when invoking the client's callback URL."},"authorizationInfo":{"$ref":"#/components/schemas/AuthorizationInfo"},"stationId":{"type":"string"},"pumpNumber":{"type":"string"},"fuelProductId":{"type":"string"},"amount":{"$ref":"#/components/schemas/Money"},"matchingReference":{"type":"string","description":"Reference of the payment card / wallet of the user."}}},"CreateFuelingProcessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"fuelingProcessId":{"type":"integer","example":1234567}}},"FuelingProcessInfo":{"type":"object","properties":{"fuelingProcessId":{"type":"string"},"senderFuelingProcessId":{"type":"string"},"authorizationCode":{"type":"string"},"stationId":{"type":"string"},"pumpNumber":{"type":"string"},"fuelProductId":{"type":"string"},"amount":{"$ref":"#/components/schemas/Money"}}},"Receipt":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/Product"},"quantity":{"type":"number"},"amount":{"$ref":"#/components/schemas/Money"},"vatRate":{"type":"number"},"vatAmount":{"$ref":"#/components/schemas/Money"}}},"FuelingProcessState":{"type":"object","properties":{"code":{"type":"string","enum":["created","pumpReady","in progress","processed","success","rejected"]},"receipt":{"$ref":"#/components/schemas/Receipt"},"filledQuantity":{"type":"number","description":"Only present when code = in progress."},"rejectionReasonCode":{"type":"string","enum":["systemError","pumpInUse","tankingNotStarted","tankingCancelled","tankingTimedOut"],"description":"Only present when code = rejected."}}},"CallbackEvent":{"type":"object","required":["fuelingProcessId","senderFuelingProcessId","state"],"properties":{"fuelingProcessId":{"type":"string"},"senderFuelingProcessId":{"type":"string"},"state":{"type":"object","required":["code"],"properties":{"code":{"type":"string","enum":["created","pumpReady","tanking","processed","rejected"]},"filledQuantity":{"type":"number"},"rejectionReasonCode":{"type":"string","enum":["systemError","pumpInUse","tankingNotStarted","tankingCancelled","tankingTimedOut"]},"receipt":{"$ref":"#/components/schemas/Receipt"}}}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"errorMessage":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}