Permalink
Browse files

official public release

  • Loading branch information...
em committed Aug 22, 2011
1 parent f96f00c commit d82c3d9c8f3dc7b2a95ddbeba53505cb96553581
View
@@ -1,30 +1,34 @@
# Recurly.js
-Recurly.js makes it easy to provide the user experience available on our hosted payment pages, on your site, with complete control over the look and feel, outside of PCI scope.
+Recurly.js is an open-source Javascript library for creating great looking credit card forms to securely create subscriptions, one-time transactions, and update billing information using Recurly. The library is designed to create fully customizable order forms while minimizing your PCI compliance scope.
-*Currently depends on jQuery version 1.5.2 or higher.*
+### Dynamic Total Calculation and Error Handling
-# Why you should use it
-Don't reinvent the wheel. The fundamentals of paying for subscriptions doesn't change across implementations, there's got to be one approach that gets it right for everyone. We aim to be that solution. The one thing that does change, however, is design: your website has its own look, and we want you to keep it. This is why we created Recurly.js to handle all of the hard work, leaving you with the sole task of styling to fit your design. And with the help of [stylus](/LearnBoost/stylus), that couldn't be easier.
+The library performs client-side validation of cardholder data, immediate pricing calculations for add-ons and Value Added Tax (VAT), and coupon validation. The library handles transaction failures gracefully. Should a transaction be declined, the library automatically highlights the appropriate fields and displays proper error messages for your customers.
+### PCI Compliance
-# How it works
+Recurly.js simplifies PCI compliance for Recurly merchants. After performing client-side validation on the cardholder data, the library securely submits the order details directly to Recurly. Because the sensitive cardholder data is never transmitted to your web servers, your PCI compliance scope is dramatically reduced. This allows you to host the credit card order forms on your website without the headaches of PCI compliance.
-Recurly.js comes with:
+### Fully Customizable CSS
-1. A little script that:
- * Builds the DOM of a well-structured subscription form
- * Performs the same tricky client-side total calculations on our hosted pages. (quantities,addons,coupons,vat,etc..)
- * Does inline validation, and server-side validation.
- * Talks to Recurly (through a JSONP API), pulling down plan criteria, and creating subscriptions.
-
-2. A stock stylesheet that is also very similar to our hosted payment pages. It is coded in stylus, and comes with the css compilations.
- * Take this stylesheet and tweak it to your heart's content to match the look and feel of your design.
+Recurly.js is designed to be fully customized to fit within your website. To help get you started, this library includes a sample stylesheet that resembles Recurly's hosted payment pages. We use [stylus](https://github.com/LearnBoost/stylus) to create the CSS.
+__Learn more:__ View the Recurly.js [intro video and examples](http://js.recurly.com) and [documentation](http://docs.recurly.com/recurlyjs/overview).
+
+
+# In the Project
+
+Recurly.js includes:
+
+* A Javscript library (_recurly.js_) for creating well-structured forms with validation and error handling
+* A stock stylesheet (_recurly.css_)
+* [stylus](https://github.com/LearnBoost/stylus) source for customizing the stylesheet (_recurly.styl_)
+* And examples for creating subscriptions, one time transactions, and updating billing information
# Getting Started
-Accepting subscriptions is as simple as dropping in this js:
+Accepting subscriptions is as simple as dropping in this Javascript:
```javascript
Recurly.config({
@@ -35,10 +39,12 @@ Recurly.config({
Recurly.buildSubscriptionForm({
target: '#subscribe', // A jQuery selector for the container element to append the form to
planCode: 'myplancode' // A plan you have created in recurly-app
- successURL: '/success?account_code={account_code}' // Redirect on success URL
+ successURL: '/success' // Redirect on success URL
});
```
+View our [documentation](http://docs.recurly.com/recurlyjs/overview) for more details.
+
## Additional Options
```javascript
Recurly.config({
@@ -78,30 +84,28 @@ Recurly.buildSubscriptionForm({
```
## Customizing the style
+
A stock stylesheet is provided that is coded in [stylus](/LearnBoost/stylus), a wonderful language that compiles to CSS.
Stylus is officially implemented in node.js, but you don't need to have a node app to use it. You can install node and <code>npm install stylus</code>, then use the <code>stylus</code> command-line to compile to CSS. There is also a Ruby on Rails port of stylus, [stylus_rails](/lucasmazza/stylus_rails).
Alternatively, you could modify the compiled css and ignore the stylus source. But this is heavily discouraged. It's much easier to get accustom to stylus, than to attempt to work with the compiled CSS which has lost all of the original structure that stylus provides. Give it a try, it's worth it.
-The first thing you'll want to do is take a look at the variables defined at the top. You'll notice that the default stylesheets is all centered around defined grid system dimensions, making customization a breeze.
+The default stylesheet is designed around the grid system. You will notice the default grid variables at the top of _recurly.styl_.
# Responding to subscription creates
-Once the user subscribes through the recurly.js form on your site, you have to act accordingly with your respective business logic. (giving your users what it is they just paid for)
-The easiest way to do this is by simply passing a <code>successURL</code> option to buildSubscribeForm.
-When the user's credit card is processed successfully, recurly.js will redirect to successURL replacing <code>{account_code}</code> with the newly created account.
-
-All you have to do is have your server read the GET variable, pull down the account from Recurly with one of our client libraries, and act accordingly giving them what they paid for.
+Once the subscription is successfully started, Recurly.js will POST to `successURL`. The parameters are signed by Recurly for validation. Using the client library, you should validate the results and start the subscription. Alternatively, you may skip the validation and simply use the API to query the account's subscription status.
Alternatively, you can pass in an option to buildSubscribeForm, <code>afterSubscribe</code>, to handle subscription creates.
-# Caveats
-You will still need to use one of our existing server-side client libraries to pull down the account after it's been created, and act accordingly. But that's the easy part. The hard part in the past has been building out subscription UX and mediating errors.
+# Additional Requirements
+
+This library depends on jQuery 1.5.2+. A future version may be framework agnostic.
-It currently depends on jQuery 1.5.2+. Not a problem if you already use it. A future version of the library may be framework agnostic.
+You will need a Recurly client library in order to sign the protected fields for one-time transaction and billing info updates. Today, our [PHP](https://github.com/recurly/recurly-client-php) and [Ruby](https://github.com/recurly/recurly-client-ruby) clients have support for creating Recurly.js signatures. A client library is also necessary for performing other actions, such as retrieving account information, upgrading or downgrading a subscription, etc.
-# Soon To Come
+# Coming Soon
-* Multi-currency
-* Localization (english only right now)
+* Multi-currency (Supporting more than one currency per merchant)
+* Multi-lingual support (English only today)
View
@@ -26,6 +26,12 @@ p {
line-height: 26px;
text-align: justify;
}
+pre {
+ margin: 20px;
+ padding: 20px;
+ background: #000;
+ color: #fff;
+}
code {
font-family: menlo, monaco, "Lucida Console", monospace;
padding: 2px 4px;
@@ -40,7 +46,8 @@ a {
color: inherit;
font-weight: bold;
}
-#index {
+#index,
+#result {
width: 480px;
margin: 0 auto;
}
View
@@ -9,29 +9,19 @@
<script src="lib/jquery-1.6.1.js"></script>
<script src="../recurly.js"></script>
<script>
- $(function() {
- Recurly.config({
- environment: 'sandbox'
- , subdomain: 'recurlyjsdemo-test'
- , currency: 'GBP'
- , country: 'GB'
- , VATPercent: 10
- });
-
- Recurly.buildSubscriptionForm({
- target: '#recurly-subscribe'
- , planCode: 'complexplan'
- , addressRequirement: 'full'
- , successURL: 'confirmation.html?account_code={account_code}'
- });
+ Recurly.config({
+ environment: 'sandbox'
+ , subdomain: 'recurlyjsdemo-test'
+ , currency: 'USD'
+ , country: 'US'
+ , VATPercent: 10
+ });
- $('#test').click(function() {
- $('.first_name input').val('joe').change();
- $('.last_name input').val('user').change();
- $('.email input').val('joeuser@example.com').change();
- $('.card_number input').val('4111-1111-1111-1111').change();
- $('.cvv input').val('123').change();
- });
+ Recurly.buildSubscriptionForm({
+ target: '#recurly-subscribe'
+ , planCode: 'simpleplan'
+ , addressRequirement: 'full'
+ , successURL: 'confirmation.html?{*}'
});
</script>
@@ -74,7 +64,6 @@ <h1>
<div id="demo480">480px</div>
<div id="demo960">960px</div>
- <button id="test">test</button>
</div>
</div>
</div>
View
@@ -22,7 +22,7 @@ <h2>Examples</h2>
<p>The demo company defines two plans: <code>simpleplan</code>, and <code>complexplan</code>, and
a forever 30% off coupon, named <code>test</code>.</p>
- <p>Update Billing Info, and One-time Transactions both require <a href="vv">parameter signatures</a>, which must be generated server-side and rendered to an option. For demonstration purposes we pre&#8209;computed the signatures and hardcoded them in.</p>
+ <p>Update Billing Info, and One-time Transactions both require <a href="http://docs.recurly.com/recurlyjs/signatures/">signatures</a>, which must be generated server-side and rendered to an option. For demonstration purposes we pre&#8209;computed the signatures and hardcoded them in.</p>
</div>
</body>
</html>
@@ -12,23 +12,22 @@
Recurly.config({
environment: 'sandbox'
, subdomain: 'recurlyjsdemo-test'
- , baseURL: 'http://api-sandbox.lvh.me:3000/jsonp/emeryco-test/'
, currency: 'USD'
, country: 'US'
- , VATPercent: 10
});
Recurly.buildTransactionForm({
target: '#recurly-transaction'
- , accountCode: 'testaccount'
, amountInCents: 5000
- , successURL: 'confirmation.html?account_code={account_code}&signature={signature}'
- , signature: 'f37ecbd8556f936161d3b9a76cf9291ed46a3000-1312409907'
+ , successURL: 'confirmation.html?acc={account_code}'
+ , signature: '83634a130e340191abca714d7391da48ece7bfd2-0'
// Signature must be generated server-side with sign_transaction()
// Without it the request will be rejected.
+ //
+ // The example signature only works with recurlyjsdemo-test
//
// !!! IMPORTANT !!!
- // You must use verify_transaction() with the GET variables passed to successURL
+ // You must use verify_transaction() with the POST params passed to successURL
// http://docs.recurly.com/recurlyjs/signatures/
});
</script>
View
@@ -9,22 +9,20 @@
<script src="lib/jquery-1.6.1.js"></script>
<script src="../recurly.js"></script>
<script>
- $(function() {
- Recurly.config({
- environment: 'sandbox'
- , subdomain: 'recurlyjsdemo-test'
- , currency: 'GBP'
- , country: 'GB'
- , VATPercent: 10
- });
+ Recurly.config({
+ environment: 'sandbox'
+ , subdomain: 'recurlyjsdemo-test'
+ , currency: 'GBP'
+ , country: 'GB'
+ , VATPercent: 10
+ });
- Recurly.buildSubscriptionForm({
- target: '#recurly-subscribe'
- , planCode: 'simpleplan'
- , addressRequirement: 'zipstreet'
- , successURL: 'confirmation.html?account_code={account_code}'
- , distinguishContactFromBillingInfo: true
- });
+ Recurly.buildSubscriptionForm({
+ target: '#recurly-subscribe'
+ , planCode: 'simpleplan'
+ , addressRequirement: 'zipstreet'
+ , successURL: 'confirmation.html'
+ , distinguishContactFromBillingInfo: true
});
</script>
</head>
@@ -12,21 +12,22 @@
Recurly.config({
environment: 'sandbox'
, subdomain: 'recurlyjsdemo-test'
- /* , baseURL: 'http://api-sandbox.lvh.me:3000/jsonp/emeryco-test/' */
, currency: 'GBP'
, country: 'GB'
, VATPercent: 10
});
- Recurly.buildUpdateBillingInfoForm({
+ Recurly.buildBillingInfoUpdateForm({
target: '#recurly-update-billing-info'
, accountCode: 'testaccount'
- , successURL: 'confirmation.html?account_code={account_code}'
- , signature: '04e2f13f2db4f7cfc87d915eee94870fc3e15caa-1312409866'
+ , successURL: 'confirmation.html'
+ , signature: '1970639b53c29e9ed3f0a5c7574751caa1b30553-0'
// Signature must be generated server-side with a utility method provided in client libraries.
// e.g. Recurly::billing_info_signature(accountcode)
// It guarantees that you grant the end-user the right to update billing info for this account
// Without it the request will be rejected.
+ //
+ // The example signature only works for recurlyjsdemo-test
});
</script>
Oops, something went wrong.

0 comments on commit d82c3d9

Please sign in to comment.