Quaderno Checkout v2 reference (deprecated)

quaderno-checkout-v2.md

Quaderno Checkout v2 reference (deprecated)

Demo

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

https://codepen.io/xxswingxx/pen/pqEObe

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	A  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 ( stripe, braintree, paymill, 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 ( eservice, ebook 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 ( consumer, business 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 ( 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)

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 ( 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)

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	A  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 ( stripe, braintree, paymill, 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 ( eservice, ebook 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 ( consumer, business 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).