Payments
Several customer interactions involve payments. billwerk offers integration with different payment providers. SubscriptionJS hides most of the complexity so integrating any supported providers is done with the same approach.
Notice
PSP specific workflows
In the vast majority the described workflows are independent from the selected Payment Service Provider. However, due to technical reasons some PSP integrations have slightly differ from the standard workflow. Make sure to check our FAQs for such exceptions by searching for the PSP of your choice.
We also offer a payment method that does not involve any payment provider. On account payments can be used if a customer should be able to transfer money manually from his bank account after an invoice was received. To use this payment method you need to pass the "InvoicePayment" as payment provider.
If a customer should not be required to pass payment information upon subscription, you can pass the "None:None" as payment provider. This is only allowed for plan variants which permit subscriptions without payment information (flag 'allow signup without payment information'). An use case could be that you offer a trial period and want the user to pass a payment information not until trial period has expired. In some use cases it could also be suitable for up-/downgrades.
Nevertheless, let's begin with a basic payment workflow with a transparent PSP.
We distinguish between interactive and non interactive payments. Interactive means a customer interactively enters his payment data like credit card or bank account information. In billwerk the most prominent use case for this kind of payment is the initial signup. Usually upgrading a subscription involves a Non Interactive payment. Payment information has already been provided during signup and will be reused for the upgrade.
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 just need to 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);
Notice
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.
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 process with PSP redirects
This part is mandatory for all payment providers. Even though payment providers are usually transparent, there are processes that 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": "test@example.com" /*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 success callback in this example. If calling subscribe() succeeded 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 finished his payment he might be redirected to this URL. This page is used to finalize the order and show the customer a succes 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 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 done implicitely 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.
Payment Form IFrame
Dealing with PCI DSS compliance can cause a real headache. billwerk therefore provides an easy way to be compliant without the hustle to deal with it yourself for your business. You'll find further information about our paymentForm here.