Billwerk+ Premium & Enterprise supports integration with various payment providers, simplifying the process of integrating any supported provider using SubscriptionJS, which abstracts much of the payment handling complexity.

📘

PSP specific workflows

For the most part, workflows are PSP-agnostic, meaning they don't depend on the selected Payment Service Provider. However, some PSP integrations might deviate slightly due to technical specifics. It's important to review the FAQs for exceptions pertaining to the PSP you're working with.

Alternative Payment Methods

Billwerk+ Premium & Enterprise also caters to scenarios that do not involve standard PSPs:

• On-Account Payments: Allow customers to make bank transfers post-invoice issuance by specifying "InvoicePayment" as the payment provider.
• Deferred Payment Information: To enable subscriptions without immediate payment details, use "None:None" as the payment provider, under the condition, the plan variant allows signups without payment information. This is ideal for:
  • Free trials where payment details are collected post-trial.
  • Subscription upgrades or downgrades where payment details are not immediately needed.

Payment Form Iframe

Dealing with PCI DSS compliance can cause a real headache. Billwerk+ Premium & Enterprise, therefore, provides an easy way to be compliant without the hustle of dealing with it yourself for your business. You'll find further information about our paymentForm here.

Payment Workflow

Starting with a basic payment process using a transparent PSP, we distinguish between two payment interaction types:

• Interactive Payments: The customer provides payment details (such as credit card or bank account information) during the interaction, primarily during initial sign-up.

• Non-Interactive Payments: Payments for upgrades use existing payment methods provided at sign-up, with no need for the customer to input new payment information.

Interactive payments

Interactive payments require two objects. We need to create an SubscriptionJS.Payment instance and an object representing the payment data. The payment data object contains the selected payment method/provider and additional payment information like credit card data if required for the payment method.

paymentService = new SubscriptionJS.Payment({ publicApiKey : "527cc4c951f45909c493c820" },
    function () { /*ready*/ },
    function() { /*error*/ });
var paymentData = {
    "bearer": "CreditCard:Paymill",
    "cardNumber": "5169147129584558",
    "expiryMonth": "12",
    "expiryYear": "2015",
    "cardHolder": "Marcellus Wallace",
    "cvc": "911"
};

Both objects must be passed to the corresponding SubscriptionJS method representing the desired action.

Paying a subscription signup

signupService.paySignupInteractive(subscriptionJSPayment, secretPaymentData, order, success, error);

Paying an upgrade interactively

portalService.upgradePayInteractive(paymentService, paymentData, order, success, error);

Changing the payment method

portalService.paymentChange(paymentService, paymentData, success, error);

🚧

Credit Card Data, PCI-DSS

As you can see from the sample, the credit card data will be known to your own javascript. Make sure that this information is not logged and never sent to your server! SubscriptionJS will hand off any PCI-DSS protected data to the selected PSP so the data is sent from the customer's browser directly to the PSP, thus keeping you from PCI-DSS hassle.
Of course, it is important to deliver the form itself via HTTPS to prevent third parties from tampering with the form. SubscriptionJS is also only available via HTTPS.

Integrating payment processes with PSP redirects

This part is mandatory for all payment providers. Even though payment providers are usually transparent, some processes include redirects to the PSP, e.g. credit card payments with 3D secure. Let's take a look at another signup process. This time, we want to integrate PayPal.

paymentService = new SubscriptionJS.Payment({
        publicApiKey : "527cc4c951f45909c493c820",
        providerReturnUrl : "https://your_domain.com/your_finalize_page"
    },
    function () { /*ready*/ },
    function() { /*error*/ }
);
var paymentData = {
    "bearer": "PayPal",
    "emailAddress": "[email protected]" /*If not passed, billwerk will use the customer's signup email address*/
};
signupService.subscribe(paymentService, cart,  customer, paymentData,
    function(data) {
        if (data.Url) {
            // Open the PSP URL if provided
            window.location.href = data.Url;
        }
        else {
            // No PSP page to open here
        }
    }
, error);

First, please have a look at the successful callback in this example. If calling subscribe() succeeds, it will return a URL that leads to the PSP checkout page. Open it to let the customer go on with the payment. Now, take a look at the initialization of SubscriptionJS.Payment. There is an additional parameter named providerReturnUrl. This URL is passed to the PSP. When the customer finishes his payment, he might be redirected to this URL. This page is used to finalize the order and show the customer a success or error message. The required SubscriptionJS code on this page is a single call:

SubscriptionJS.finalize(success,error);

Except for the mandatory success and error callback, no parameters need to be passed. The PSP added some URL-encoded parameters, which SubscriptionJS passes to the Billwerk+ Premium & Enterprise server. It'll trigger order finalization as paySignupInteractive(), for example, would do for providers without redirect. It is not certain that the order process ever reaches the finalize page, e.g. a customer could simply close the browser after successful payment. Therefore, as a second way of payment confirmation, billwerk is notified by the PSP, which will trigger the same processes as SubscriptionJS.finalize().

Non Interactive payments

A good example is upgrading a subscription. Although SubscriptionJS provides a way to pay upgrades interactively, usually, payment is made implicitly with the payment bearer stored for the subscription.

portalService.upgradePaySync(orderId,success,error);

As you can see for non-interactive payments, no payment information needs to be passed. Non-interactive payments are also triggered by billwerk transparently for each recurring payment.