Quaderno Checkout v2 reference (deprecated)

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	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: '[email protected]',
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).

mpociot/quaderno-checkout-v2.md