Methods
SubscriptionJS.Payment
The 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.
Notice
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.
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
}
}
}
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 paySignupInteractivedirectly.
The constructor creates an instance of SubscriptionJS.Signup.
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.
Property | Type | Description |
|---|---|---|
cart | cart | A description of the products in this order. |
customerData | 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. |
The successful output of preview():
{
"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
}
}
The error output of preview().
Creates an order and initiates the payment in a single step. This is a mere wrapper for createOrder and paySignupInteractive.
Notice
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 |
cart | cart | A description of the products in this order. |
customer | 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 | secretPaymentData | The potentially secret payment information entered by the customer to pay for the order. |
The successful output of subscribe():
{
"OrderId": "5ca4af02bb573feacc9f7b55",
"ContractId": "5ca4af0250abb730802f9e3e",
"CustomerId": "5ca4af0250abb730802f9e3d",
"GrossTotal": 89.25,
"Currency": "EUR",
"OrderStatus": "InProgress"
}
The error output of subscribe().
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 | A description of the products in this order. |
customer | 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.. |
The successful output of createOrder():
{
"OrderId": "5ca4af02bb573feacc9f7b55",
"ContractId": "5ca4af0250abb730802f9e3e",
"CustomerId": "5ca4af0250abb730802f9e3d",
"GrossTotal": 89.25,
"Currency": "EUR",
"OrderStatus": "InProgress"
}
The error output of createOrder().
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 |
The successful output of createOrder(selfServiceOrder):
{
"OrderId": "5ca4af02bb573feacc9f7b55",
"ContractId": "5ca4af0250abb730802f9e3e",
"CustomerId": "5ca4af0250abb730802f9e3d",
"GrossTotal": 89.25,
"Currency": "EUR",
"OrderStatus": "InProgress"
}
The error output of createOrder(selfServieOrder).
Initiates an interactive payment of the given order.
Property | Type | Description |
|---|---|---|
subscriptionJSPayment | subscriptionJSPayment | An instance of |
secretPaymentData | secretPaymentData | The potentially secret payment information entered by the customer to pay for the order. |
order | order | An order object previously created either via |
The successful output of paySignupInteractive().
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 an 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"
}
The error output of paySignupInteractive().
[paymentForm EXCLUSIVE]
Behaves like paySignupInteractive, except the subscriptionJSPayment is not necessary and the paymentForm is submitted instead of the secretPaymentData.
[paymentForm EXCLUSIVE]
Behaves like paySignupInteractive, except the subscriptionJSPayment is not necessary and the processedPaymentData from processPaymentData() is submitted instead of the secretPaymentData.
SubscriptionJS.Portal
The constructor creates an instance of the SubscriptionJS.Portal.
Property | Type | Description |
|---|---|---|
selfServiceToken | string | A token to identify and authenticate a customer. You can request this token from the API via the GET /api/v1/contracts/{contractId}/selfservicetoken. |
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.
Property | Type | Description |
|---|---|---|
orderId | string | The Id of an order to pay for. The order must have been created before using a back-end API call. |
The successful output of the upgradePaySync():
{
"OrderId": "5ca5d0fd12a50c79c94f46f0",
"ContractId": "5ca4b04a50abb730802f9e78",
"CustomerId": "5ca4b04a50abb730802f9e77",
"GrossTotal": 387.6,
"OrderStatus": "PaymentPending"
}
The error output of the upgradePaySync().
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.
Property | Type | Description |
|---|---|---|
subscriptionJSPayment | SubscriptionJS.Payment | An instance of |
secretPaymentData | secretPaymentData | The potentially secret payment information entered by the customer to pay for the order. |
order | order | An order object previously created either via |
The successful output of the upgradePayInteractive():
{
"OrderId": "5ca4af02bb573feacc9f7b55",
"ContractId": "5ca4af0250abb730802f9e3e",
"CustomerId": "5ca4af0250abb730802f9e3d",
"GrossTotal": 89.25,
"Currency": "EUR",
"OrderStatus": "InProgress"
}The error output of the upgradePayInteractive().
[paymentForm EXCLUSIVE]
Behaves like upgradePayInteractive, except the subscriptionJsPayment is not necessary and the paymentForm is submitted instead of secretPaymentData.
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(...).
Property | Type | Description |
|---|---|---|
invoice | string or invoice object | Either the id of the invoice or the invoice object that has an 'Id' field. A URL string to download the PDF, including the selfServiceToken that is required for the authentication. |
Returns details about the current contract, the customer, and the payment method. It also lists up to 50 recent invoices.
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.
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.
Danger
Changing customer data affects all contracts of the customer.
Property | Type | Description |
|---|---|---|
customerData | 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. |
Sets up a new payment method for the contact.
Property | Type | Description |
|---|---|---|
subscriptionJSPayment | SubscriptionJS.Payment | An instance of |
secretPaymentData | SecretPaymentData | Potentially secret payment data required for the respective payment method, e.g. credit card or direct debit information. |
[paymentForm EXCLUSIVE]
Behaves like the paymentChange, except the subscriptionJsPayment is not necessary and the paymentForm is submitted instead of secretPaymentData.
General
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 or not.
Notice
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 offers createElement to let you use different embeddable elements, like our paymentForm iframe. A separated documentation can be found here.
Property | Type | Description |
|---|---|---|
embeddableElement | string | Describes which element will be embedded. Currently we support only |
embedInElement | DOM Element | Describes in which DOM element the |
config | object | Configuration object, consists of your public API key, payment methods, locale and Return URL, a more detailed description is found here. |
style | object | Style object, which lets you control different properties used in the embeddable element, a more detailed description is found here. |