Embeddable Elements

Available Elements

subcriptionJS currently offers only one embeddable element, paymentForm. We are planning to expand the list in the future.

Payment Iframe

Introduction

When it comes to payments via credit card PCI DSS compliance is required. When using your own implementation to capture payment data based on SubscriptionJS you need to comply with SAQ A-EP. By using billwerk’s hosted selfservice you are only required to comply with SAQ A. This is also the case, if you use our Payment Form Iframe to capture payment data. Your benefit, with the use of the new separate self service server, is, you only have to deal with the implementation of this single iframe. The element itself is created by SubscriptionJS and can be configured to the needs of your business.

Configuration

The config object enables you to configure everything needed to make the iframe work properly. Required properties are your Public API Key, the desired payment methods, the locale and if needed the provider return URL.
var config = {
    paymentMethods: ["Debit:FakePSP", "CreditCard:FakePSP"],
    publicApiKey: yourPublicApiKey,
    locale: 'en',
    providerReturnUrl: "https://your_domain.com/your_finalize_page"
};

Public API Key

Your Public API Key can be found in your SelfService Settings.

Payment Methods

The payment methods supported are the same as the ones for SubscriptionJS and can be found here. Naturally, you can choose more than one value.

Locale

As seen before the config object offers as well a property locale, which determines the localization of the payment form. Supported locales so far are:
  • English: en
  • German: de
  • French: fr
  • Spanish: es

Provider Return URL

The providerReturnUrl specifies a page on your website a customer returns to after payment on a payment provider page that rely on redirects (e.g. PayPal, Skrill, PayOne with 3D-Secure, ...).

Appearance

The style object provides you control over several elements in the iframe itself. It is applicable to each element following:
var style = {
/* Some example values
{
    backgroundColor: '#ffffff',
    fontSize: '16px',
    fontFamily: '"Times New Roman", Times, serif',
    fontStyle: 'normal',
    color: '#444444',
    borderLeftColor: 'black',
    borderLeftWidth: '5px'
}
*/
    body: {},
    label: {},
    input: {},
    inputRequired: {},
    inputInvalid: {}
}

Body

Label

Input

Required Input & Invalid Input

Examples

A few simple examples on how to use the paymentForm can be found here or directly in this repository.

paymentForm Reference

paymentForm.processPaymentData(totalGross, currency, success, error) processPaymentData sends the payment data to the PSP and returns the processed data or an error. This enables you to do further checks on this data, e.g. BIN checks (CC), bank country (Debit).
totalGross Type: decimal To get the value you have to do a Signup.preview(...) which returns preview.Order.TotalGross
currency Type: string To get the value you have to do a Signup.preview(...) which returns preview.Order.Currency
success
Show callback data
{
  "bearer": {
    "pseudoCardPan": "4111111111111111",
    "TruncatedCardPan": "****",
    "ExpiryMonth": "12",
    "ExpiryYear": "2030",
    "Holder": "Marcellus Wallace"
  },
  "selectedPaymentMethod": "CreditCard:FakeProvider",
  "returnUrl": "https://sandbox.billwerk.com/portal/finalize.html"
}
paymentForm.payerDataChanged(customerData)
Sends the customer data to the paymentForm. This is needed as the form does not know anything about the customers data so far. Must be called on changes to the customer data.
customerData Type: 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.