Checkout

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.

Demo

Try the demo below with this test card number:  4111 1111 1111 1111

Integration

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.

<form action="" method="POST">
<script
  src="https://checkout.quaderno.io/checkout.js" class="quaderno-button"
  data-type="charge"
  data-key="YOUR_QUADERNO_PUBLISHABLE_KEY"
  data-charge="JWT_WITH_THE_CHARGE_DATA"
  data-gateway="stripe"
  data-description="Purchase Description"
  data-label="Pay with Card"
  data-amount="1000"
  data-currency="EUR">
</script>
</form>

Response Parameters

These parameters will be submitted to your form’s action endpoint, along with any other  <input> fields in the form, once the transaction is complete.

Parameter Description
transactionDetails 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',
  original_charge: 'Original JWT (only for one-off charges)',
  iat: UNIX timestamp }

You can use this data to sync the transaction in your back-end.

Configuration Options

Option Mandatory Description
data-key Yes Your publishable key.
data-plan Only for subscriptions, except PayPal The ID of the plan your customer want to subscribe.
data-charge Only for one-off charges and PayPal subscriptions JWT with info about the charge. More info.
data-description Yes A description of the product or service being purchased.
data-amount Yes The amount (in cents) that’s shown to the user.
data-gateway Yes Specify the payment gateway you’re using ( stripebraintreepaymill, or paypal). The default is stripe
data-type No Specify the type of transaction ( subscription or charge). The default is subscription.
data-transaction-type No Specify the transaction type ( eserviceebook or standard). The default is eservice
data-currency No The currency of the amount (3-letter  ISO code). The default is USD.
data-quantity No The quantity you’d like to apply to the subscription you’re creating. The default is 1.
data-billing-address No The checkout form ask for the customer’s full billing address. The default is false.
data-country No Hide the VAT number field when the customer is based in this country (2-letter  ISO code). Usually set to the vendor’s country.
data-customer-type No Specify the type of customers you’re charging ( consumerbusiness or both). The default is both
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.
data-first-name No Your customer’s first name, to pre-filled the checkout form.
data-last-name No Your customer’s last name, to pre-filled the checkout form.
data-email No Your customer’s email address, to pre-filled the checkout form.
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.


One-Off Charge Info

If the transaction is a one-off charge, the  data-charge attribute can 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.
taxes String No Specify if the taxes are  included or excluded in the amount. The default is excluded
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 can 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)

Custom Integration

The custom integration (only supported for Stripe and Braintree) lets you create a custom button 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 handler. 

The  key and locale parameter must be passed to configure(). Any other options can be passed to either configure() or open().

<button id="customButton">Pay with card</button>

<script>
  var handler = QuadernoCheckout.configure({
    key: 'pk_test_LNpesCnUBN6Ax__xbmc4',
    locale: 'en',
    callback: function(data) {
      console.log(data.details);
    }
  });

  $('#customButton').on('click', function(e){
    // Open Checkout with further options
    handler.open({
      type: 'subscription',
      currency: 'eur',
      amount: 999,
      plan: "awesome",
      description: 'Subscribe to the Awesome plan',
      first_name: 'Orson',
      last_name: 'Scott',
      email: 'orson@yourdomain.com',
      quantity: 2
    });
    e.preventDefault();
  }); 
</script>

The parameters supported by the  open() method are the following:

Option Mandatory Description
plan Only for subscriptions, except PayPal The ID of the plan your customer want to subscribe.
charge Only for one-off charges and PayPal subscriptions JWT with info about the charge. More info.
description Yes A description of the product or service being purchased.
amount Yes The amount (in cents) that’s shown to the user.
gateway Yes Specify the payment gateway you’re using ( stripebraintreepaymill, or paypal). The default is stripe
type No Specify the type of transaction ( subscription or charge). The default is subscription.
transaction_type No Specify the transaction type ( eserviceebook or standard). The default is eservice.
currency No The currency of the amount (3-letter  ISO code). The default is USD.
quantity No The quantity you’d like to apply to the subscription you’re creating. The default is 1.
billing_address No The checkout form ask for the customer’s full billing address. The default is false.
country No Hide the VAT number field when the customer is based in this country (2-letter  ISO code). Usually set to the vendor’s country.
customer_type No Specify the type of customers you’re charging ( consumerbusiness or both). The default is both
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.
first_name No Your customer’s first name, to pre-filled the checkout form.
last_name No Your customer’s last name, to pre-filled the checkout form.
email No Your customer’s email address, to pre-filled the checkout form.
label No The text to be shown on the button the customer presses to show the checkout form.
color No The RGB color for the Checkout interface. The default is #4C7800.
coupon No Customers can enter a coupon code (only works for Stripe subscriptions). The default is  false.

Note: parameters' names are always snake_case.

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: message and details.

The  message should contain a brief description about the transaction (charge or subscription), 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).

Still need help? Contact Us Contact Us