API Reference
Billwerk+ WebsiteHelp Center ENHelp Center DE

SubscriptionJS Types

Cart Object Structure

The cart object is a critical part of the order process in Billwerk, outlining the subscription plan and additional components for purchase. Here's how the structure is defined:

PropertyTypeDescription
PlanVariantIdObjectIdThe identifier for the specific plan variant the customer wishes to subscribe to.
ComponentSubscriptionsarray of component ordersAn optional array specifying additional components the customer wishes to subscribe to, excluding metered components.
MeteredUsagesarray of metered usage component ordersAn optional array for metered usage components, specifying the Billwerk IDs and any additional details required.
CouponCodestringAn optional field where a coupon code can be entered by the customer for discount application.

The ObjectId is a specific type used in database systems like MongoDB to uniquely identify records, and in this context, it refers to unique identifiers for plan variants and components within the Billwerk system.

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 Object Structure

The customerData object carries detailed information about the customer, required during the signup and billing process. Here's the layout of the customerData object:

Note: The tag field is essential for integrating customer identification from external systems into Billwerk. Upon receiving a signup notification through a webhook, the externalCustomerId can be set or updated by corresponding to Billwerk's REST API, providing a seamless connection between different customer management systems.

{
    "EmailAddress" : "[email protected]",
    "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" : "[email protected]",
        "Whatever" : "you want"
    }
}

Custom Fields in SubscriptionJS

Custom fields are a flexible feature in Billwerk to capture additional, bespoke information about a subscription or customer. Here's how they are managed in SubscriptionJS:

  • Admin UI Configuration: Custom fields need configuration in the Billwerk Admin UI. Access rights are set on a per-field basis.
  • Accessibility: Not all custom fields might be accessible via SubscriptionJS due to the defined access rights.
  • PATCH Behavior: Unlike the REST API, updating resources with SubscriptionJS behaves differently. Unspecified custom fields are not deleted but remain unchanged.
  • Deleting Fields: To remove a custom field with SubscriptionJS, you have to set its value to explicitlynull.

For more specific details and guidance on using custom fields within SubscriptionJS, it's recommended to review the provided documentation and ensure that field access rights are properly set up in the Billwerk Admin UI.

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

Payment Configuration for SubscriptionJS

When initializing SubscriptionJS.Payment, you need to pass a configuration object. The configuration ensures that the payment setup is tailored to your account's needs and that the user experience during the payment process is seamless. Below is an outline of what the paymentConfig object contains:

  • publicApiKey (string): Your unique public key for account identification, found in Billwerk under Settings -> SubscriptionJS.
  • providerReturnUrl (string): The URL to which users are redirected after completing payment on a provider's page, like PayPal. This URL's page must call SubscriptionJS.finalize() to complete the process.
  • popupCreate (function): An optional callback for creating a popup, typically for 3D-Secure verification frames. Used with PSPs like paymill, it follows the paymill JS bridge's method signature for tdsInit.
  • popupClose (function): An optional function that SubscriptionJS invokes to close the popup initialized by popupCreate. This aligns with tdsCleanup from paymill's documentation.

These parameters are crucial for handling payments that involve third-party verification (such as 3D-Secure) and for ensuring that the transaction flow is maintained without interruption.

❗️

We are going to deprocated popupCreate (function) and popupClose (function)

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

Secret Payment Data Structure for SubscriptionJS

The secretPaymentData object holds sensitive payment information like credit card details or bank account numbers. It's a critical part of processing payments securely and must be handled with utmost care to maintain security and privacy. Here's the structure of the secretPaymentData object:

  • bearer (string): A key indicating the payment provider and the bearer (the medium through which the payment is made). It should align with one of the recognized payment providers in the system, and it's set either by selecting from available options or by inputting a predetermined value if known.

When using SubscriptionJS, ensure this object is populated according to the specific requirements of the payment provider you're integrating with to facilitate smooth transactions.

Please find below few examples:

// 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" : "[email protected]" };
var paymentInfo = { "bearer": "Skrill" };
var paymentInfo = { "bearer": "FakePSP" }; //For testing only

Payment Bearer Values for SubscriptionJS

Below is the breakdown of the bearer values you can use in secretPaymentData when setting up payments with SubscriptionJS. The bearer indicates the payment medium and the associated payment service provider (PSP).

Credit Card Options

  • Adyen: CreditCard:Adyen
  • Fake PSP (for testing): CreditCard:FakePSP
  • Nets Easy: CreditCard:NetsEasy
  • PayEx: CreditCard:PayEx
  • Paymill: CreditCard:Paymill
  • PayOne: CreditCard:PayOne
  • Stripe: CreditCard:Stripe
  • Unzer: CreditCard:Unzer
  • Worldline: CreditCard:Worldline
  • Worldpay: CreditCard:Worldpay

Debit Options

  • Adyen: Debit:Adyen
  • Fake PSP (for testing): Debit:FakePSP
  • GoCardless: Debit:GoCardless
  • Paymill: Debit:Paymill
  • PayOne: Debit:PayOne
  • SlimPay: Debit:SlimPay
  • Stripe: Debit:Stripe
  • Unzer: Debit:Unzer
  • Worldpay: Debit:Worldpay

Miscellaneous Payment Methods

  • iDEAL via Adyen: iDEAL:Adyen
  • MobilePay: MobilePay
  • On Account via PayOne: OnAccount:PayOne
  • PayPal: PayPal
  • Fake PSP (for testing purposes): FakePSP
  • Invoice Payment: InvoicePayment
  • No Payment Method: None:None

Each payment method corresponds to a specific service and processing style. Choose the appropriate bearer based on the payment service provider and the payment type your application supports.

📘

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.