Transparent Post: Transactions

The Transaction Transparent Post API allows you to securely create one-time transactions from your website.

Required Protected Fields

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 and account URL for every transparent post request. The one-time transaction endpoint also requires an amount in cents attribute so Recurly knows how much to charge.
redirect_url
URL for redirection after the Transparent Post completes. This should be a fully qualified URL to your web site. It must include a hostname.
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.
transaction[amount_in_cents]
The amount in cents to charge. Multiply the dollar amount by 100, e.g. $9.99 would be 999.
transaction[currency]
Optionally specify the currency for the transaction amount. If not specified, your company's default currency will be used.
transaction[description]
Transaction description for the customer's invoice.

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
<form method="POST" 
      action="https://api.recurly.com/transparent/[subdomain]/transaction">
  <input type="hidden" name="data" value="[protected form data]" />
  <!-- Form here -->
  <input type="text" name="account[first_name]" placeholder="First name" />
</form>

Transaction HTML Form Fields

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

Account Fields (optional)

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]/transaction">
  <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>

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]/transaction

More Info

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