Pre Auth or Post Pay

POST /gas-stations/{gasStationId}/transactions
OAuth2 Oidc

This call supports two different flows. The Pre Auth flow and the Post Pay flow. This call will notify the user via email with a payment receipt if transaction is finished successfully. Only use after approaching, otherwise returns 403 Forbidden.

Pre Auth

This flow is used if a pump is having the status locked. A locked pump requires a Pre Auth to unlock. Only after this Pre Auth the pump and can be used by the user

  • carFuelType may be passed to only unlock a certain nozzle of the pump. Not all pumps support this feature, and some require it. It is advised to always pass the desired fuel type.

Post Pay

You can optionally provide:

  • priceIncludingVAT and currency in the request body to check if the price the user has seen is still correct. If the values don't match, the status 409 Conflict is returned.
  • carFuelType may be provided but has no effect.
  • The token will still be available for use in case the payment fails. It may need to be deleted by the caller

Unattended Payment

As an additional feature, the caller can - in case of Post Pay - opt for unattended payment. In summary, this means that when given a token with a certain authorized amount, the service will watch over the status of the fueling process and finish the transaction in the background, with no further user interaction required. This will only work if the amount fueled does not exceed the amount authorized in the token. Otherwise, an error response will be sent to the callback URL

  • unattendedPayment in the request body designates whether this should be done or not. Note that this is only possible if a valid token has been provided
  • callbackURL is an optional URL that will be called with what would usually be the response to the final ProcessPayment call after the process has finished
  • The token will still be available for use in case the payment fails. It may need to be deleted by the caller
  • This process is only available if the pump is in status free. Otherwise, 422 is returned.
  • The backend will wait for a grace period of 20 seconds after this call was sent before starting the process

Path parameters

application/vnd.api+json

Body Required

  • data object
    Hide data attributes Show data attributes object
    • type string Required

      Value is transaction.

    • id string(uuid)

      Transaction ID

    • attributes object Required
      Hide attributes attributes Show attributes attributes object
      • paymentToken string Required

        'Value' field of the payment token (not the payment token ID)

      • unattendedPayment boolean

        Set to 'true' if you want the payment to be cleared automatically in the background after fueling

      • callbackURL string

        A callback URL to report the status of the transaction to, once completed. Only relevant if unattendedPayment is true

      • pumpId string(uuid) Required

        Pump ID

      • vin string

        Vehicle identification number

      • driverVehicleID string

        Driver/vehicle identification

      • mileage integer

        Current mileage in meters

        Minimum value is 0, maximum value is 9999999999.

      • numberPlate string

        Number plate of the Vehicle

      • additionalData string

        additional data for omv

      • priceIncludingVAT number(decimal)
      • currency string

        Currency as specified in ISO-4217.

        Format should match the following pattern: ^[A-Z]{3}$.

      • carFuelType string

        Fuel type for cars, based on the EU fuel marking

        Values are ron98, ron98e5, ron95e10, diesel, e85, ron91, ron95e5, ron100, dieselGtl, dieselB0, dieselB7, dieselB15, dieselB20, dieselBMix, dieselPremium, dieselHvo, dieselRed, dieselSynthetic, lpg, cng, lng, h2, truckDiesel, adBlue, truckAdBlue, truckDieselPremium, truckLpg, or heatingOil.

      • metadata array[object]
        Hide metadata attributes Show metadata attributes object

Responses

  • 201 application/vnd.api+json

    Post Pay: Payment successful, or unattended payment enqueued

    Hide response attribute Show response attribute object
  • 202

    Pre Auth: Pump unlocked

    Hide headers attribute Show headers attribute
    • Location string(url)

      Location of the future payment transaction details

  • 400 application/vnd.api+json

    Bad request

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 401 application/vnd.api+json

    OAuth token missing or invalid or a linked identity is missing.

    Linked identity missing is a special case where you need to make sure that the user has additionally logged in / authorized with a third-party.

    This is not relevant for most use-cases.

    The specific error code that identifies a missing linked identity is missing-linked-identity

    Example:

      {
      "errors": [
          {
              "id": "cbgmhslmp1o9or9kh1p0",
              "title": "Missing linked identity for authorized access",
              "detail": "Linked identity is needed to access this resource, please check why the user does not have a linked identity",
              "status": "401",
              "code": "missing-linked-identity"
          }
      ]
  }
    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 403 application/vnd.api+json

    Forbidden

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 404 application/vnd.api+json

    Resource not found

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 406 application/vnd.api+json

    The specified accept header is invalid

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 409 application/vnd.api+json

    The provided priceIncludingVAT does not match the actual price

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 412 application/vnd.api+json

    Precondition failed

      {
      "errors": [
          {
              "id": "buck3h44qtf5j268141g",
              "title": "Pump already unlocked/in-use on site by someone else",
              "detail": "",
              "status": "412",
              "code": "FUELING_PUMP_BUSY_ON_SITE"
          }
      ]
  }
    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 415 application/vnd.api+json

    The specified content type header is invalid

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 422 application/vnd.api+json

    The request was well-formed but was unable to be followed due to semantic errors.

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 500 application/vnd.api+json

    Internal server error

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
  • 502 application/vnd.api+json

    Error occurred while communicating with PACE services

    Hide response attribute Show response attribute object
    • errors array[object]
      Hide errors attributes Show errors attributes object
      • id string

        A unique identifier for this particular occurrence of the problem.

      • links object
        Hide links attribute Show links attribute object
        • about string

          A link that leads to further details about this particular occurrence of the problem.

      • status string

        the HTTP status code applicable to this problem, expressed as a string value.

      • code string

        an application-specific error code, expressed as a string value.

      • title string

        A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

      • detail string

        a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

      • source object

        An object containing references to the source of the error.

        Hide source attributes Show source attributes object
        • pointer string

          A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].

        • parameter string

          A string indicating which URI query parameter caused the error.

      • meta object

        a meta object containing non-standard meta-information about the error.

        Hide meta attribute Show meta attribute object
POST /gas-stations/{gasStationId}/transactions 
curl \
 -X POST https://api.pace.cloud/fueling/2024-2/gas-stations/a6ec9bd7-cf0b-416c-b24f-9ce65ab3dfe1/transactions \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/vnd.api+json"
Request examples 
{
  "data": {
    "type": "transaction",
    "id": "c3f037ea-492e-4033-9b4b-4efc7beca16c",
    "attributes": {
      "paymentToken": "12c52345c1x34",
      "unattendedPayment": false,
      "callbackURL": "https://my.fueling/pace/transaction-callback",
      "pumpId": "460ffaad-a3c1-4199-b69e-63949ccda82f",
      "vin": "1B3EL46R36N102271",
      "driverVehicleID": "1B2598746",
      "mileage": 66435000,
      "numberPlate": "KA AM92",
      "additionalData": "987654321098",
      "priceIncludingVAT": 69.34,
      "currency": "EUR",
      "carFuelType": "ron95e10",
      "metadata": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    }
  }
}
Response examples (201) 
{
  "data": {
    "type": "transaction",
    "id": "c3f037ea-492e-4033-9b4b-4efc7beca16c",
    "attributes": {
      "paymentToken": "12c52345c1x34",
      "gasStationId": "a6ec9bd7-cf0b-416c-b24f-9ce65ab3dfe1",
      "pumpId": "460ffaad-a3c1-4199-b69e-63949ccda82f",
      "vin": "1B3EL46R36N102271",
      "driverVehicleID": "1B2598746",
      "mileage": 66435000,
      "VAT": {
        "amount": 11.07,
        "rate": 0.19
      },
      "priceWithoutVAT": 58.27,
      "priceIncludingVAT": 69.34,
      "discountAmount": 1.27,
      "currency": "EUR"
    }
  }
}
Response examples (400) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (401) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (403) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (404) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (406) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (409) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (412) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (415) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (422) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (500) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}
Response examples (502) 
{
  "errors": [
    {
      "id": "string",
      "links": {
        "about": "string"
      },
      "status": "string",
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}