Recurly.js Reference

View on GitHub or Download zip

After including jQuery and the recurly.js file in your HTML, the library will need to be initialized with the configuration for your company. Then, build the subscription form, transaction form, or update billing information form. The Recurly.js library includes the following methods:

Recurly.config(options)
Recurly.buildSubscriptionForm(options)
Recurly.buildBillingInfoUpdateForm(options)
Recurly.buildTransactionForm(options)

Please see the Recurly.js project for example implementations.

Functions

`Recurly.config(options)`

Initializes general options and company settings.

Options

subdomain

Your company subdomain in Recurly.

currency

3-letter currency denomination, e.g. 'USD', 'GBP', 'EUR'. Please note that Recurly.js only supports a single currency today.

country

Your country, this is used to determine VAT applicability, as well as default the country select.

VATPercent

Percentage of total to charge for VAT. See VAT.

locale

Override default human readable text. Nested objects get deep-merged into the default locale.

errors: Error messages inserted on fields when they fail validation

currency

The base display rules of all currencies.

format: A formatting string for converting number to text. Two variables, %u and %nare replaced with the currency-symbol and number respectively. e.g. "%u%s"
precision: Number precision
delimiter: Floating pointer delimiter string. e.g. '.'
separator: thousands separator string. e.g. ','

currencies

Attributes of individual currencies.The nested object property keys must be the ISO 4217:2001 alphanumeric code of the currency.

symbol: Currency symbol string. e.g. '$'

resultNamespace

When Recurly.js POST's the result params to successURL, enclose the result in this parent.The verify_* methods will fail to validate the signed result if any additional data in present. Some web frameworks and middleware will add params that aren't from the POST body and cause problems.

Example

Recurly.config({
    subdomain: 'mycompany'
  , currency: 'USD' // GBP | CAD | EUR, etc...
  , VATPercent: 10 // European Value Added Tax
  , country: 'GB' // Seller country, needed for VAT to work 
  , locale: {
      // Currency formatting rules
      currency:  {
        format: "%u%n" // Unit symbol and Number
      , separator: "."
      , delimiter: ","
      , precision: 2
    }
    // Error messages
    , errors: {
        emptyField: 'Forget something?'
      , invalidEmail: 'This doesn't look right.'
      , invalidCC: 'This doesn't look right.'
      , invalidCVV: 'This doesn't look right.'
      , invalidCoupon: 'Coupon not found.' 
    }
  }
});

`Recurly.buildSubscriptionForm(options)`

Creates a subscription form and injects it into a target element.

Options

target

A jQuery selector string for the target element to replace with the form. The entire contents of the target element is replaced, fascilitating the ability to put a loading indicator and/or a failover link to the plan's hosted payment page in the event of an error.

planCode

Plan code corresponding to a plan you've created. It will get pulled down via Recurly from the API.

accountCode

Explicitly sets the account code of the account when it's created.

successURL

After the subscription is created successfully, the library will POST the signed results from Recurly to this URL.

You must validate server-side with verify_subscription().

Result Params

signature
account_code
plan_code
quantity
add_ons

add_on_code
quantity

coupon_code

collectPhone

If true, will add a phone number field to Contact Info. Default false.

collectCompany

If true, will add a company name field to Contact Info. Default false.

enableAddOns

true / false, shows available add-ons defined for the plan, allowing them to be toggled for the user to opt-in.

enableCoupons

true / false, shows the coupon redeemer box.

addressRequirement

Which address fields to display, 'full', 'zipstreet', 'zip', or 'none' Defaults to 'full'

beforeInject(form)

Callback function envoked before the form is injected into the target. Use this to enhance or adjust layout and behavior without having to patch the library directly.

form: The DOM element of the built form. Note that it is not inserted into the document yet, and this can be envoked before the page document is fully structured.

afterInject(form)

Callback function envoked after the form has been injected into the target. Only use this if you need to make changes that depend on the enclosing document's presence.

form: The DOM element of the form.

distinguishContactFromBillingInfo

If true, will show first and last names under contact info, and billing info, allowing the customer to use a different person's credit card.

account

Predefine details about the existing or to-be account.

firstName
lastName
email
companyName

billingInfo

Predefine details about the existing or to-be billing info.

firstName
lastName
address1
address2
country
city
zip
state
vatNumber

termsOfServiceURL

If provided, Recurly.js will create a field that links to the URL and require the user click a checkbox accepting it before submitting.

privacyPolicyURL

Same as termsOfServiceURL. If both are provided they are combined into a single acceptance with links to both.

signature

A signature generated server-side by sign_subscription()

Example

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: 'confirmation' // POST on success URL
});

`Recurly.buildBillingInfoUpdateForm(options)`

Creates a billing info update form and injects it into a target element.

Options

target

accountCode

The account code of the account who's billing info is to be updated.

successURL

After the billing info is updated successfully, the library will POST the signed results from Recurly to this URL. You must validate server-side with verify_billing_info_update().

Result Params

signature
account_code

addressRequirement

Which address fields to display, 'full', 'zipstreet', 'zip', or 'none' Defaults to 'full'

distinguishContactFromBillingInfo

If false, will update the first and last name of the account along with billing info. Default true.

account

Predefine details about the existing or to-be account.

firstName
lastName
email
companyName

billingInfo

Predefine details about the existing or to-be billing info.

firstName
lastName
address1
address2
country
city
zip
state
vatNumber

signature

A signature generated server-side by sign_billing_info()

`Recurly.buildTransactionForm(options)`

Creates a one-time transaction form and injects it into a target element.

Options

target

accountCode

Explicitly sets the account code. If the account doesn't exist a new account will be created with the code.

amountInCents

Amount to charge the account in cents

successURL

After the transaction is processed successfully, the library will POST the signed results from Recurly to this URL.

Result Params

signature
account_code
amount_in_cents
currency
uuid

collectContactInfo

If true, will collect First/Last Name and Email for the account. This can be used as an alternative to accountCode, using the user-provided Email as the account code.If neither accountCode or collectContactInfo are provided, Recurly.js will raise a configuration exception.

collectPhone

If true, will add a phone number field to Contact Info. Default false.

collectCompany

If true, will add a company name field to Contact Info. Default false.

distinguishContactFromBillingInfo

If true, will show first and last names under contact info, and billing info, allowing the customer to use a different person's credit card.

account

Predefine details about the existing or to-be account.

firstName
lastName
email
companyName

billingInfo

Predefine details about the existing or to-be billing info.

firstName
lastName
address1
address2
country
city
zip
state
vatNumber

termsOfServiceURL

If provided, Recurly.js will create a field that links to the URL and require the user click a checkbox accepting it before submitting.

privacyPolicyURL

Same as termsOfServiceURL. If both are provided they are combined into a single acceptance with links to both.

signature

A signature generated server-side by sign_transaction()