Transparent Post: Subscription

The Subscription Transparent Post API allows you to securely create new subscriptions from your web application.

Required Protected Fields

The Transparent Post API requires certain fields to be protected from tampering. The protected field is digitally signed using your private key to ensure that the user does not tamper with the value. At a minimum, you must include the redirect URL or account code for every transparent post request. You may include additional attributes to override the trial duration, unit amount, and quantity.

redirect_url
URL for redirection after the Transparent Post completes. This should be a URL on your web site.
account[account_code]
The account code is your site's unique identifier. This can be a unique, auto-incrementing id, GUID, username, or email -- anything on your site that uniquely identifies your user's account.
subscription[plan_code]
The plan code for the new subscription. This must be specified in the protected fields or in the HTML form.

Optional Protected Fields

subscription[unit_amount_in_cents]
Override the default unit amount in cents
subscription[trial_ends_at]
Set a custom trial end date
subscription[add_ons][x][unit_amount_in_cents]
Override the default unit amount of an add-on

Unit amounts and trial durations may be overridden when included as attributes in the protected fields list. These attributes may not be submitted by users.

Hidden HTML Field: Protected Data

The client library saves the protected fields to a hidden field in the HTML form. While the values of the hidden field may be visible to a user viewing the HTML source, the values are protected with a secure hash. The hidden field is hashed using your private key to ensure that the form was legitimately created on your site and the values have not been tampered with before submission.

HTML Example

1
2
3
4
5
6
7
8
<form method="POST"
    action="https://api.recurly.com/transparent/[subdomain]/subscription">
  <input type="hidden" name="data" value="[protected form data]" />
  <!-- Form here -->
  <input type="text" name="billing_info[first_name]" placeholder="First name" />
  <input type="text" name="billing_info[credit_card][number]"
    placeholder="Credit card number" />
</form>

Subscription HTML Form Fields

The following form fields may be submitted by your HTML form:

Subscription Fields

subscription[plan_code]
must be provided, protected or form field
subscription[coupon_code]
Optional coupon, must be empty or valid for the subscription to start
subscription[quantity]
Subscription quantity

Subscription Add-On Fields

subscription[add_ons][__x__][add_on_code]
subscription[add_ons][__x__][quantity]

Note: __x__ should increment, starting from `0`, to specify multiple add-ons.

Account Fields

account[username]
account[first_name]
account[last_name]
account[email]
account[company_name]

The account will be created upon a successful transaction if it does not already exist. These fields will update the account if it does exist.

Billing Information Fields

billing_info[first_name]
billing_info[last_name]
billing_info[address1]
billing_info[address2]
billing_info[city]
billing_info[state]
2-letter state/province code preferred
billing_info[zip]
Zip or postal code
billing_info[country]
2-letter country code strongly preferred
billing_info[phone]
billing_info[vat_number]
billing_info[credit_card][number]
billing_info[credit_card][verification_value]
3-4 digit security code (CVV)
billing_info[credit_card][year]
billing_info[credit_card][month]
billing_info[payment_method]
credit_card (default) or paypal for PayPal transactions (requires PayPal Referential Transactions)

HTML Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<form method="POST"
    action="https://api.recurly.com/transparent/[subdomain]/subscription">
  <input type="hidden" name="data" value="[protected form data]" />
  <!-- Form here -->
  <label for="billing_info[first_name]">First Name</label>
  <input type="text" name="billing_info[first_name]" placeholder="First name" />
  <!-- ... -->
  <label for="billing_info[credit_card][number]">Card Number</label>
  <input type="text" name="billing_info[credit_card][number]"
    placeholder="Card number" />
</form>

Specifying Add-Ons

You may optionally apply add-ons using the Transparent Post API. The `subscription[add_ons]` is treated as an array and should be indexed starting at 0. To specify the add-on, set the appropriate `add_on_code` using a hidden input. Then, set the appropriate `quantity` using an input field. If the `quantity` field is not specified, an empty string, or '0', the add-on will not be included.

You may also set the add_on_code and quantity using the protected variables of the Transparent Post.

Quantity Example

This example allows your users to specify a quantity for the Silver and Gold add-ons:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<p>Silver Add-On</p>
<input name="subscription[add_ons][0][add_on_code]" type="hidden"
  value="silver-addon" />
<label for="subscription[add_ons][0][quantity]">Quantity</label>
<input name="subscription[add_ons][0][quantity]" type="text" value="1" />

<p>Gold Add-On</p>
<input name="subscription[add_ons][1][add_on_code]" type="hidden"
  value="gold-addon" />
<label for="subscription[add_ons][1][quantity]">Quantity</label>
<input name="subscription[add_ons][1][quantity]" type="text" value="1" />

Checkbox Example

Or using a checkbox:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<input name="subscription[add_ons][0][add_on_code]" type="hidden"
  value="silver-addon" />
<!-- the "quantity" value of "1" is set only if the checkbox is checked -->
<input name="subscription[add_ons][0][quantity]" type="checkbox" value="1"
  checked="checked" />
<label for="subscription[add_ons][0][quantity]">Silver Add-On</label>

<input name="subscription[add_ons][1][add_on_code]" type="hidden"
  value="gold-addon" />
<input name="subscription[add_ons][1][quantity]" type="checkbox" value="1"
  checked="checked" />
<label for="subscription[add_ons][1][quantity]">Gold Add-On</label>

Endpoint URL

The client libraries handle the URL details automatically. If you are building your own transparent post implementation, use the endpoint below, substituting subdomain with your Recurly account's subdomain:

POSThttps://api.recurly.com/transparent/[subdomain]/subscription

More Info

Please see the Subscription API for more information. The behavior of the Subscriptions Transparent Post API closely mirrors the behavior of the Subscriptions API for creating a new subscription.