Recurly.js Reference

Note—View documentation for Recurly.js verions < v2.1 here

Setting Your Private Key

Before using any of the server side Recurly.js functions, you must set your private key.

Recurly_js::$privateKey = 'abcdef01234567890abcdef01234567890';

Recurly.js.private_key = 'abcdef01234567890abcdef01234567890'

recurly.js.PRIVATE_KEY = 'abcdef01234567890abcdef01234567890'

sign(parameters)

The sign function creates a signature string that includes an HMAC-SHA1 hash code, cryptographic nonce, timestamp, and serialized parameters.

In all languages, the sign function is designed to take a hash/array/dict of nested keys and values, corresponding to API objects. Alternatively, you can pass in actual Recurly API objects, i.e. Subscription, Account, etc.

$signature = Recurly_js::sign(
  array('transaction' => array('amount_in_cents' => 1999, 'currency' => 'USD'))
);

signature = Recurly.js.sign(
  :transaction => { :amount_in_cents => 19_99, :currency => 'USD' }
)

signature = recurly.js.sign({
    'transaction': {'amount_in_cents': 1999, 'currency': 'USD'
})

fetch(token)

The fetch function is used to retrieve the result of a Recurly.js transaction. It will return either a Subscription, BillingInfo, or Invoice object (actual type names vary with the language you are working in.)

$result = Recurly_js::fetch($_POST['recurly_token']);

result = Recurly.js.fetch params[:recurly_token]

result = recurly.js.fetch(params['recurly_token'])

Required Parameters

The following lists the API parameters that MUST be signed and included with your Recurly.js form.

New Subscriptions

subscription.plan_code

Billing Info Updates

account.account_code

One Time Transactions

transaction.amount_in_cents
transaction.currency

subscription Object

Applies to: new subscriptions

Attribute	Description
`plan_code`	Plan code for the subscription
`trial_ends_at`	If set, overrides the default trial behavior for the subscription. This must be a date and time, ISO 8601 formatted. The date must be in the future.
`starts_at`	If set, the subscription will begin in the future on this date. The subscription will apply the setup fee and trial period, unless the plan has no trial. This must be a date and time, ISO 8601 formatted.
`total_billing_cycles`	Renews the subscription for a specified number of cycles, then automatically cancels. Defaults to the subscription renewing indefinitely.
`first_renewal_date`	Indicates a date at which the first renewal should occur. Subsequent renewals will be offset from this date. The first invoice will be prorated appropriately so that the customer only pays for the portion of the first billing period for which the subscription applies.

account Object

Applies to: new subscriptions, billing info updates, one time transactions

Attribute	Description
`account_code`	A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .].
`username`	Username, ignore if you do not use usernames
`email`	Email address
`first_name`	First name
`last_name`	Last name
`company_name`	Company name

billing_info Object

Applies to: new subscriptions, billing info updates, one time transactions

Attribute	Description
`first_name`	First name
`last_name`	Last name
`address1`	Address line 1, recommended for address validation
`address2`	Address line 2
`city`	City
`state`	State
`country`	Country, 2-letter ISO code
`zip`	Zip or postal code, recommended for address validation
`phone`	Phone number
`vat_number`	Customer's VAT Number

transaction Object

Applies to: one time transactions

Attribute	Description
`amount_in_cents`	Amount of the transaction in cents
`currency`	3-letter currency code
`description`	Description of the transaction that will appear on invoice
`accounting_code`	Accounting code for related invoice line items, defaults to the plan_code

Recurly.config(options)

Initializes general options and company settings.

You must call this before any of the form building functions.

options

property	type	description
`subdomain`	String	Your company subdomain in Recurly.Required
`currency`	String	3-letter currency denomination, e.g. 'USD', 'GBP', 'EUR'. Required
`country`	String	Your country. This is used to determine VAT applicability, as well as default the country selection. Note: starting with version 2.1.3, this value is automatically set from your Recurly settings -- it does not need to be specified in your HTML.
`enableGeoIp`	Boolean	Whether you want Recurly.js to automatically determine the customer's location. enableGeoIp defaults to true.
`VATPercent`	Number	Percentage of total to charge for VAT. Note: starting with version 2.1.3, this value is automatically set from your Recurly settings -- it does not need to be specified in your HTML.
`locale`	Object	Override default human readable text. See details below.

options.locale

property	type	description
`errors`	Object	Error messages inserted on fields when they fail validation. Object properties: emptyField (String) default: 'Required field' invalidEmail (String) default: 'Invalid' invalidCC (String) default: 'Invalid' invalidCVV (String) default: 'Invalid' invalidCoupon (String) default: 'Invalid' missingFullAddress (String) default: 'Please enter your full address.' cardDeclined (String) default: 'Transaction declined' acceptTOS (String) default: 'Please accept the Terms of Service.' invalidQuantity (String) default: 'Invalid quantity'
`currency`	Object	The base display rules of all currencies. Object properties: format (String) A formatting string for converting amounts to text. Two variables, %u and %n are replaced with the currency-symbol and number respectively. e.g. "%u%n" precision (Number) Number precision delimiter (String) Floating pointer delimiter string. e.g. '.' separator (String) thousands separator string. e.g. ','

Example

Recurly.config({
    subdomain: 'mycompany'
  , currency: 'USD' // GBP | CAD | EUR, etc...
  , 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

property	type	Description
`target`	String	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. Required
`signature`	String	Signature for the request. Required
`planCode`	String	Plan code corresponding to a plan you've created. It will get pulled down from Recurly via the API. Required
`successURL`	String	After a successful subscription, the library will POST the signed results from Recurly to this URL.
`successHandler`	Function	Callback function of the form: fn(token) This function will be passed the result token of a successful subscription. Note: If using this parameter, you probably do not want to specify successURL.
`acceptedCards`	Array	Use this to control which credit card icons are displayed on the form. Default: ['american_express', 'discover', 'mastercard', 'visa']
`collectPhone`	Boolean	If true, will add a phone number field to Contact Info. Default: false
`collectCompany`	Boolean	If true, will add a company name field to Contact Info. Default: false
`enableAddOns`	Boolean	Shows available add-ons defined for the plan, allowing them to be toggled for the user to opt-in. Default: true
`enableCoupons`	Boolean	Displays the coupon redeemer box. Default: true
`addressRequirement`	String	Defines which address fields to display. Values: 'full' \| 'zipstreet' \| 'zip' \| 'none' Default: full
`distinguishContactFromBillingInfo`	Boolean	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. Default: false
`termsOfServiceURL`	String	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`	String	Same as `termsOfServiceURL`. If both are provided they are combined into a single acceptance with links to both.
`account`	Object	Used for pre-populating account details.
`billingInfo`	Object	Used for pre-populating billing information.
`subscription`	Object	Used for pre-populating subscription details.
`beforeInject`	Function	Callback function of the form: fn(formEl) Invoked before the form is injected into the target. Use this to enhance or adjust layout and behavior without having to patch the library directly. `formEl`—the DOM element of the built form. Note that it is not inserted into the document yet, and this can be invoked before the document is fully structured.
`afterInject`	Function	Callback function of the form: fn(formEl) Invoked 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. `formEl`—the DOM element of the built form.

Example

Recurly.buildSubscriptionForm({
  target: '#subscribe'
, planCode: 'myplancode'
, successURL: 'http://myserver.com/subscriptions/confirmation.php'
});

Recurly.buildBillingInfoUpdateForm(options)

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

options

property	type	Description
`target`	String	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. Required
`signature`	String	Signature for the request. Required
`accountCode`	String	The account code of the account being updated. Required
`successURL`	String	After a successful subscription, the library will POST the signed results from Recurly to this URL.
`successHandler`	Function	Callback function of the form: fn(token) This function will be passed the result token of a successful update. Note: If using this parameter, you probably do not want to specify successURL.
`acceptedCards`	Array	Use this to control which credit card icons are displayed on the form. Default: ['american_express', 'discover', 'mastercard', 'visa']
`addressRequirement`	String	Defines which address fields to display. Values: 'full' \| 'zipstreet' \| 'zip' \| 'none' Default: full
`distinguishContactFromBillingInfo`	Boolean	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. Default: true
`account`	Object	Used for pre-populating account details.
`billingInfo`	Object	Used for pre-populating billing information.
`beforeInject`	Function	Callback function of the form: fn(formEl) Invoked before the form is injected into the target. Use this to enhance or adjust layout and behavior without having to patch the library directly. `formEl`—the DOM element of the built form. Note that it is not inserted into the document yet, and this can be invoked before the document is fully structured.
`afterInject`	Function	Callback function of the form: fn(formEl) Invoked 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. `formEl`—the DOM element of the built form.

Recurly.buildTransactionForm(options)

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

options

property	type	Description
`target`	String	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. Required
`signature`	String	Signature for the request. Required
`successURL`	String	After a successful subscription, the library will POST the signed results from Recurly to this URL.
`successHandler`	Function	Callback function of the form: fn(token) This function will be passed the result token of a successful transaction. Note: If using this parameter, you probably do not want to specify successURL.
`acceptedCards`	Array	Use this to control which credit card icons are displayed on the form. Default: ['american_express', 'discover', 'mastercard', 'visa']
`collectContactInfo`	Boolean	If true, will collect first/last Name and e-mail for the account. Default: true
`collectPhone`	Boolean	If true, will add a phone number field to Contact Info. Default: false
`collectCompany`	Boolean	If true, will add a company name field to Contact Info. Default: false
`distinguishContactFromBillingInfo`	Boolean	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. Default: true
`termsOfServiceURL`	String	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`	String	Same as `termsOfServiceURL`. If both are provided they are combined into a single acceptance with links to both.
`account`	Object	Used for pre-populating account details.
`billingInfo`	Object	Used for pre-populating billing information.
`beforeInject`	Function	Callback function of the form: fn(formEl) Invoked before the form is injected into the target. Use this to enhance or adjust layout and behavior without having to patch the library directly. `formEl`—the DOM element of the built form. Note that it is not inserted into the document yet, and this can be invoked before the document is fully structured.
`afterInject`	Function	Callback function of the form: fn(formEl) Invoked 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. `formEl`—the DOM element of the built form.

Recurly.js Reference

Server Side Functions

Required Parameters

API Objects

Form Generation (Browser)

Setting Your Private Key

sign(parameters)

fetch(token)

Required Parameters

New Subscriptions

Billing Info Updates

One Time Transactions

subscription Object

account Object

billing_info Object

transaction Object

Recurly.config(options)

options

options.locale

Example

Recurly.buildSubscriptionForm(options)

options

Example

Recurly.buildBillingInfoUpdateForm(options)

options

Recurly.buildTransactionForm(options)

options