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.
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>
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 |
A JWT with info about the charge (only for one-off charges and PayPal subscriptions). More info below. |
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 ( eservice, ebook or standard). The default is eservice. |
data-gateway |
Specify the payment gateway you’re using ( stripe, braintree, or paypal). The default is stripe. |
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 ( eservice, ebook 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)
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 ( D, W, M, Y). 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)
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). |
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). |
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)
});
If you use the data-amount
form attribute and want to show live tax calculations, you can add the classes quaderno-subtotal
, quaderno-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>
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
}
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-quaderno
: company-name, country, postal-code, vat-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'
}
}
Check out the following examples to learn how to use Quaderno.js in your project: