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

      Lieferanten-Checkout

      Präambel
      Hosts
      Checkout starten
      Status-Page / Success Ziel

      Präambel

      • Lieferanten müssen im Core registriert sein (Quelle: TBD; PIM?)

      • Lieferanten erhalten ein Shared Secret ausschließlich für die Nutzung des Checkouts (Details s. u.)

      • Lieferanten erhalten eine eindeutige ID (wird vom Quellsystem vergeben), die für den Checkout benötigt wird

      • Lieferanten können bis zu 10 Success-URLs hinterlegen, die für den Checkout genutzt werden können

      • nach der Bezahlung wird der Kunde auf die für den Checkout definierte Success-URL (mit zusätzlichen Parametern, Details s. u.) umgeleitet

      • übergibt der Lieferant eine Return URL bei der Initialisierung des Checkouts, kann der Checkout über einen “Zurück”-Button verlassen werden. Der User wird dann auf die übergebene Return-URL zurückgeleitet.

      Hosts

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

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

      Checkout starten

      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 im Error-Fall

         
        HTTP 422: Unprocessable Entity

        • enthält eine Liste der Fehler

      💡 Die Success-URL ist optional, auch wenn eine Vendor-ID übergeben wird. Ohne Vendor-ID ist eine Success-URL allerdings nicht zulässig.

      💡 Die Success-URL muss für den Lieferanten gewhitelistet sein. Geprüft wird dabei jedoch nur die Base-URL mit Path (hier: https://order.partner-domain.com/status), es können somit dynamisch Query-Parameter für den Redirect übergeben werden, um bspw. UTM-Parameter, State o. Ä. durchzuschleifen.

      ⚠️ Die Success-URL ist nach dem Start des Checkouts nicht mehr änderbar.

      Status-Page / Success-Ziel

      Nach Durchlaufen des Checkouts wird der Kunde auf die definierte Success-URL umgeleitet. Dabei werden weitere Query-Parameter zur Validierung der Bestellung & der Quelle hinzugefügt:

      • Success-URL aus Checkout: https://order.partner-domain.com/status?source=partner_shop

      • Finales Success-Ziel: https://order.partner-domain.com/status?source=partner_shop&order_id=foo_id&token=a4cafc8f55b66c4f8d96b21c602f36f4890582c42e7565cebc7d6f624a36a64c

        • die order_id ist die ID des generierten Checkouts

        • der tokenist ein HMAC-Hash (SHA256) der Checkout-ID mit dem Shared Secret des Lieferanten als Key