SubscriptionJS Types

cart

PropertyTypeDescription
PlanVariantIdObjectIdThe id of the plan variant to subscribe to
ComponentSubscriptionsarray of component ordersOptional 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.
MeteredUsagesarray of metered usage component ordersOptional. 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.
CouponCodestringOptional. Pass a coupon code entered by a customer to take into account the corresponding discount.

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

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
}

paymentConfig

A configuration object that must be passed to SubscriptionJS.Payment upon initialization.

PropertyTypeDescription
publicApiKeystringA public key used to identify your account. You can see your key under Settings -> SubscriptionJS.
providerReturnUrlstringA 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).
popupCreatefunction(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.
popupClosefunction()Optional. A function called by SubscriptionJS to destroy the popup created using popupCreate. In the paymill documentation, that is called tdsCleanup.

paymentConfig 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() { ... }
};

secretPaymentData

An object that contains payment information such as credit card data or bank accounts.

PropertyTypeDescription
bearerstringA string that indicates which payment provider and payment bearer medium to use. Populate this from the list of available payment providers or simply hardcode it.

secretPaymentData 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
"CreditCard:Adyen",
"CreditCard:FakePSP",
"CreditCard:NetsEasy"
"CreditCard:PayEx"
"CreditCard:Paymill",
"CreditCard:PayOne",
"CreditCard:Stripe",
"CreditCard:Unzer",
"CreditCard:Worldline",
"CreditCard:Worldpay"

//Debit
"Debit:Adyen",
"Debit:FakePSP",
"Debit:GoCardless",
"Debit:Paymill",
"Debit:PayOne",
"Debit:SlimPay",
"Debit:Stripe",
"Debit:Unzer",
"Debit:Worldpay"

//Miscellaneous
"iDEAL:Adyen",
"MobilePay",
"OnAccount:PayOne",
"PayPal",
"FakePSP",
"InvoicePayment",
"None:None"

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. For PayPal PreApprovals (deprecated) the email address has to be passed at this point. It can't be modified during PayPal checkout process.


Important! It is required to integrate credit card payments in a PCI DSS 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.

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.

PropertyTypeDescription
ContractCustomFieldsobjectOptional, define your ContractCustomFields as Key-Value-Pairs
CustomFieldsobjectOptional, define your order CustomFields as Key-Value-Pairs

selfServiceOrder 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: {
        "I am" : "a ContractCustomField"
    },
    CustomFields: {
        "I am" : "an OrderCustomField"
    }
}
Last updated on 7/19/2021 by AxelDuenninger
← GeneralCallbacks →