Process payment Beta

POST /transactions

Process payment and notify user (payment receipt) if transaction is finished successfully. The priceIncludingVAT and currency attributes are required, unless when announcing a transaction in which case those values are copied from the token and any given values are ignored.

Only use after approaching (fueling api), otherwise returns 403 Forbidden.

Query parameters

  • announce boolean

    Announcing the transaction without actually capturing the payment. An announced transaction can later be processed only if providing the same paymentToken, purposePRN, and providerPRN. By announcing the transaction the token is locked to be used only with this transaction. The priceIncludingVAT and currency will be taken from the token, and upon capturing the transaction, must be equal or lower than what was announced.

application/vnd.api+json

Body Required

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

      Value is transaction.

    • id string(uuid)

      ID of the new transaction.

    • attributes object Required
      Hide attributes attributes Show attributes attributes object
      • userUuid string(uuid)

        User uuid in case we need different user to update transaction

      • paymentToken string Required

        Payment token value

      • priceIncludingVAT number(decimal)
      • priceExcludingVAT number(decimal)
      • currency string

        Currency as specified in ISO-4217.

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

      • VAT object
        Hide VAT attributes Show VAT attributes object
        • amount number(decimal)
        • rate number(decimal)

          Important: Vat rates have to be between 0.00 and 1.00 and not have a decimal precision beyoned 2, i.e., no rate of 0.119999999

      • purposePRN string Required

        PACE resource name - referring to the transaction purpose

      • PACE resource name - referring to the transaction issuer

      • providerPRN string Required

        PACE resource name - referring to the transaction purpose with provider details

      • PACE resource name - referring to the transaction's merchant

      • vin string

        Vehicle identification number

      • Driver/vehicle identification

      • fuelAmount number(decimal)

        Fuel amount

      • Product name

      • fuel object
        Hide fuel attributes Show fuel attributes object
        • pumpNumber integer

          Number of the pump used for fueling, i.e., the actual number that is being displayed to the customer

        • unit string

          Fuel measurement unit. Eg: liter, us-gallon, uk-gallon, kilogram

        • pricePerUnit number(decimal)

          Price per unit (with three decimal places)

        • amount number(decimal)

          Fuel amount in provided unit

        • Product Name of the current fuel.productName

        • type string

          Fuel type for cars, based on the EU fuel marking

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

      • mileage integer

        Current mileage in meters

      • Number plate of the car

      • The given productFlow (e.g. preAuth, postPay)

      • unattended boolean

        Set to true if the payment is for an unattended process

      • metadata array[object]
        Hide metadata attributes Show metadata attributes object
      • additional data for omv

      • receiptInformation array[string]

        Additional information that will be rendered on the receipt

Responses

  • 201 application/vnd.api+json

    Created

    Hide response attribute Show response attribute object
  • 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 403 application/vnd.api+json

    The request was well-formed but was unable to be followed due to semantic errors. The following codes may be seen:

    • provider:payment-method-rejected: The method was rejected by the payment provider
    • provider:authorization-denied: The transaction was rejected by the payment provider
    • rule:product-denied: Product restrictions forbid transaction, e.g., forbidden fuel type - token authorized only for Diesel but attempted to fuel Super.
    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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 409 application/vnd.api+json

    Resource conflicts

    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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 410 application/vnd.api+json

    Resource is gone

    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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

  • 502 application/vnd.api+json

    Error occurred while communicating with upstream 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.

      • 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].

        • A string indicating which URI query parameter caused the error.

      • meta object

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

POST /transactions
curl \
 -X POST https://api.pace.cloud/pay/2024-4/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": {
      "userUuid": "b4d037ea-492e-4033-9b4b-4efc7beca16c",
      "paymentToken": "12c52345c1x34",
      "priceIncludingVAT": 69.34,
      "priceExcludingVAT": 58.27,
      "currency": "EUR",
      "VAT": {
        "amount": 11.07,
        "rate": 0.19
      },
      "purposePRN": "prn:poi:gas-stations:124e522d-65ef-4386-b7e0-00d2eceeadc6:pumps:f86c1f11-687e-4a85-b16f-3f82a16f3243",
      "issuerPRN": "prn:poi:apps:c30bce97-b732-4390-af38-1ac6b017aa4c",
      "providerPRN": "prn:provider-name:sites:7652346752:pumps:6",
      "merchantPRN": "prn:merchant:merchants:b8c60e3a-3771-4c48-8666-3cbbb42ffdc2",
      "vin": "1B3EL46R36N102271",
      "driverVehicleID": "1B2598746",
      "fuelAmount": 55.12,
      "fuelProductName": "ron98",
      "fuel": {
        "pumpNumber": 1,
        "unit": "liter",
        "pricePerUnit": 1.112,
        "amount": 55.12,
        "productName": "Super Plus",
        "type": "ron98"
      },
      "mileage": 66435000,
      "numberPlate": "KA AM1234",
      "productFlow": "preAuth",
      "unattended": false,
      "metadata": [
        {
          "key": "string",
          "value": "string"
        }
      ],
      "additionalData": "987654321098",
      "receiptInformation": [
        "Email: test@example.com",
        "Firmenanschrift: Meine Adresse 1"
      ]
    }
  }
}
Response examples (201)
{
  "data": {
    "type": "transaction",
    "id": "c3f037ea-492e-4033-9b4b-4efc7beca16c",
    "links": {
      "receipt": {
        "href": "https://api.pace.cloud/pay/receipts/b58b6898-ca63-4417-b671-abe86fb853f0.png",
        "meta": {
          "mimeType": "image/png"
        }
      },
      "receiptPDF": {
        "href": "https://api.pace.cloud/pay/receipts/b58b6898-ca63-4417-b671-abe86fb853f0.pdf",
        "meta": {
          "mimeType": "application/pdf"
        }
      }
    },
    "attributes": {
      "createdAtLocaltime": "2017-07-21T17:32:28Z",
      "createdAt": "2017-07-21T17:32:28Z",
      "updatedAt": "2017-07-21T19:32:28Z",
      "paymentMethodKind": "paydirekt",
      "paymentMethodId": "d7101f72-a672-453c-9d36-d5809ef0ded6",
      "authorizePaymentTokenId": "string",
      "paymentToken": "12c52345c1x34",
      "paymentTokenRequestID": "string",
      "paymentTransactionRequestID": "string",
      "purposePRN": "prn:poi:gas-stations:124e522d-65ef-4386-b7e0-00d2eceeadc6:pumps:f86c1f11-687e-4a85-b16f-3f82a16f3243",
      "providerPRN": "prn:provider-name:sites:7652346752:pumps:6",
      "issuerPRN": "prn:poi:apps:c30bce97-b732-4390-af38-1ac6b017aa4c",
      "vin": "1B3EL46R36N102271",
      "driverVehicleID": "1B2598746",
      "mileage": 66435000,
      "numberPlate": "KA AM1234",
      "additionalData": "987654321098",
      "productFlow": "preAuth",
      "priceIncludingVATBeforeDiscount": 69.34,
      "priceIncludingVAT": 68.17,
      "priceWithoutVAT": 58.27,
      "discountAmount": 1.27,
      "fuel": {
        "pumpNumber": 1,
        "unit": "liter",
        "pricePerUnit": 1.112,
        "amount": 55.12,
        "productName": "Super Plus",
        "type": "ron98"
      },
      "currency": "EUR",
      "VAT": {
        "amount": 11.07,
        "rate": 0.19
      },
      "references": [
        "prn:acquirer:transactions:jgrwsntrjt:types:settlement",
        "prn:acquirer:methods:creditcard"
      ],
      "location": {
        "latitude": 49.013,
        "longitude": 8.425,
        "brand": "Total",
        "stationName": "German Petrol",
        "brandId": "hoyer",
        "address": {
          "street": "Haid-und-Neu-Str.",
          "houseNo": "18",
          "postalCode": "76131",
          "city": "Karlsruhe",
          "countryCode": "DE"
        }
      },
      "error": "string",
      "receiptInformation": [
        "Email: test@example.com",
        "Firmenanschrift: Meine Adresse 1"
      ]
    },
    "relationships": {
      "discountTokens": {
        "data": [
          {
            "type": "discount",
            "id": "c3f037ea-492e-4033-9b4b-4efc7beca16c"
          }
        ]
      }
    }
  }
}
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 (410)
{
  "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": {}
    }
  ]
}