Dokumentation für Lieferanten (englisch)
      Zurück zur Startseite
      1. HB Marketplace GmbH
      2. Dokumentation für Lieferanten (englisch)

      Supplier Checkout

      Preamble
      Hosts
      Start Checkout
      Status page / success target

      Preamble

      • Suppliers must be registered in the Core (source: TBD; PIM?)

      • Suppliers receive a shared secret exclusively for the checkout usage (see details below)

      • Suppliers receive a unique ID (assigned by the source system), which is required for checkout

      • Suppliers can store up to 10 success URLs that can be used for the checkout.

      • after payment, the customer is redirected to the success URL defined for the checkout (with additional parameters, see below for details)

      • Suppliers can submit a return URL into the checkout. The user will then be able to see a RETURN-Button to leave the checkout. The User will be directed to the given return URL.

      Hosts

      • Production: https://checkout-api.hb-marketplace.com

      • Staging: https://staging-checkout-api.hb-marketplace.com

      Start Checkout

      HTTP POST /api/checkout

      { "vendor_id": "foo_partner",
      "success_url": "<https://order.partner-domain.com/status?source=partner_shop>",
      "return_url": "<https://return-url.de>",
      "items": [
      {
      // Used to group subscription products with their associated
      // addons and one-time charges/purchases, e. g. setup fees
      "group_id": "sub1",
      "sku": "subscription_product123",
      "quantity": 5
      },
      {
      "group_id": "sub1",
      "sku": "addon_product123",
      "quantity": 5
      },
      {
      // One-time purchases independent of subscriptions
      // may be passed without a group
      "sku": "mug-blue",
      "quantity": 1
      }
      ],
      "discount_codes": [
      "10_PERCENT_OFF"
      ]
      }

      • Response (HTTP 200)

         
        {
        "id": "ed16893b-c6d4-441b-a5cb-03b794f9edeb",
        "token": "0frjjUBpqiun44sfGRag2oC0gwU4MdiaLRoD46s2iFUiKqDashYbGW9PzPRjvMoI",
        "url": "<https://checkout.hb-platform.com/checkout/ed16893b-c6d4-441b-a5cb-03b794f9edeb?token=0frjjUBpqiun44sfGRag2oC0gwU4MdiaLRoD46s2iFUiKqDashYbGW9PzPRjvMoI&ts=1663590273>",
        "return_url": "<https://return-url.de>"
        }
      • Response in case of Error
       HTTP 422: Unprocessable Entity
       

      The success URL is optional, even if a vendor ID is passed. However, without a vendor ID, a success URL is not permitted.

      The success URL must be whitelisted for the supplier. However, only the base URL with the path (here: https://order.partner-domain.com/status) is checked, so query parameters can be passed dynamically for the redirect, e.g. to loop through UTM parameters, states or similar.

      The success URL cannot be changed after the checkout has started.

      Status Page / Success Target

      After going through the checkout, the customer is redirected to the defined success URL. In the process, more query parameters are added to validate the order and the source:

      • success URL from checkout: https://order.partner-domain.com/status?source=partner_shop

      • final success target: https://order.partner-domain.com/status?source=partner_shop&order_id=foo_id&token=a4cafc8f55b66c4f8d96b21c602f36f4890582c42e7565cebc7d6f624a36a64c

        • the order_id is the ID of the generated checkout

        • the token is a HMAC hash (SHA256) of the checkout ID with the vendor's shared secret as key