Introduction
Quaderno is a set of APIs to automate and improve tax management in businesses of all sizes. Here are some resources that will help you understand the basics of all of them.
The documentation is organized into three major areas:
- Quaderno.js is a javascript library that allows you to calculate sales taxes in your own checkout form.
- Quaderno Checkout is a checkout form that you can use on your site to sell products and subscriptions.
- Quaderno Billing is a small plugin that you can use on your site to let your customers access their receipts and edit their billing data.
- Quaderno API is our billing and tax API that you can use to calculate taxes and manage receipts from your backend.
Not a developer?
A custom Quaderno integration requires you to either be or hire a developer. But you can use Quaderno through any number of third-parties plugins and libraries built by our community, such as for Shopify, Amazon FBA, and WooCommerce.
Need more help?
Just send us an email. We’re always happy to help out with code or any other questions you might have.
The Sandbox
The Quaderno Sandbox mirrors the features found on the Quaderno Production servers and let you to test our API and/or connect your trial accounts from other services like Stripe, PayPal, Braintree, etc.
The Sandbox has parity with the Quaderno main feature set supported by the live environment. This means you can test your Quaderno processes and know they will behave the same on the production servers as they do in the Sandbox environment.
Your credentials for the Production environment does not work on the Sandbox. You need to create a new account.
By using your Sandbox account, you can test and debug your application without referencing any real Quaderno users or their live Quaderno accounts. The Sandbox lets you operate your application in a safe environment and provides you a way to fine tune your Quaderno routines before moving your product into production.
We’re always happy to help out with code or any other questions you might have. Please drop us a line.
Quaderno.js
Introduction
This is the API reference for Quaderno.js. Use Quaderno.js’ APIs to calculate taxes, and accept payments with Stripe and Paypal.
Including Quaderno.js
However you’re using Quaderno.js, you always begin by including the library and setting your API key. To get started, include this script on your pages — it should always be loaded directly from https://js.quaderno.io:
<script src="https://js.quaderno.io/v3/"></script>
If you are using Stripe
as your gateway you should also include Stripe-js library.
<script src="https://js.stripe.com/v3/"></script>
Supported browsers
Quaderno.js strives to support all recent versions of major browsers. For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.
- We support Internet Explorer and Edge per Microsoft's lifecycle policy.
- We support Chrome and Safari on all platforms and Firefox on desktop platforms.
- We support the Android native browser on Android 4.4 and later.
- We respond to bug reports but do not proactively test other mobile browsers.
If you have an issue with Quaderno.js on a specific browser, please contact us so we can improve its support.
Reference
Quaderno.publishableKey = "pk_test00112233445566";
Quaderno.productId = "prod_0011223344556677";
Quaderno.gateway = "stripe";
Quadeno.firstName = "Perro";
Quaderno.lastName = "Muchacho";
Quaderno.email = "perro@muchacho.com";
Quaderno.streetLine1 = "C/Enrique Jardiel Poncela 4 ";
Quaderno.city = "Madrid";
Quaderno.postalCode = "28016";
Quaderno.region = "Madrid";
Quaderno.country = "ES";
Quaderno.redirectUrl = "https://your-webpage.com/thank-you";
When you include the Quaderno.js script in your page, a global Quaderno
object will be available with the following attributes:
Attribute | Description |
---|---|
publishableKey |
Your Quaderno publishable key. |
productId |
The Quaderno code of the product you want to sell. |
gateway |
The payment gateway to process the transaction. Supported values are: stripe and `paypal. Default is stripe. |
firstName |
|
lastName |
|
email |
|
companyName |
|
streetLine1 |
|
streetLine2 |
|
city |
|
postalCode |
|
region |
|
country |
ISO 3166-1 alpha-2 |
businessNumber |
A valid business number. Supported values are: EU VAT numbers, ABN, and NZBN. |
coupon |
A valid Stripe subscription percent off discount coupon mapped in your Quaderno account. |
redirectUrl |
URL to which redirect your customers after finishing the checkout process in PayPal. Mandatory if gateway value is set to paypal . |
init( publishableKey, productId [, options] )
Quaderno.init(publishableKey, productId, {
gateway: "stripe",
firstName: "Marcial",
lastName: "Ruiz Escribano"
}).then(function(response){
console.log(response.gateway, response.product);
}).catch(function(error){
console.log(error.description, error.messages);
});
Async request. Use this method to initialize the global object Quaderno
.
It accepts an optional options
object. Available options are documented below:
Attribute | Description |
---|---|
gateway |
The payment gateway to process the transaction. Supported values are: stripe and paypal . Default is stripe. |
firstName |
|
lastName |
|
email |
|
companyName |
|
streetLine1 |
|
streetLine2 |
|
city |
|
postalCode |
|
region |
|
country |
ISO 3166-1 alpha-2 |
businessNumber |
A valid business number. Supported values are: EU VAT numbers, ABN, and NZBN. |
redirectUrl |
URL to which redirect your customers after finishing the checkout process in PayPal. Mandatory if gateway value is set to paypal . |
This method returns a Promise
which resolves with a result
object. This object has either:
- result.gateway: a
gateway
object with general info about the chosen payment processor. - result.product: a
product
object.
If there's any issue, this method returns a Promise
which rejects with an error
object. This object has either:
- error.description: A full description of the error.
- error.messages: If present, it indicates the affected attribute and an specific error (ie.
{ email: "invalid", businessNumber: "invalid" }
).
initForm( formId )
Quaderno.initForm("#formId").then(function(response){
console.log(response.gateway, response.product);
}).catch(function(error){
console.log(error.description, error.messages);
});
Async request. This method also initializes the global object Quaderno
from a form object.
This method returns a Promise
which resolves with a result
object. This object has either:
- result.gateway: a
gateway
object with general info about the chosen payment processor. - result.product: a
product
object.
If there's any issue, this method returns a Promise
which rejects with an error
object. This object has either:
- error.description: A full description of the error.
- error.messages: A brief description if each invalid attribute.
calculateTaxes()
Quaderno.calculateTaxes().then(function(taxObject){
console.log(taxObject.name, taxObject.rate, taxObject.country); // ie. "VAT", 20, "GB"
})
Async request. Calculates the taxes based on the billing data from the Quaderno
object.
This method returns a Promise
which resolves with a tax
object.
calculatePrice()
priceObject = Quaderno.calculatePrice();
priceObject.subtotal;
priceObject.taxes;
Calculates the final price of the product, tax inclusive.
This method returns a price
object with the following attributes:
- subtotal: the price without taxes and discounts.
- taxes: the taxes amount.
- total: the final amount.
- discountedAmount: The amount minus the applied discount
createTransaction( cardToken )
Quaderno.createTransaction(cardToken).then(function(transactionDetails){
console.log(transactionDetails)
}).catch(function(error){
// Show the error message if the transaction couldn't be created
alert(error.description);
})
Async request. Creates either a subscription or a one-off charge if the payment gateway is Stripe.
This method returns a Promise
which resolves with an object with information related to the recently created transaction.
redirectToPayPal()
Quaderno.redirectToPayPal().catch(function(error){
// Show the error message if the redirection cannot be done
alert(error.description);
})
Async request. Automatically redirect your customer to the PayPal checkout page.
Remember to specify a value for redirectURL
field in order to be able to use this method.
destroy()
Quaderno.destroy();
Remove event listeners from the DOM elements. It might be useful if you have single-page apps and have tied the Quaderno object to a form via initForm
or the simple initialization.
getGateway()
Quaderno.gateway = "stripe";
Quaderno.getGateway().then(function(gateway){
// Stripe publishable key needed for card tokenization
console.log(gateway.gatewayKey);
});
Async request. Retrieves the payment gateway public key. Returns a gateway
object in the resolve function.
getProduct()
Quaderno.productId = "productId";
Quaderno.getProduct().then(function(product){
console.log(product.name);
});
Async request. Retrieve the product info identified by productId
. Returns a product
object in the resolve function.
getTaxes()
taxes = Quaderno.getTaxes();
taxes.name;
taxes.rate;
taxe.country;
Reads the taxes cache and returns a tax
object.
reload()
Quaderno.gateway = "stripe";
Quaderno.productId = "anotherProduct";
Quaderno.reload().then(function(response){
console.log(response.gateway, response.product);
}).catch(function(error){
console.log(error.description, error.messages);
});
Async request. Reloads the object Quaderno
if any notable configuration options (mainly publishableKey
and productId
) have been modified.
This method returns a Promise
with the same behavior as Quaderno.init
validateBusinessNumber()
Quaderno.businessNumber = "GB1234567";
Quaderno.country = "GB";
Quaderno.validateBusinessNumber().then(function(response){
console.log(response.valid);
}).catch(function(error){
console.log(error.descriptions);
});
Async request. This method validates the customer's business number. Currently Quaderno validates EU VAT numbers, ABN, and NZBN.
This method returns a result
object with the following attribute:
- result.valid: true, false or null.
The Tax object
This object is passed by the resolve function of the Promise
returned by the Quaderno.calculateTaxes
method or by invoking Quaderno.readTaxes
.
Attribute | Description |
---|---|
country |
A valid ISO 3166-1 alpha-2 code. |
region |
|
county |
|
name |
|
rate |
|
extraName |
|
extraRate |
|
taxClass |
The tax class of the transaction. Can be one of the following: standard , eservice or ebook . |
invalidCoupon |
Boolean. If a coupon was passed, indicates wether it was valid or not. |
discountedAmount |
The original amount minus discounts. |
percentOff |
The discount rate applied. |
The Gateway object
Contains relevant information about the payment gateway. Currently, it only works for Stripe. It's returned by the resolve function of Quaderno.init
, Quaderno.initForm
(in conjunction with the product object) or Quaderno.getGateway
. It contains just an attribute:
Attribute | Description |
---|---|
gatewayKey |
Your Stripe publishable key. |
The Product object
This object contains the relevant information related to the productID you've set. It's returned by the resolve function of Quaderno.init
, Quaderno.initForm
(in conjunction with the gateway object) or Quaderno.getProduct
.
Attribute | Description |
---|---|
name |
A valid ISO 3166-1 alpha-2 code. |
image |
|
gateway |
The payment gateway to process the transaction. Supported values are: stripe and paypal . Default is stripe . |
unitCost |
|
currency |
|
kind |
Indicate if the product is either a subscription or a one-off . |
extraRate |
|
taxClass |
The tax class of the transaction. Can be one of the following: standard , eservice or ebook . |
taxType |
Indicates if the tax is included or excluded from the unitCost |
How to initialize Quaderno.js
Simple automatic init
Automatically loads quaderno.js if the form has the quaderno-payment-form
ID and a valid data-publishable-key
and data-product-id
.
- data-publishable-key: Your Quaderno public key
- data-product-id: The product code you've registered in Quaderno
The input fields will be automatically detected as long as they have the data-quaderno
with their definition:
- firstName (mandatory)
- lastName
- streetLine1
- streetLine2
- city
- region
- postalCode
- country (mandatory)
- businessNumber
- taxId
<head>
<script src="https://js.quaderno.io/v3/"></script>
</head>
<body>
<form id="quaderno-payment-form" data-publishable-key="pk_xxxxxxxx" data-product-id="prod_xxxxxxxx">
<input data-quaderno="firstName" />
<input data-quaderno="lastName" />
<select data-quaderno="country"> <!--options … --> </select>
<!-- … -->
</form>
</body>
Deferred automatic init
If you don't want the form to load automatically, you can load it later by not using the "quaderno-payment-form" id, and calling the initForm
method whenever you want.
<head>
<script src="https://js.quaderno.io/v3/"></script>
</head>
<body>
<form id="payment-form" data-publishable-key="pk_xxxxxxxx" data-product-id="prod_xxxxxxxx">
<input data-quaderno="firstName" />
<input data-quaderno="lastName" />
<!-- … -->
</form>
<script>
Quaderno.initForm('#payment-form').then(function(response) {
console.log(response.gateway, response.product);
}).catch(function(error){
console.log(error.description, error.messages);
});
</script>
</body>
Custom init
Futhermore, you can also dissociate Quaderno from the DOM by setting the Quaderno object properties by yourself. This means you need to explicitly set the minimum mandatory configuration options during the init
call.
- publishableKey: Your Quaderno publishable key.
- productId: The ID of the product registered in Quaderno.
<label for="country">
<span>Country</span>
<input id="country" name="country" value="ES" />
</label>
<label for="postal-code">
<span>Postal code</span>
<input id="postal-code" name="postal-code" value="35007" />
</label>
<script>
Quaderno.init(publishableKey, productId,
{
gateway: 'stripe',
country: $('#country').val(),
postalCode: $('#postal-code').val(),
}
).then(function(response) {
console.log(response.gateway, response.product);
}).catch(function(error) {
console.log(error.description, error.messages);
});
</script>
By using the custom init, you can also programmatically swap configuration options by setting the Quaderno attributes and reloading it. In this example we are swapping the product and reloading so we can get the new product information:
Quaderno.productId = 'newProductId';
// As the new product might have a different price and/or taxes configurations, we must call "reload" to retrieve the missing information
Quaderno.reload().then(function(response) {
console.log(response.gateway, response.product);
}).catch(function(error) {
console.log(error.description, error.messages);
});
Usually you want to reload
the checkout when one of those values has changed:
- gateway
- productId
How to use Quaderno.js to calculate taxes
In this example, we are going to handle updates on the relevant tax-related fields to force taxes calculations and show it in a
<span>
:
<label for="country">
Country
<select id="country">
<option value="US" selected>United States</option>
<option value="GB">United Kingdom</option>
<option value="DE">Germany</option>
<option value="FR">France</option>
<option value="IT">Italy</option>
<option value="ES">Spain</option>
<option value="CA">Canada</option>
<option value="AU">Australia</option>
…
</select>
</label>
<label for="postal-code">
Postal code
<input id="postal-code">
</label>
<label for="business-number">
<input id="business-number">
</label>
Taxes: <span id="tax-rate"></span>
<script>
function reloadTaxes(){
Quaderno.calculateTaxes().then(function(taxObject){
document.querySelector('tax-rate').innerHTML = taxObject.name + " " + taxObject.rate + "%"; // ie.: VAT 20%
})
}
// Handle the change events on the relevant user-inputs
document.querySelector('#country').addEventListener('change', function () {
Quaderno.country = this.value
reloadTaxes()
})
document.querySelector('#postal-code').addEventListener('change', function () {
Quaderno.postalCode = this.value
reloadTaxes()
})
document.querySelector('#business-number').addEventListener('change', function () {
Quaderno.businessNumber = this.value
reloadTaxes()
})
</script>
You can use Quaderno.js to calculate taxes by invoking the method Quaderno.calculateTaxes
.
If you are showing real time taxes calculations it's usually a good idea to force taxes calculations when the country, postal code or business number has changed.
How to use Quaderno.js to charge your customers
All the methods described in this page needs at least two mandatory attributes:
- Your Quaderno publishable key.
- The ID of the product you want to sell.
Whether your transaction is a recurring charge or a one-off charge is determined by the way you've registered the product in Quaderno. Choose "subscription" if you want a recurring charge or "one-off" if you want a one-off charge.
With simple automatic init or deferred automatic init
The simple automatic init is the most simple way to integrate Quaderno.js with your page. You just need to set some attributes on your checkout form and Quaderno.js will automatically link to it in order to show live taxes calculations and grab the necessary data from your customer input. Then you will only need to tokenize the card and handle the success or the errors.
The deferred automatic init is almost the same but it let you decides when and to which form should Quaderno.js be initialized by providing the function Quaderno.initForm
(more information here).
Either way, in order to create a transaction first, grab the code of your subscription product and paste it as the data-product-id
in your form. For example:
<div id="payment-errors"></div>
<form id="quaderno-payment-form"
data-publishable-key="pk_test_publishable_key"
data-product-id="prod_code"
data-gateway="stripe">
<label>
<span> First name </span>
<input data-quaderno="firstName">
</label>
<label>
<span> Last name </span>
<input data-quaderno="lastName">
</label>
<label>
<span> Country </span>
<input data-quaderno="country">
</label>
<label>
<span> Postal code </span>
<input data-quaderno="postalCode">
</label>
…
<div id="card-element"></div>
<button type="submit" id="submit-button">Pay now</button>
</form>
When the customer submits the form, in case you are using a card payment method such as Stripe, you'll need to first tokenize the card and pass the resulting token to Quaderno.createTransaction
. In the following example we are loading our core after the page has been properly loaded in order to tokenize the card:
<script>
window.addEventListener('load', function(){
var form = document.getElementById('quaderno-payment-form');
var errorPanel = document.getElementById('payment-errors');
// Setup the form handlers after Quaderno.js has been initialized
form.addEventListener('initialized.Quaderno', function() {
var stripe = Stripe(Quaderno.gatewayKeys.stripe);
var elements = stripe.elements();
var card = elements.create('card', { hidePostalCode: true });
card.mount('#card-element');
// Handle submit event on the form
form.addEventListener('submit', function(event) {
event.preventDefault();
var button = document.getElementById('submit-button');
// Disable the submit button to prevent multiple clicks
button.disabled = true;
// Tokenize the card
stripe.createToken(card).then(function(result) {
if (result.error) {
// Inform the customer that there was an error.
errorPanel.textContent = result.error.message;
button.disabled = false;
} else {
// If the tokenization was a success then send the token to your server.
Quaderno.createTransaction(result.token.id).then(function(response){
// Submit the form to your backend if everything was correct
form.submit();
}).catch(function(error){
// Show the error message if the transaction couldn't be created
errorPanel.textContent = error.description;
button.disabled = false;
})
}
});
})
})
})
</script>
Please note the relevant parts in the snippet from above, first we call stripe.createToken
in order to tokenize the card, as it's a JS promise, we expect the result inside the resolve function. Only if there isn't any errors we attempt to create the transaction in Stripe by calling Quaderno.createTransaction
.
If you use PayPal then it's much simpler as it doesn't require any card tokenization, you just need to redirect your customer to PayPal after they submit the form. As a downside as the customer is redirected outside of our checkout, we are no longer able to return the PayPal in the promise:
<script>
window.addEventListener('load', function(){
var form = document.getElementById('quaderno-payment-form');
var errorPanel = document.getElementById('payment-errors');
// Setup the form handlers after Quaderno.js has been initialized
form.addEventListener('initialized.Quaderno', function() {
// Handle submit event on the form
form.addEventListener('submit', function(event) {
event.preventDefault();
var button = document.getElementById('submit-button');
// Disable the submit button to prevent multiple clicks
button.disabled = true;
// Redirect your customer to PayPal
Quaderno.redirectToPayPal().catch(function(error){
// Handle possible errors
errorPanel.textContent = error.description;
button.disabled = false;
});
})
})
})
</script>
In this case the relevant function is Quaderno.redirectToPayPal
, in case of success it automatically redirects the customer to the PayPal payment page, otherwise we will catch the error in the reject block and show it to the customer.
Remember that in order to use Paypal, you should have set the value of the payment form attribute data-gateway
to paypal
. In addition to that, you should have set a value for redirectURL
so you can use Quaderno.redirectToPayPal
. If you are using the automatic initialization method, you should use the data-redirect-url
attribute in the form tag so it is automatically detected.
With custom init
<h1>James Tiberius Kirk</h1>
<span id="country">CH</span>
<label>
Postal code
<input id="postal-code" />
</label>
<script>
var publishableKey = 'pk_test_0123456789';
var productId = 'prod_0123456789';
Quaderno.init(publishableKey, productId,
{
gateway: 'stripe',
firstName: $('h1').html(),
streetLine1: 'USS Enterprise',
country: $('#country').val(),
}
).then(function(response) {
console.log(response.gateway, response.product);
}).catch(function(error) {
console.log(error.description, error.messages);
});
</script>
The custom init provides you all the flexibility you need in order to integrate Quaderno.js with your system. Unlike the automatic init or the deferred automatic init, it doesn't require the rigid schema of data
attributes, it doesn't even require to be linked to any element from the DOM if you don't want to!
The way it operates is very simple, you just need the global Quaderno object and assign your customer attributes to its accepted fields.
First we need to initialize the Quaderno
object:
After you have the Quaderno object correctly configured, all you need is to tokenize the card (if you are using a card payment method) and create the transaction via Quaderno.createTransaction
:
<h1>James Tiberius Kirk</h1>
<span id="country">CH</span>
<label>
Postal code
<input id="postal-code" />
</label>
<!-- Card container for Stripe elements. You can get more information here: https://stripe.com/docs/stripe-js-->
<div id="card-element"></div>
<button id="pay-button">Pay now!</button>
// Tokenize the card with Stripe and create the transaction.
<script>
var publishableKey = 'pk_test_0123456789';
var productId = 'prod_0123456789';
var stripe = null;
// Initialize the Quaderno object
Quaderno.init(publishableKey, productId,
{
gateway: 'stripe',
firstName: $('h1').html(),
streetLine1: 'USS Enterprise',
country: $('#country').html(),
postalCode: $('#postal-code').val(),
}
).then(function(response) {
// After a successful initialization we can mount Stripe elements
stripe = Stripe(Quaderno.gatewayKeys.stripe);
elements = stripe.elements();
card = elements.create('card', { hidePostalCode: true });
card.mount('#card-element');
// Tokenize the card and create the transaction when the customer clicks the button
$('#pay-button').on('click', function(){
// Disable the button in order to prevent multiple clicks
$(this).attr('disabled', 'disabled');
// Tokenize the card
stripe.createToken(card).then(function(result) {
if (result.error) {
//Tokenization error: inform the customer that there was an error.
alert(result.error.message);
button.disabled = false
} else {
// Just an example of updating the postal code
Quaderno.postalCode = $('#postal-code').val();
// Tokenization success: create the transaction.
Quaderno.createTransaction(result.token.id).then(function(response){
// Submit the form to your backend if everything was correct
form.submit();
}).catch(function(error){
// Show the error message if the transaction couldn't be created
alert(error.description);
button.disabled = false;
})
}
});
})
}).catch(function(error) {
console.log(error.description, error.messages);
});
</script>
If you are using PayPal as the configured gateway, rather than using Quaderno.createTransaction
, you need to call Quaderno.redirectToPayPal
:
<h1>James Tiberius Kirk</h1>
<span id="country">CH</span>
<label>
Postal code
<input id="postal-code" />
</label>
<!-- Card container for Stripe elements. You can get more information here: https://stripe.com/docs/stripe-js-->
<div id="card-element"></div>
<button id="pay-button">Pay now!</button>
// Tokenize the card with Stripe and create the transaction.
<script>
var publishableKey = 'pk_test_0123456789';
var productId = 'prod_0123456789';
// Initialize the Quaderno object
Quaderno.init(publishableKey, productId,
{
gateway: 'paypal',
firstName: $('h1').html(),
streetLine1: 'USS Enterprise',
country: $('#country').html(),
postalCode: $('#postal-code').val(),
redirectUrl: 'https://your-webpage.com/thank-you'
}
).then(function(response) {
// Redirect to PayPal when the customer clicks the button
$('#pay-button').on('click', function(){
// Disable the button in order to prevent multiple clicks
var button = $(this).attr('disabled', 'disabled');
// Just an example of updating the postal code
Quaderno.postalCode = $('#postal-code').val();
// Redirect your customer to PayPal
Quaderno.redirectToPayPal().catch(function(error){
// Handle possible errors
alert(error.description);
button.disabled = false;
});
});
}).catch(function(error) {
console.log(error.description, error.messages);
});
</script>
Quaderno Checkout
Introduction
Checkout is the best billing flow, on web and mobile. Checkout builds on top of Quaderno.js to provide your users with a streamlined, mobile-ready payment experience that is constantly improving.
Try the demo below with this test card number: 4111 1111 1111 1111
Reference
When you include the Quaderno Checkout script in your page, a global QuadernoCheckout
object will be available with the following methods:
configure(options = {})
QuadernoCheckout.configure({
publishableKey: 'pk_test_00112233445566778899',
paypal: true,
cardGateway: 'stripe',
locale: 'es',
callback: function(e){
// Transaction successfully created
console.log(e)
}
});
Configures the basic checkout options that cannot be changed (unless close()
is invoked). Accepts the following options:
Option | Mandatory | Description |
---|---|---|
publishableKey | Yes | Your Quaderno publishable key. |
charge | No | A JWT with extra information about the transaction. |
cardGateway | No | String (only stripe ). Specify if you want to activate the Stripe card inputs |
paypal | No | Boolean. Specify if you want to activate PayPal as payment method |
color | No | The RGB color for the Checkout interface. The default is #4C7800. |
locale | No | Localize the Checkout interface (2-letter ISO code). The default is auto`. |
callback | No (Recommendable) | A function to handle the response details after the transaction for a card payment has been made. |
tosUrl | No (Yes if privacyUrl is present) | An url pointing to a page with your Terms of Service |
privacyUrl | No (Yes if tosUrl is present) | An url pointing to a page with your privacy policy |
open([options = {}])
QuadernoCheckout.open({
redirectUrl: 'https://your-webpage.com/thank-you',
discount: true,
firstName: 'Steve',
lastName: 'Rogers',
email: 'the@nomad.com',
country: 'US',
postalCode: '11201',
productId: '123456',
billingAddress: true
});
Programmatically opens the checkout with the options passed. The parameters supported by the open()
method are the following:
Option | Mandatory | Description |
---|---|---|
redirectUrl | Yes (only if paypal has been set to true ) |
URL to which redirect your customers after finishing the checkout process in PayPal. |
productId | Yes | The ID of the product you want to sell. |
charge | No | A JWT with extra information about the transaction. |
billingAddress | No | The checkout form ask for the customer’s full billing address and tax ID. The default is false. |
panelLabel | No | The label of the payment button in the Checkout (e.g. “Subscribe now”, “Pay {{amount}}”, etc.). If you include {{amount}}, it will be replaced by the provided amount. Otherwise, the amount will be appended to the end of your label. |
company | No | Boolean. Toggle the company name input. Default is false |
firstName | No | Your customer’s first name, to pre-fill the checkout form. |
lastName | No | Your customer’s last name, to pre-fill the checkout form. |
companyName | No | Your customer’s company name, to pre-fill the checkout form. |
No | Your customer’s email address, to pre-fill the checkout form. | |
country | No | 2-letter ISO code. Set it if you want to preload the customer's country. |
discount | No | Customers can enter a coupon code (only works for Stripe subscriptions). The default is false . |
close()
QuadernoCheckout.close();
Programmatically close the checkout form and remove it from your DOM. After this, you can call configure
again if you want to set up basic configuration options again or open()
to reopen the checkout form.
Integration
Depending on your needs, you can either integrate Checkout as just a copy and paste snippet with almost zero coding with the simple integration or you can get more flexibility by using the custom integration.
Simple integration
<form action="/response-handler" method="POST">
<script src="https://checkout.quaderno.io/v3/checkout.js" class="quaderno-button"
data-company="false"
data-publishable-key="pk_test_LNpesCnUBN6Ax__xbmc4"
data-card-gateway="stripe"
data-paypal="true"
data-product-id='prod_61ffa845b4a0b8'
data-locale="en"
data-label="A demo button"
data-billing-address="true"
data-panel-label="Pay {{amount}} now!"
></script>
</form>
You can integrate Checkout in as little as a single line of client-side code. As we release new features, we’ll automatically roll them out to your existing Checkout integration, so that you will always be using our latest technology without needing to change a thing. Just add this <script>
tag inside your checkout <form>
to render the payment button. When a user clicks the button and completes the payment, we will create a charge or a subscription and submit your form with the transaction details along with any other <input>
fields in your form.
Once the transction is complete, a new transactionDetails
input will be added to the form and it will be submitted to your form’s action endpoint, along with any other <input>
in the form.
The transactionDetails
value is a JWT string encoded with your Quaderno private key that contains the transaction details. The transactionDetails
input contains the following data:
{
customer: 'CUSTOMER_ID',
transaction: 'TRANSACTION_ID',
type: 'subscription or charge',
gateway: 'stripe',
product_id: 'PRODUCT_CODE'
iat: UNIX timestamp
}
You can use this data to sync the transaction in your back-end.
These are the accepted data
attributes for configuring checkout in the simple integration:
Option | Mandatory | Description |
---|---|---|
data-publishable-key | Yes | Your Quaderno publishable key. |
data-product-id | Yes | The ID of the product you want to sell. |
data-charge | No | A JWT with extra information about the transaction. |
data-card-gateway | No | String (only stripe ). Specify if you want to activate the Stripe card inputs |
data-paypal | No | Boolean. Specify if you want to activate PayPal as payment method |
data-billing-address | No | The checkout form ask for the customer’s full billing address and tax ID. The default is false. |
data-panel-label | No | The label of the payment button in the Checkout (e.g. “Subscribe now”, “Pay {{amount}}”, etc.). If you include {{amount}}, it will be replaced by the provided amount. Otherwise, the amount will be appended to the end of your label. Only works for Stripe. |
data-tos-url | No (Yes if data-privacy-url is present) | An url pointing to a page with your Terms of Service |
data-privacy-url | No (Yes if data-tos-url is present) | An url pointing to a page with your privacy policy |
data-company | No | Boolean. Toggle the company name input. Default is false |
data-first-name | No | Your customer’s first name, to pre-fill the checkout form. |
data-last-name | No | Your customer’s last name, to pre-fill the checkout form. |
data-company-name | No | Your customer’s company name, to pre-fill the checkout form. |
data-email | No | Your customer’s email address, to pre-fill the checkout form. |
data-country | No | 2-letter ISO code. Set it if you want to preload the customer's country. |
data-label | No | The text to be shown on the button the customer presses to show the checkout form. |
data-color | No | The RGB color for the Checkout interface. The default is #4C7800. |
data-locale | No | Localize the Checkout interface (2-letter ISO code). The default is EN. |
data-coupon | No | Customers can enter a coupon code (only works for Stripe subscriptions). The default is false. |
Custom Integration
The custom integration lets you create a custom DOM element and bind it to the Quaderno Checkout. This permits any HTML element or JavaScript event to start a Checkout payment.
When your page loads, you should create a handler object using QuadernoCheckout.configure()
. You can call open()
on the handler in response to any event.
If you need to abort the Checkout process—for example, when navigation occurs in a single-page application—you can call close()
on the QuadernoCheckout global object.
The publishableKey
, cardGateway
, paypal
, locale
, color
and callback
parameter must be passed to configure()
. Any other options should be passed to open()
.
<head>
<script src="https://checkout.quaderno.io/v3/checkout.js"></script>
</head>
<button id="customButton">Pay with card</button>
<script>
QuadernoCheckout.configure({
publishableKey: 'pk_test_LNpesCnUBN6Ax__xbmc4',
paypal: true,
cardGateway: 'stripe',
locale: 'es',
callback: function(e){
console.log(e);
}
});
$('#customButton').on('click', function(e) {
QuadernoCheckout.open({
redirectUrl: 'https://your-webpage.com/thank-you',
discount: true,
firstName: 'Steve',
lastName: 'Rogers',
email: 'the@nomad.com',
country: 'US',
postalCode: '11201',
productId: '123456',
billingAddress: true
})
});
</script>
In case of successful payment, the callback set in the handler will be invoked. It should accept an argument which contains a JS object with two methods: description
and details
.
The description should contain a brief message about the transaction , while the details
contain a JWT with a the transaction details such as the customer ID or the transaction ID (see the Response Parameters section above for more details).
{
address: "",
businessNumber: "",
companyName: "",
country: "ES",
description: "Charge successfully created.",
details: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJnYXRld2F5Ijoic3RyaXBlIiwidHlwZSI6ImNoYXJnZSIsImN1c3RvbWVyIjoiY3VzX0R4eU5SQ3djUXRYeVVwIiwiZW1haWwiOiJkYWNhc2Nvc0Bvay5jb20iLCJ0cmFuc2FjdGlvbiI6ImNoXzFEZ1ZvWkVqVkh2SU5LbGNWZVJkQWtqSSIsInByb2R1Y3RfaWQiOiIxMjM0NTYiLCJ0YXhfbmFtZSI6IklWQSIsInRheF9yYXRlIjoyMS4wLCJleHRyYV90YXhfbmFtZSI6IklSUEYiLCJleHRyYV90YXhfcmF0ZSI6LTE5LjAsImlhdCI6MTU0NDYxMzgyNH0.LgE7i_PHDVGH881HforhADlS2GbjlrXoDD7Pq4TC_5Y",
email: "magic@taco.com",
firstName: "Super",
lastName: "Nacho",
postalCode: "123456",
taxId: "0011223344",
type: "QCheckout.success"
}
Quaderno Billing
Billing is the simplest way to give your customers access to all their receipts & billing history. They can easily download past receipts and update their billing data by themselves. Improve your billing support with a single line of code.
Reference
When you include the Quaderno Billing script in your page, a global QuadernoBilling
object will be available with the following methods:
configure(options = {})
QuadernoBilling.configure({
key: 'QUADERNO_PUBLIC_KEY',
customer_id: 'CUSTOMER_SECURE_ID_OR_PAYMENT_GATEWAY_ID',
editable: true
})
Configures the basic checkout options that cannot be changed (unless close()
is invoked). Accepts the following options:
Option | Mandatory | Description |
---|---|---|
key | Yes | Your Quaderno publishable key. |
customer_id | Yes | The customer ID. You can also use their Stripe, Braintree, Paymill, or PayPal IDs if the customer was created via those gateways |
editable | No | Select wether or not your user can edit the invoices he opens |
open()
QuadernoBilling.open();
Programmatically opens the billing modal.
close()
QuadernoBilling.close();
Programmatically close the billing modal form and remove it from your DOM. After this, you can call configure
again if you want to set up basic configuration options again or open()
to reopen the billing modal.
Integration
You can integrate Billing in as little as a single line of client-side code. As we release new features, we’ll automatically roll them out to your existing Billing integration, so that you will a be using our latest technology without needing to change a thing.
Simple integration
<script
src="https://billing.quaderno.io/billing.js" class="quaderno-billing-button"
data-key="YOUR_QUADERNO_PUBLISHABLE_KEY"
data-customer-id="YOUR_QUADERNO_CUSTOMER_ID"
data-label="View billing">
</script>
Just add this <script>
tag in your HTML page to render the billing button. When users click the button we’ll show them their past receipts.
Configuration options:
Option | Required | Description |
---|---|---|
data-key | Yes | Your publishable key. |
data-customer-id | Yes | The customer ID. You can also use their Stripe, Braintree, Paymill, or PayPal IDs if the customer was created via those gateways. |
data-label | No | The text to be shown on the default green button. |
data-editable | No | Allow your users to edit their billing data. The default is true. |
Custom integration
<head>
<script src="https://billing.quaderno.io/billing.js"></script>
</head>
<button id="billing">Check your invoices</button>
<script>
QuadernoBilling.configure({
key: 'QUADERNO_PUBLIC_KEY',
customer_id: 'CUSTOMER_SECURE_ID_OR_PAYMENT_GATEWAY_ID',
editable: true
})
$('#billing').on('click', function(e) {
e.preventDefault();
QuadernoBilling.open();
});
</script>
The custom integration lets you create a custom button and bind it to Quaderno Billing. This permits any HTML element or JavaScript event to start launch the modal.
When your page loads, you should create a handler object using QuadernoBilling.configure()
. You can call open()
on the handler in response to any event.
If you need to reload the modal-for example, when navigation occurs in a single-page application—you can call close() on the handler.
The key and customer_id parameter must be passed to configure()
. Any other options can be passed to either configure()
or open()
.