API Reference
Billwerk+ WebsiteHelp Center ENHelp Center DE

SubscriptionJS.Signup

Constructor

Creates an instance of SubscriptionJS.Signup.

preview(cart, customerData, success, error)

The preview function in SubscriptionJS is designed to provide a real-time estimation of what an order will cost based on the current cart and customer data. It's beneficial for creating dynamic pricing tables that allow customers to adjust quantities and see the updated invoice instantly.

Rate-Limited preview Calls

When using preview() to estimate orders in SubscriptionJS, it's important to consider the rate-limiting measures in place:

  • The first preview() call on any page will be executed immediately without delay.
  • Subsequent preview() calls will have an enforced delay of 700ms between requests.

This delay mechanism prevents hitting the API rate limit too quickly, ensuring a smooth user experience while interacting with dynamic pricing elements.

preview Property Structure

PropertyTypeDescription
cartcartA description of the products in this order.
customerDatacustomerDataInformation about the customer for accurate pricing.

Result objects

Error result

Successful result

{
  "Order": {
    "MeteredComponents": [
      {
        "ComponentType": "Metered",
        "PreventModification": false,
        "Name": "metered",
        "PricePerUnit": 22,
        "VatPercentage": 0,
        "LineItems": [],
        "TotalNet": 0,
        "TotalVat": 0,
        "ExternalId": "",
        "IsQuantityBased": false,
        "ComponentId": "5c920e6950abbb0554620a2d",
        "Quantity": 0
      }
    ],
    "CouponCode": "STAR",
    "Quantity": 1,
    "PlanVariantId": "5c90fc8450abb71aa0bf039b",
    "AllowWithoutPaymentData": false,
    "ComponentSubscriptions": [],
    "Coupon": {
      "CouponCode": "STAR",
      "ErrorMessage": "CouponCode is invalid",
      "ErrorCode": "InvalidCouponCode"
    },
    "RecurringFee": {
      "ComponentType": "QuantityBased",
      "PreventModification": true,
      "FeePeriod": {
        "Unit": "Month",
        "Quantity": 1
      },
      "Name": "Mein Produkt - Basic",
      "PricePerUnit": 25,
      "VatPercentage": 19,
      "LineItems": [
        {
          "Description": "Mein Produkt - Basic",
          "Quantity": 1,
          "PricePerUnit": 25,
          "VatPercentage": 19,
          "PeriodStart": "2019-04-03T11:56:37.8490000Z",
          "PeriodEnd": "2019-05-03T11:56:37.8490000Z",
          "PeriodMultiplier": 1,
          "ScaleAmount": 1,
          "ProductId": "5c90fc8450abb71aa0bf039b",
          "TotalNet": 25,
          "TotalVat": 4.75,
          "TotalGross": 29.75,
          "ProductDescription": "enthält alle basic-Funktionen\r\nmonatliche Laufzeit und monatliche Zahlung"
        }
      ],
      "TotalNet": 25,
      "TotalVat": 4.75,
      "Description": "enthält alle basic-Funktionen",
      "IsQuantityBased": false,
      "VariantName": "monatliche Laufzeit",
      "VariantDescription": "monatliche Laufzeit und monatliche Zahlung",
      "ComponentId": "5c90fc8450abb71aa0bf039b",
      "Quantity": 1
    },
    "SetupFee": {
      "ComponentType": "QuantityBased",
      "PreventModification": true,
      "Name": "Einrichtungsgebühr",
      "PricePerUnit": 50,
      "VatPercentage": 19,
      "LineItems": [
        {
          "Description": "Einrichtungsgebühr",
          "Quantity": 1,
          "PricePerUnit": 50,
          "VatPercentage": 19,
          "PeriodStart": "2019-04-03T11:56:37.8490000Z",
          "PeriodEnd": "2019-04-03T11:56:37.8490000Z",
          "ProductId": "5c90fc8450abb71aa0bf039b",
          "TotalNet": 50,
          "TotalVat": 9.5,
          "TotalGross": 59.5
        }
      ],
      "TotalNet": 50,
      "TotalVat": 9.5,
      "IsQuantityBased": false,
      "Quantity": 1
    },
    "Currency": "EUR",
    "Total": 75,
    "TotalVat": 14.25,
    "TotalGross": 89.25,
    "NextTotalGross": 29.75,
    "NextTotalGrossDate": "2019-05-03T11:56:37.8490000Z",
    "IsTrial": false,
    "TrialEndPolicy": "NoTrial",
    "Status": "InProgress",
    "OrderType": "Signup",
    "TriggerInterimBilling": false,
    "PreviewAfterTrial": false
  }
}

subscribe(subscriptionJSPayment, cart, customer, secretPaymentData, success, error)

Creates an order and initiates the payment in a single step. This is a mere wrapper for createOrder and paySignupInteractive.

📘

Stateless operation

When paying with a white-label PSP calling this method is a one-step stateless operation. Calling it several times will process several orders, e.g. the customer double clicks the order button. Prevent this in your signup implementation.

PropertyTypeDescription
subscriptionJSPaymentSubscriptionJS.PaymentAn instance of SubscriptionJS.Payment.
cartcartA cart object containing details of the products included in this order.
customercustomerDataCustomer information object including details such as name, address, and VAT ID. The price may vary based on the customer's country of residence and VAT status.
secretPaymentDatasecretPaymentDataPayment information provided by the customer, which may be sensitive, is used to process the payment.
{
  "OrderId": "5ca4af02bb573feacc9f7b55",
  "ContractId": "5ca4af0250abb730802f9e3e",
  "CustomerId": "5ca4af0250abb730802f9e3d",
  "GrossTotal": 89.25,
  "Currency": "EUR",
  "OrderStatus": "InProgress"
}

createOrder(cart, customerData, success, error)

Creates an order object on the server. The order object can later be paid for. This is useful to show the definite amount to the user before proceeding to checkout or if you need to validate orders manually.

PropertyTypeDescription
cartcartAn object detailing the products included in the order.
customercustomerDataAn object containing customer information such as name, address, and VAT ID, necessary for determining the final order price.

createOrder success:

{
  "OrderId": "5ca4af02bb573feacc9f7b55",
  "ContractId": "5ca4af0250abb730802f9e3e",
  "CustomerId": "5ca4af0250abb730802f9e3d",
  "GrossTotal": 89.25,
  "Currency": "EUR",
  "OrderStatus": "InProgress"
}

createOrder(selfServiceOrder, success, error)

Creates an order object on the server. The order object can later be paid for. This is useful to show the definite amount to the user before proceeding to checkout or if you need to validate orders manually.

PropertyTypeDescription
selfServiceOrderselfServiceOrderA wrapper for customerData, cart and optional Contract-/OrderCustomFields.

createOrder success

{
  "OrderId": "5ca4af02bb573feacc9f7b55",
  "ContractId": "5ca4af0250abb730802f9e3e",
  "CustomerId": "5ca4af0250abb730802f9e3d",
  "GrossTotal": 89.25,
  "Currency": "EUR",
  "OrderStatus": "InProgress"
}

paySignupInteractive(subscriptionJSPayment, secretPaymentData, order, success, error)

Initiates interactive payment of the given order.

PropertyTypeDescription
subscriptionJSPaymentSubscriptionJSPaymentAn instance of SubscriptionJSPayment which is used to initiate a payment transaction.
secretPaymentDataSecretPaymentDataIt contains sensitive payment information that the customer inputs for order payment.
orderOrderAn object representing the order to be paid. It should follow the format: { OrderId: "(id)", GrossTotal: 23.4, Currency: "EUR" }. This order object can be obtained through SubscriptionJS.Signup.createOrder(), backend API calls, or via the Billwerk+ Transform user interface.

Notes:

  • The order object must contain the OrderId to reference the correct order along with GrossTotal and Currency to specify the payment amount and currency.
  • It is important to handlesecretPaymentData with the utmost security since it contains confidential payment information.

paySignupInteractive success

Data for a successful order. If the order is successful, ContractId and CustomerId are returned.

{  
  "OrderId": "5ca4af02bb573feacc9f7b55",  
  "ContractId": "5ca4af0250abb730802f9e3e",  
  "CustomerId": "5ca4af0250abb730802f9e3d",  
  "GrossTotal": 89.25,  
  "Currency": "EUR",  
  "OrderStatus": "PaymentPending"  
}

If the order process requires redirecting to a payment provider page, the URL is passed to the success callback.

{  
  "OrderId": "5ca4af02bb573feacc9f7b55",  
  "Url": "<https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=PA-5XN84696Y7987241A">,  
  "GrossTotal": 89.25,  
  "Currency": "EUR",  
  "OrderStatus": "PaymentPending"  
}

paySignupInteractive(null, paymentForm, order, success, error)

[paymentForm EXCLUSIVE]
It behaves like paySignupInteractive, except subscriptionJsPayment is unnecessary and paymentForm is submitted instead of secretPaymentData.

paySignupInteractive(null, processedPaymentData, order, success, error)

[paymentForm EXCLUSIVE]
Behaves like paySignupInteractive, except subscriptionJsPayment is unnecessary and processedPaymentData from processPaymentData(...) is submitted instead of secretPaymentData.