Quaderno.js Reference

Quaderno.js is a simple javascript library that allows you to process payments, calculate sales taxes (VAT, GST, etc.) on the fly, and send beautiful tax receipts to your customers.

Note: For more help, take a look at our examples.

Including Quaderno.js

Add these script tags to your page to get started with Quaderno.js.

<script src="https://js.stripe.com/v2/"></script> <!--if you're using Stripe -->
<script src="https://js.braintreegateway.com/v2/braintree.js"></script> <!--if you're using Braintree --> 
<script src="https://js.quaderno.io/v2/"></script>

Form Attributes

You have to add some extra attribute to your payment form, so that Quaderno will be able to create a transaction in the back-end.

<form action="" method="POST" id="payment-form"
  data-key="YOUR_QUADERNO_PUBLISHABLE_KEY" 
  data-plan="YOUR_PLAN_ID"> 
...
</form>

Required

Attribute Description
data-key Your Quaderno publishable key.
data-plan The ID of the plan your customer want to subscribe (only for subscriptions, except PayPal).
data-charge JWT with info about the charge (only for one-off charges and PayPal subscriptions). More info below.
Optional
Attribute Description
data-amount The total amount (in cents) that’s shown to the user.
data-taxes Specify if the taxes are  included or excluded in the amount. The default is excluded.
data-transaction-type Specify the transaction type ( eserviceebook or standard). The default is eservice.
data-gateway Specify the payment gateway you’re using ( stripebraintree, or paypal). The default is stripe.

One-Off Charge Info

If the transaction is a one-off charge, the  data-charge attribute MUST contain the following data in a  JWT string, encoded with your Quaderno private key:
Attribute Type Mandatory Description
iat Integer Yes Current UNIX timestamp. We use it to prevent the reuse of the generated JWT after 10 minutes.
amount Integer Yes Total amount of the transaction in cents.
currency String No Currency of the amount (3-letter  ISO code). The default is USD.
description String No Description of the transaction.
item_number String No Only for PayPal. Pass-through variable for you to track product or service purchased.
quantity Integer No Only for PayPal. The quantity of item included in the transaction. The default is 1.
transaction-type String No Specify the transaction type ( eserviceebook or standard). The default is eservice

Here’s an example in Ruby for a €5.90 charge:

JWT.encode({
  iat: Time.now.to_i,
  amount: 590,
  currency: 'EUR'
}, YOUR_QUADERNO_SECRET_KEY)

PayPal Subscriptions

If you want to create a PayPal subscription, the  data-charge attribute MUST contain the following data in a JWT string, encoded with your Quaderno private key:

Attribute Type Mandatory Description
iat Integer Yes Current UNIX timestamp. We use it to prevent the reuse of the generated JWT after 10 minutes.
amount Integer Yes Total amount of the transaction in cents.
currency String No Currency of the amount (3-letter  ISO code). The default is USD.
description String No Description of the transaction.
subscription_unit String No Specify the units of the subscription frequency ( DWMY). The default is M
subscription_duration Integer No Specify the subscription frequency. The default is 1.
recurring_duration Integer No Number of times that subscription payments recur. The default is infinity.

Here’s an example in Ruby for a $9.99 PayPal subscription that is renewed every 3 months:

JWT.encode({
  iat: Time.now.to_i,
  amount: 999,
  subscription_unit: 'M',
  subscription_duration: 3
}, YOUR_QUADERNO_SECRET_KEY)

Form Fields

In order to calculate the right taxes and create a proper invoice in Quaderno, it’s necessary to add some extra inputs. These inputs have a  data-quaderno attribute. It is mandatory to include at least the customer’s first name and country to prevent unexpected results.

Required

Value Description
first-name Customer’s first name.
country Customer’s country (2-letter  ISO code).
Optional
Value Description
last-name Customer’s last name. Necessary for exact tax calculation.
street-line-1 Billing street (1 of 2 fields).
street-line-2 Billing street (2 of 2 fields).
city Billing city.
region Billing region or state.
postal-code Billing postal code (ZIP). Necessary for exact tax calculation.
email Billing email address where we’ll send the receipt.
vat-number Billing VAT number. Necessary for exact tax calculation.
language Customer’s preferred language (2-letter  ISO code). The default is your account language.
coupon The code of the coupon to apply (only for subscriptions).
quantity The quantity you’d like to apply (only for subscriptions).

Processing the Transaction

Quaderno.createSubscription

Quaderno.createSubscription is an ajax function that creates a Stripe subscription on the server and sends a receipt to your customer. This guide explains this flow in more detail.

Quaderno.createSubscription({
  success: quadernoSuccessHandler(status, response),
  error: quadernoErrorHandler(status, response),
  complete: quadernoResponseHandler(status, response)
});

Quaderno.createCharge

Quaderno.createCharge is an ajax function that creates a Stripe one-off charge on the server and sends a receipt to your customer. This guide explains this flow in more detail.

Quaderno.createCharge({
  success: quadernoSuccessHandler(status, response),
  error: quadernoErrorHandler(status, response),
  complete: quadernoResponseHandler(status, response)
});

Extra Fields

If you use the  data-amount form attribute and want to show live tax calculations, you can add the classes quaderno-subtotalquaderno-taxes, and quaderno-total to any DOM element to modify its inner HTML. For example:

<span class="quaderno-subtotal"></span>
<span class="quaderno-taxes"></span>
<span class="quaderno-total"></span>

Handling the Responses

All the handlers accept two arguments:

  • status: the code of the request (200, 201, 401, etc.).
  • response: a Javascript object with the following structure:
{
  message: 'The message of the response as a string',
  details: 'A JWT string with information about the transaction'
}

The details attribute is a JWT string, encoded with your Quaderno private key, that contains the following data:

{
  customer: 'CUSTOMER_ID',
  transaction: 'TRANSACTION_ID',
  type: 'subscription or charge',
  gateway: 'stripe',
  original_charge: 'Original JWT (only for one-off charges)',
  iat: UNIX timestamp 
}

Advanced Usage

Quaderno.init

If you include the identifier  payment-form, Quaderno will associate the necessary callbacks to your form. Nevertheless if the form is not present in the DOM when the page is loaded or if you want to use a different selector you can do it by calling:

Quaderno.init('#custom-form-selector')

Quaderno.calculateTaxes

In order to refresh the taxes calculations when the form is modified, Quaderno will associate the event  change handler on the inputs with the following values for data-quadernocompany-namecountrypostal-codevat-number, and quantity.

If you want to force a taxes calculation or associate your custom events to a taxes calculation, you can do it like this:

Quaderno.calculateTaxes({
  success: function(statusCode, response) { ... },
  error: function(statusCode, response) { ... },
  complete: function(statusCode, response) { ... } 
});

Quaderno.readQuadernoTaxes

If you just want to check the values of the last calculated tax, you can always call do:

Quaderno.readQuadernoTaxes(); // => Object {name: "IVA", rate: 22, notes: null} 
Quaderno.readQuadernoTaxes().name; // => "IVA" 
Quaderno.readQuadernoTaxes().rate; // => 22

taxCalculated.Quaderno

The event  taxCalculated.Quaderno is dispatched on the payment form when a tax is successfully calculated. It’s useful if you want to bind some custom actions to the automatic taxes calculations made by Quaderno.js.

// With plain JavaScript
document.getElementById("payment-form").addEventListener('taxCalculated.Quaderno', function(data){
  alert(data.detail.message) // "A tax has been calculated"
})  

// With JQuery
$('#payment-form').on('taxCalculated.Quaderno', function(data){
  alert(data.namespace + ": " + data.detail.message) // "Quaderno: A tax has been calculated" 
})

The  data argument is a javascript object that contains the following data:

{
  detail: {
    tax: 'the calculated tax rate',
    message: 'a string with the event message'
  }
}

Examples

Check out the following examples to learn how to use Quaderno.js in your project:

Still need help? Contact Us Contact Us