Methods

SubscriptionJS.Payment

SubscriptionJS.Payment(paymentConfig, ready, error) Constructor. Creates an instance of SubscriptionJS.Payment, loads the configured payment methods for your billwerk account from our server, loads required PSP-specific libraries and initializes them. Because of the external calls required, this can take a while and should only be performed once on a page.

The operation can't complete before the DOMContentLoaded event is fired, but you can call this method before the DOM is ready to parallelize requests.
paymentConfig Type: paymentConfig Your paymentConfig. This basically contains your public SubscriptionJS API key and optional redirect URLs for PSPs that require redirection, as well as two js callbacks that can be used to customize the appearance of the 3ds checks for paymill. In the paymill documentation, these are called tdsInit and tdsCleanup.
getAvailablePaymentMethods() Retrieves the payment methods that are configured and activated in your account.
{
  "InvoicePayment": {
    "DefaultPreauthAmount": {
      "BlackLabel": 1
    }
  },
  "PayOne": {
    "CreditCard": true,
    "DirectDebit": true,
    "OnAccount": false,
    "MerchantId": "340xx",
    "AccountId": "386xx",
    "PortalId": "20244xx",
    "Mode": "Test",
    "BankAccountHash": "xxxx9762bb8bcfd2c8dabbd0cc9d8f3be0c287beb67d74ee8417d6fcf0a49518c5b7345b9818d17adc7676205db9xxxx",
    "CreditCardHash": "xxxx67e1ed11406739e3b1d5e8becc99ba48c7b51d82597e3d0503b8cf11e11f05e09bc13588ccf0fa2fe8b670a6xxxx",
    "DefaultPreauthAmount": {
      "CreditCard": 1,
      "Debit": 1
    }
  }
}
getAvailablePaymentMethodEnum() Returns a list of available payment methods without any details.
[
  "InvoicePayment",
  "CreditCard:PayOne",
  "Debit:PayOne"
]

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.
cart Type: cart A description of the products in this order.
customerData Type: customerData Information 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.
success
Show callback data
{
  "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.
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.
subscriptionJSPayment Type: SubscriptionJS.Payment An instance of SubscriptionJS.Payment.
cart Type: cart A description of the products in this order.
customer Type: customerData Information 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.
secretPaymentData Type: secretPaymentData The potentially secret payment information entered by the customer to pay for the order.
success
Show callback data
{
  "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.
cart Type: cart A description of the products in this order.
customerData Type: customerData Information 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.
{
  "firstName": "Marcellus",
  "lastName": "Wallace",
  "emailAddress": "mw@example.com"
  "vatId" : "DE123465789"
}
success
Show callback data
{
  "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.
selfServiceOrder Type: selfServiceOrder A wrapper for customerData, cart and optional Contract-/OrderCustomFields.
success
Show callback data
{
  "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.
subscriptionJSPayment Type: SubscriptionJS.Payment An instance of SubscriptionJS.Payment.
secretPaymentData Type: secretPaymentData The potentially secret payment information entered by the customer to pay for the order.
order Type: order An 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" }
success
Show callback data
{
  "OrderId": "5ca4af02bb573feacc9f7b55",
  "ContractId": "5ca4af0250abb730802f9e3e",
  "CustomerId": "5ca4af0250abb730802f9e3d",
  "GrossTotal": 89.25,
  "Currency": "EUR",
  "OrderStatus": "InProgress"
}
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 secretPaymentData.
paySignupInteractive(subscriptionJSPayment, secretPaymentData, order, success, error) Initiates interactive payment of the given order.
subscriptionJSPayment Type: SubscriptionJS.Payment An instance of SubscriptionJS.Payment.
secretPaymentData Type: secretPaymentData The potentially secret payment information entered by the customer to pay for the order.
order Type: order An 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" }
success
Show callback data
{
  "OrderId": "5ca4af02bb573feacc9f7b55",
  "ContractId": "5ca4af0250abb730802f9e3e",
  "CustomerId": "5ca4af0250abb730802f9e3d",
  "GrossTotal": 89.25,
  "Currency": "EUR",
  "OrderStatus": "InProgress"
}

SubscriptionJS.Portal

SubscriptionJS.Portal(customerToken) Constructor. Creates an instance of SubscriptionJS.Portal.
customerToken Type: string A token to identify and authenticate a customer. You can request this token from the API via GET /contracts/:contractId/selfServiceToken.
upgradePaySync(orderId, success, error) Allows the customer to pay for an upgrade using the currently active payment method in a 'synchronous' fashion, i.e. the success method will be called only after the call to the PSP has finished. This method is non-interactive, the user can't change the active payment method using this call. Also note that this does not require to load client-side payment libraries.
orderId Type: string Id of an order to pay for. The order must have been created before using a backend API call.
success
Show callback data
{
  "OrderId": "5ca5d0fd12a50c79c94f46f0",
  "ContractId": "5ca4b04a50abb730802f9e78",
  "CustomerId": "5ca4b04a50abb730802f9e77",
  "GrossTotal": 387.6,
  "OrderStatus": "PaymentPending"
}
upgradePayInteractive(subscriptionJSPayment, secretPaymentData, order, success, error) Allows the customer to pay for an upgrade using new payment data. This method is interactive. Forward user to PSP page if URL is returned. See 'Integrating Black Label Providers'.
subscriptionJSPayment Type: SubscriptionJS.Payment An instance of SubscriptionJS.Payment.
secretPaymentData Type: secretPaymentData The potentially secret payment information entered by the customer to pay for the order.
order Type: order An 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" }
upgradePayInteractive(null, paymentForm, order, success, error) [paymentForm EXCLUSIVE]
Behaves like upgradePayInteractive, except subscriptionJsPayment is not necessary and paymentForm is submitted instead of secretPaymentData.
invoicePdfDownloadUrl(invoice) Creates a download url for a PDF document. The URL will point to billwerk, so using this method makes billwerk 'visible' to your customers. If you want to avoid this, you will have to route requests through your server or mirror the PDFs proactively. To get a list of invoices for a contract please use the function contractDetails(...).
invoice Type: string or an invoice object Either the id of the invoice or an invoice object that has an 'Id' field.
a url string to download the PDF, including the customerToken that is required for authentication.
contractDetails(success, error) Returns details about the current contract, customer, and payment method. It also lists up to 50 recent invoices.
success
Show callback data
{
  "Customer": {
    "Id": "5ca4b06750abb730802f9e90",
    "CreatedAt": "2019-04-03T13:08:55.0000000Z",
    "FirstName": "Marcellus",
    "LastName": "Wallace",
    "Locale": "de",
    "EmailAddress": "mhw@example.com",
    "DefaultBearerMedium": "Email",
    "Address": {
      "Street": "123123123",
      "HouseNumber": "11",
      "PostalCode": "1234",
      "City": "Frankfurt",
      "Country": "DE"
    },
    "CustomFields": {}
  },
  "RecentInvoices": [
    {
      "Id": "5ca4b06750abb730802f9e9e",
      "InvoiceDate": "2019-04-03T13:08:55.0000000Z",
      "TotalGross": 89.25,
      "InvoiceNumber": "0781",
      "DueDate": "2019-04-10T00:00:00.0000000Z"
    }
  ],
  "Contract": {
    "LifecycleStatus": "Active",
    "CurrentBalance": 89.25,
    "Currency": "EUR",
    "StartDate": "2019-04-03T13:08:55.7790000Z",
    "NextBillingDate": "2019-05-03T13:08:55.7790000Z",
    "PaymentBearer": {
      "Type": "InvoicePayment"
    },
    "PaymentProvider": "InvoicePayment",
    "PaymentProviderRole": "BlackLabel",
    "CustomFields": {}
  },
  "ComponentsSubscriptions": [],
  "CurrentPlan": {
    "PlanName": "Mein Produkt - Basic",
    "PlanDescription": "enthält alle basic-Funktionen",
    "Quantity": 1,
    "StartDate": "2019-04-03T13:08:55.7790000Z"
  },
  "LastPossibleCancellationDate": "2019-05-03T13:08:55.7790000Z",
  "EndDateIfCancelledNow": "2019-06-03T13:08:55.7790000Z",
  "PaymentsBlocked": false,
  "Products": {
    "PlanGroups": [
      {
        "Id": "5c90fc8450abb71aa0bf038f",
        "TimeGranularity": "Precise",
        "Name": {
          "_c": "Standard"
        },
        "Currency": "EUR",
        "PriceTaxType": "Net",
        "TaxPolicyId": "5c1b9df850abb72e4c1d16e4"
      }
    ],
    "Plans": [
      {
        "PlanGroupId": "5c90fc8450abb71aa0bf038f",
        "Id": "5c90fc8450abb71aa0bf0397",
        "Name": {
          "_c": "My Product - Advanced",
          "de": "Mein Produkt - Advanced"
        },
        "SetupDescription": {
          "_c": "Setup fee",
          "de": "Einrichtungsgebühr"
        },
        "PlanDescription": {
          "_c": "all basic features plus feature deluxe included",
          "de": "enthält alle basic-Funktionen plus das Feature Deluxe"
        },
        "TrialEndPolicy": "NoTrial",
        "IsQuantityBased": false,
        "Hidden": false,
        "IsDeletable": false,
        "RequiresOrderApproval": true,
        "CustomFields": {}
      },
      {
        "PlanGroupId": "5c90fc8450abb71aa0bf038f",
        "Id": "5c90fc8450abb71aa0bf0393",
        "Name": {
          "_c": "My Product - Basic",
          "de": "Mein Produkt - Basic"
        },
        "SetupDescription": {
          "_c": "Setup fee",
          "de": "Einrichtungsgebühr"
        },
        "PlanDescription": {
          "_c": "all basic features are included",
          "de": "enthält alle basic-Funktionen"
        },
        "TrialEndPolicy": "NoTrial",
        "IsQuantityBased": false,
        "Hidden": false,
        "IsDeletable": false,
        "RequiresOrderApproval": false,
        "CustomFields": {}
      }
    ],
    "PlanVariants": [
      {
        "Id": "5c90fc8450abb71aa0bf03a7",
        "PlanId": "5c90fc8450abb71aa0bf0397",
        "AllowSelfService": true,
        "AllowWithoutPaymentData": false,
        "ContractPeriod": {
          "Unit": "Month",
          "Quantity": 12
        },
        "LaterContractPeriod": {
          "Unit": "Month",
          "Quantity": 12
        },
        "CancellationPeriod": {
          "Unit": "Month",
          "Quantity": 3
        },
        "LaterCancellationPeriod": {
          "Unit": "Month",
          "Quantity": 3
        },
        "BillingPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "FeePeriod": {
          "Unit": "Month",
          "Quantity": 12
        },
        "PaymentPeriodMode": "PrePaid",
        "Quota": [],
        "RecurringFee": 825,
        "SetupFee": 50,
        "InternalName": "jährliche Laufzeit",
        "Description": {
          "_c": "yearly renewal and yearly payment",
          "de": "jährliche Laufzeit und jährliche Zahlung"
        },
        "BillingDateAlignment": "None",
        "Hidden": false,
        "IsDeletable": false,
        "EndAfterFirstContractPeriod": false
      },
      {
        "Id": "5c90fc8450abb71aa0bf03a3",
        "PlanId": "5c90fc8450abb71aa0bf0397",
        "AllowSelfService": true,
        "AllowWithoutPaymentData": false,
        "ContractPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "LaterContractPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "CancellationPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "LaterCancellationPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "BillingPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "FeePeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "PaymentPeriodMode": "PrePaid",
        "Quota": [],
        "RecurringFee": 75,
        "SetupFee": 50,
        "InternalName": "monatliche Laufzeit",
        "Description": {
          "_c": "monthly renewal and monthly payment",
          "de": "monatliche Laufzeit und monatliche Zahlung"
        },
        "BillingDateAlignment": "None",
        "Hidden": false,
        "IsDeletable": false,
        "EndAfterFirstContractPeriod": false
      },
      {
        "Id": "5c90fc8450abb71aa0bf039f",
        "PlanId": "5c90fc8450abb71aa0bf0393",
        "AllowSelfService": true,
        "AllowWithoutPaymentData": false,
        "ContractPeriod": {
          "Unit": "Month",
          "Quantity": 12
        },
        "LaterContractPeriod": {
          "Unit": "Month",
          "Quantity": 12
        },
        "CancellationPeriod": {
          "Unit": "Month",
          "Quantity": 3
        },
        "LaterCancellationPeriod": {
          "Unit": "Month",
          "Quantity": 3
        },
        "BillingPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "FeePeriod": {
          "Unit": "Month",
          "Quantity": 12
        },
        "PaymentPeriodMode": "PrePaid",
        "Quota": [],
        "RecurringFee": 275,
        "SetupFee": 50,
        "InternalName": "jährliche Laufzeit",
        "Description": {
          "_c": "yearly renewal and yearly payment",
          "de": "jährliche Laufzeit und jährliche Zahlung"
        },
        "BillingDateAlignment": "None",
        "Hidden": false,
        "IsDeletable": false,
        "EndAfterFirstContractPeriod": false
      },
      {
        "Id": "5c90fc8450abb71aa0bf039b",
        "PlanId": "5c90fc8450abb71aa0bf0393",
        "AllowSelfService": true,
        "AllowWithoutPaymentData": false,
        "ContractPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "LaterContractPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "CancellationPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "LaterCancellationPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "BillingPeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "FeePeriod": {
          "Unit": "Month",
          "Quantity": 1
        },
        "PaymentPeriodMode": "PrePaid",
        "Quota": [],
        "RecurringFee": 25,
        "SetupFee": 50,
        "InternalName": "monatliche Laufzeit",
        "Description": {
          "_c": "monthly renewal and monthly payment",
          "de": "monatliche Laufzeit und monatliche Zahlung"
        },
        "BillingDateAlignment": "None",
        "Hidden": false,
        "IsDeletable": false,
        "EndAfterFirstContractPeriod": false
      }
    ],
    "Components": [],
    "TaxPolicies": [
      {
        "Id": "5c1b9df850abb72e4c1d16e4",
        "Name": "tax",
        "IsDefault": true,
        "IsMossApplicable": false,
        "Entries": [
          {
            "Country": "DE",
            "Rate": 19
          },
          {
            "Country": "EU",
            "Rate": 19
          },
          {
            "Country": "XX",
            "Rate": 19
          }
        ]
      }
    ],
    "Discounts": [],
    "Coupons": []
  },
  "ChangeCustomerDataPermission": true
}
contractCancel(success, error) Cancels the contract regularly, so that it ends at the next possible point in time given by the cancellation period and minimum contract duration settings.
success
Show callback data
{
  "Message": "Contract Cancelled",
  "EffectiveEndDate": "2020-04-04T09:40:13.0040000Z"
}
customerChange(customerData, success, error) Changes a customer's data such as name, address or VAT id.

It will be possible to prohibit this method call under Settings -> SubscriptionJS in case you don't want users to be able to change their data without prior verification, or if you want to allow data changes only in your system.
Caution! Changing customer data affects all contracts of the customer.
customerData Type: customerData An object containing the new customer data. If a field in this object is unset, it will be unset in the customer, too, so this has PUT semantics, not PATCH semantics.

success Empty object
paymentChange(subscriptionJSPayment, secretPaymentData, success, error) Sets up a new payment method for the contract.
subscriptionJSPayment Type: SubscriptionJS.Payment An instance of SubscriptionJS.Payment that will be used to talk to the payment service provider. At present, the instance must be ready before calling this method.
secretPaymentData Type: secretPaymentData Potentially secret payment data required for the respective payment method, e.g. credit card or direct debit information.
success
Show callback data
{
    "ContractId": "5cd186af443e551fe8e4xxxx",
    "CustomerId": "5cd183b8443e551e4446xxxx",
    "GrossTotal": 1
}
paymentChange(null, paymentForm, success, error) [paymentForm EXCLUSIVE]
Behaves like paySignupInteractive, except subscriptionJsPayment is not necessary and paymentForm is submitted instead of secretPaymentData.

General Methods

SubscriptionJS.finalize

SubscriptionJS.finalize(success, error) For interactive PSPs like PayPal this needs to be executed on the return page the PSP redirects to after finishing a payment. It triggers finalizing the order in billwerk. The success and error callback can be used to inform the customer if the order succeeded ot not.

Please note that you must never rely on the finalize page is ever called during the order process, e.g. a customer could close the browser after successful payment or something else happens. Always use our webhooks to be notified a subscription was successful.

SubscriptionJS.createElement

SubscriptionJS.createElement(embeddableElement, embedInElement, config, style, error) SubscriptionJS offers createElement to let you use different embeddable elements, like our paymentForm iframe. A separated documentation can be found here.
embeddableElement Type: string Describes which element will be embedded. Currently we support only paymentForm
embedInElement Type: DOM Element Describes in which DOM element the embeddableElement will be embedded.
config Type: object Configuration object, consists of your public API key, payment methods, locale and Return URL, a more detailed description is found here
style Type: object Style object, which lets you control different properties used in the embeddable element, a more detailed description is found here

Types

paymentConfig A configuration object that must be passed to SubscriptionJS.Payment upon initialization.
publicApiKey Type: string A public key used to identify your account. You can see your key under Settings -> SubscriptionJS.
providerReturnUrl Type: string A url that will be used to redirect users back to your site when using a payment provider that requires redirects, such as PayPal. The page at this url must invoke the SubscriptionJS.finalize() method.

This parameter is required when using PSPs that rely on redirects (e.g. with checkoutpages).
popupCreate Type: function(redirect, cancelCallback) Optional. A function that will be called when a popup must be created. Currently, this is only used for showing 3D-Secure iframes when using paymill. The method signature is the same as in paymill's JS bridge where it's called tdsInit.
popupClose Type: function() Optional. A function called by SubscriptionJS to destroy the popup created using popupCreate. In the paymill documentation, that is called tdsCleanup.

Example

var paymentConfig = {
    // REQUIRED. Your SubscriptionJS public API key
    "publicApiKey": "527cc4c951f45909c493c820",
    // OPTIONAL. for Paymill and PayOne, REQUIRED for PSPs like PayPal, Skrill:
    "providerReturnUrl": "http://yourdomain.com/signup/finalize.html",
    // OPTIONAL. Overwrite the handling of the 3d-secure iframes when using paymill.
    "popupCreate": function(redirect, cancelCallback) { ... }
    "popupClose": function() { ... }
};
            
selfServiceOrder This object acts as a wrapper for customerData and cart. Additionally, you can fill Contract- and OrderCustomFields. Please remember to configure them first in your CustomField settings and allow access for subscriptionJS.
ContractCustomFields Type: object Optional, define your ContractCustomFields as Key-Value-Pairs
CustomFields Type: object Optional, define your order CustomFields as Key-Value-Pairs

Example

var selfServiceOrder = {
      "Cart": {
        "PlanVariantId": "5d4968af443e551420625c4e"
      },
      "Customer": {
        "FirstName": "Marcellus",
        "LastName": "Wallace",
        "VatId": "DE424324234",
        "EmailAddress": "marcellus@example.com",
        "Address": {
          "Street": "Raymond Ave (Holly)",
          "HouseNumber": "145",
          "PostalCode": "91001",
          "City": "Pasadena",
          "Country": "CA"
        }
      },
      "ContractCustomFields": {
        "Im" : "a ContractCustomField"
      },
      "CustomFields": {
        "Im" : "an OrderCustomField"
      }
    }
cart
PlanVariantId Type: ObjectID The id of the plan variant to subscribe to
ComponentSubscriptions Type: array of component orders Optional. An array of additional components to subscribe to. Please note that id must be billwerk' id of the component (i.e. you can't use your own id here) and that the component must not be a metered component.
Heads Up! We'll add support for your own component ids in a future release.
MeteredUsages Type: array of metered usage component orders Optional. An array of additional metered usage components to subscribe to. Please note that id must be billwerk' id of the component (i.e. you can't use your own id here) and that the component must be a metered component.
CouponCode Type: string Optional. Pass a coupon code entered by a customer to take into account the corresponding discount.

Example

var cart = {
    "PlanVariantId" : "527caacdeb596a247c6e0500",
    "ComponentSubscriptions" : [ 
        {
            // required
            "ComponentId" : "5277ba54eb596a0ee85199c6",
            // required, can have decimals
            "Quantity" : 23
        },
        ...
    ],
    "MeteredUsages": [
        {
            // required
            "ComponentId": "5d53f9a050abb95b40fce74a",
            // required, can have decimals
            "Quantity": 2.7
        },
        ...
    ],
    "CouponCode" : "ABC-DEF"
};
secretPaymentData An object that contains payment information such as credit card data or bank accounts.
bearer Type: string A string that indicates which payment provider and payment bearer medium to use. Populate this from the list of available payment providers (refer to the Angular example), or simply hardcode it.

Example

// Credit Card payments
var paymentInfo = {
    "bearer": "CreditCard:Paymill",
    "cardNumber": "5169147129584558",
    "expiryMonth": "12",
    "expiryYear": "2015",
    "cardHolder": "Marcellus Wallace",
    "cvc": "123"
};
// Direct debit payments
var paymentInfo = {
    "bearer": "Debit:Paymill",
    "accountHolder": "Marcellus Wallace",
    "bankAccountNumber": "1234567890",
    "bankRoutingCode": "70050010",
    "mandateReference": "customersMandateReference",
    "mandateSignatureDate": "2019-09-12T11:56:37.8490000Z",
    "mandateText": "yourMandateText"
}
var paymentInfo = {
    "bearer": "Debit:Paymill",
    "accountHolder": "Marcellus Wallace",
    "iban": "DE13501105170648485890",
    "bic": "INGDDEFFXXX",
    "mandateReference": "customersMandateReference",
    "mandateSignatureDate": "2019-09-12T11:56:37.8490000Z",
    "mandateText": "yourMandateText"
}
// Black Label payment providers
var paymentInfo = { "bearer": "PayPal", "emailAddress" : "paypal_acct@example.com" };
var paymentInfo = { "bearer": "Skrill" };
var paymentInfo = { "bearer": "FakePSP" }; //For testing only
        

The bearer can be one of the following values:

"CreditCard:Adyen",
"CreditCard:Paymill", 
"CreditCard:PayOne", 
"CreditCard:Wirecard", (will be deprecated after 30.06.2019)
"CreditCard:WirecardElastic",
"CreditCard:Stripe",
"CreditCard:Heidelpay",
"CreditCard:FakePSP",
"Debit:Adyen", 
"Debit:Paymill", 
"Debit:PayOne",
"Debit:Wirecard", (will be deprecated after 30.06.2019)
"Debit:WirecardElastic",
"Debit:Heidelpay",
"Debit:SlimPay",
"Debit:Stripe",
"Debit:FakePSP", 
"OnAccount:PayOne",
"PayPal", 
"FakePSP",
"InvoicePayment",
"None:None"

For PayPal PreApprovals the email address has to be passed at this point. It can't be modified during PayPal checkout process. Using PayPal Reference Transactions the email can be passed, but it's not necessary. We'll update the used email address after the payment.
Nonetheless, if not passed, billwerk uses the email address of the customer data.
Important! It is required to integrate credit card payments in a PCI compliant way. Unless you are PCI-DSS certified do not send any credit card data to your server. SubscriptionJS will return a tetheredPaymentInformation object which contains PSP-specific information such as a payment token which will subsequently be sent to Billwerk.
customerData An object that contains information about a customer.
If you need to identify the customer with your own id during signup please use the field tag at this point to pass the foreign Id to billwerk. The customer object also has an externalCustomerId field, which is unique in billwerk. Do not use externalCustomerId during initial signup. Instead read the tag upon signup notification via webhook and set the externalCustomerId by updating the customer object with the REST API.
    {
        "EmailAddress" : "john.doe@example.com",
        "FirstName" : "John",
        "LastName" : "Doe"
        "Tag" : "A53FD212-7879-44AD-923C-56DD20012100",
        "CompanyName" : "ACME, Inc."
        "VatId" : "DE123465789",
        "PhoneNumber" : "0123-45678",
        "Address" : { 
                "AddressLine1": "c/o Coworking Ltd.",
			    "Street": "Torstraße"
			    "HouseNumber": "89a",
			    "PostalCode": "10123",
			    "City": "Berlin",
			    "Country": "DE" 
        },
        "Locale" : "en-US",
        "CustomFields": {
            "InvoiceEmail" : "random@address.com",
            "Whatever" : "you want"
        }
    }
Custom Fields This data type also supports custom fields. To use custom fields in SubscriptionJS at all access rights need to be defined from within the billwerk Admin UI on a per-field-base. Because not all custom fields are necessarily accessible via SubscriptionJS the PATCH sematic is different to the one in the REST API. Custom fields not specified in SubscriptionJS will not be removed in the resource. If you want to explicitely remove a custom field pass null. For further detail please also take a look here.
{
    customFields :
    {
        myCustomFieldKey1 : "MyCustomFieldValue1" ,
        myCustomFieldKey2 : null //Will be removed
        //If MyCustomFieldKey3 exists it will not be removed
    }
}
{
    customFields.myCustomFieldKey1 : "MyCustomFieldValue1",
    customFields.myCustomFieldKey2 : null //Will be removed
}

Callbacks

success(successData) Most SubscriptionJS methods provide a success callback. Please refer to each method to see in which form successData will be provided.
error(errorData) Most SubscriptionJS methods provide a callback to handle errors.
{
    errorCode : ["InvalidCardCvc"],
    errorMessage : "",
    referenceId: "",
    referenceUrl: "",
    details: ""
}
Please check the structure of the passed object before using it. Currently, the passed object might have a different structure under certain circumstances.
errorMessage is an error message for your internal use. It is NOT prepared for direct notification of the customer.
referenceId Reserved for future use.
referenceUrl Reserved for future use.
details Reserved for future use.
errorCode is an array that provides a hierarchy of error codes. At least one value is provided. This can be used to implement error specific behaviour of your page, e.g. inform the customer some credit card data was incorrect and let him correct it.

Possible values created by SubscriptionJS:
IteroServerError,
PspServerError,
Timeout,
InvalidKey,
InvalidConfiguration,
InvalidPaymentData,
InvalidData,
UnmappedError,
Aborted,
AcquirerServerError,
AuthorizationRejected,
RateLimit,
InvalidTransaction,
AmountLimitExceeeded,
InvalidPaymentMethod,
InvalidCardType,
InvalidCardNumber,
InvalidExpirationDate,
InvalidCardCvc,
InvalidCardHolder,
3DsProblem,
InvalidAmount,
InvalidCurrency,
InvalidAccountNumber,
InvalidAccountHolder,
InvalidBankCode,
InvalidIban,
InvalidBic,
InvalidCountry,
BearerRejected,
BearerExpired,
InvalidCouponCode
Possible values returned by the server on failed payments:
LimitExceeded,
BearerInvalid,
BearerExpired,
InvalidCountry,
InvalidAmount,
InvalidCurrency,
LoginError,
InvalidData,
InsufficientBalance,
AlreadyExecuted,
InvalidPreconditions,
InternalError,
InternalProviderError,
RateLimit,
InvalidConfiguration,
PermissionDenied,
Canceled,
Rejected,
UnmappedError //for PSP errors not mapped to a specific billwerk code
PSPConnectionProblem,
InvalidBic,
InvalidIBAN,
PSPConnectionTimeout