SubscriptionJS.Signup

The method subscribe is a wrapper of the methods createOrder and paySignupInteractive. For an initial signup subscribe will usually be the method you want to call. If you already created an order via REST API, e.g. for subsequent subscriptions of an existing user, you need to call paySignupInteractive directly.

SubscriptionJS.Signup()

Constructor. Creates an instance of SubscriptionJS.Signup.

preview(cart, customerData, success, error)

Previews what an order for this cart and customerData would look like and what the total amount will be. This is useful if you want to implement a 'dynamic pricing table' where the customer can edit the quantity and will see an updated version of the invoice immediately.

Only the first preview() call will perform an HTTP request immediately, subsequent calls will have a 700ms delay so you don't need to worry about hitting the rate limit too soon.

PropertyTypeDescription
cartcartA description of the products in this order.
customerDatacustomerDataInformation about the customer such as name, address, VAT ID, etc.. This information is required already because the final price might depend on the country of residence, VAT ID, etc.

preview success

{
  "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
  }
}

preview error

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.

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 description of the products in this order.
customercustomerDataInformation about the customer such as name, address, VAT ID, etc.. This information is required already because the final price might depend on the country of residence, VAT ID, etc.
secretPaymentDatasecretPaymentDataThe potentially secret payment information entered by the customer to pay for the order.

subscribe success

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

subscribe error

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
cartcartA description of the products in this order.
customercustomerDataInformation about the customer such as name, address, VAT ID, etc.. This information is required already because the final price might depend on the country of residence, VAT ID, etc.

createOrder success

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

createOrder error

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"
}

createOrder error

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

Initiates interactive payment of the given order.

PropertyTypeDescription
subscriptionJSPaymentsubscriptionJSPaymentAn instance of SubscriptionJS.Payment.
secretPaymentDatasecretPaymentDataThe potentially secret payment information entered by the customer to pay for the order.
orderorderAn order object previously created either via SubscriptionJS.Signup.createOrder() or via a backend call or via the billwerk user interface. Must look like { OrderId : "(id)", GrossTotal : 23.4, Currency : "EUR" }

paySignupInteractive success

Data for 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 order process requires a redirect 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 error

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

[paymentForm EXCLUSIVE]
Behaves like paySignupInteractive, except subscriptionJsPayment is not necessary and paymentForm is submitted instead of secretPaymentData.

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

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

Last updated on 3/20/2020 by Thomas Tauber
← PaymentPortal →