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 firstpreview() call on any page will be executed immediately without delay.
Subsequentpreview() 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

Property	Type	Description
cart	cart	A description of the products in this order.
customerData	customerData	Information 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.

Property	Type	Description
subscriptionJSPayment	SubscriptionJS.Payment	An instance of SubscriptionJS.Payment.
cart	cart	A cart object containing details of the products included in this order.
customer	customerData	Customer 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.
secretPaymentData	secretPaymentData	Payment 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.

Property	Type	Description
cart	cart	An object detailing the products included in the order.
customer	customerData	An 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.

Property	Type	Description
selfServiceOrder	selfServiceOrder	A 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.

Property	Type	Description
subscriptionJSPayment	SubscriptionJSPayment	An instance of SubscriptionJSPayment which is used to initiate a payment transaction.
secretPaymentData	SecretPaymentData	It contains sensitive payment information that the customer inputs for order payment.
order	Order	An 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.