{"_id":"55820361b806360d00244600","project":"555fbba928249c1900618a82","user":{"_id":"55648cf93b87582b003ab8b1","username":"","name":"Chris Bunting"},"initVersion":{"_id":"555fbba928249c1900618a85","version":"1.0"},"__v":0,"hidden":false,"createdAt":"2015-06-17T23:31:45.222Z","fullscreen":false,"htmlmode":false,"html":"","body":"The Recurly Ruby Client library is an open source library to interact with Recurly's subscription management from your Ruby application. The library interacts with Recurly's REST API.\n\nView the [GitHub project site](https://github.com/recurly/recurly-client-ruby) for a list of requirements and download/install instructions.\n\n* [Configuration](#configuration)\n* [Handling Dates](#handling-dates)\n* [Using the API](#using-the-api)\n* [Handling Errors](#handling-errors)\n* [Handle Webhooks](#handle-webhooks)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configuration\"\n}\n[/block]\nFirst, install the `recurly` gem and setup your [authentication credentials](https://dev.recurly.com/docs/getting-started):\n\n```\nrequire 'rubygems'\nrequire 'recurly'\n\nRecurly.subdomain      = 'YOUR-SUBDOMAIN'\nRecurly.api_key        = 'abcdef01234567890abcdef01234567890'\n\n# To set a default currency for your API requests:\nRecurly.default_currency = 'USD'\n```\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"All the examples will assume that you have properly set up your configuration.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Handling Dates\"\n}\n[/block]\nDates from Recurly are converted into [Date](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/date/rdoc/Date.html) objects, which gives your methods to compare or format dates using that Ruby class. Dates are returned in ISO 8601 format.\n\n```\nsubscription = Recurly::Subscription.find('1dd2129544f3e57ecf7d84467985eaf6')\nputs subscription.activated_at # => 2008-03-01T13:00:00Z\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the API\"\n}\n[/block]\nEach endpoint is documented with examples [here](https://dev.recurly.com/docs/getting-started).  Feel free to explore them for more information related to specific endpoints.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Handling Errors\"\n}\n[/block]\nWhen using the Ruby library, Recurly recommends proper exception handling.  Not handling exceptions properly could result in unexpected results or sudden termination of your code.  Below is a sample example in Ruby as how to properly catch exceptions thrown by the Recurly Ruby library.\n\n```\nbegin\n  #if account does not exist, a NotFound Error will be thrown\n  account = Recurly::Account.find '1'\n\n  #subscription will fail because a plan_code is not set\n  subscription = Recurly::Subscription.create!(:account => account)\nrescue Recurly::Resource::NotFound => e\n  puts e.message\nrescue Recurly::API::UnprocessableEntity => e\n  puts e.message\nelse\n  puts \"Successfully Created\"\nend\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Handle Webhooks\"\n}\n[/block]\nThere is a built in class to help handle [webhooks](https://docs.recurly.com/push-notifications). For a list of the different webhooks and their format, you can view the [documentation](https://recurly.readme.io/v2.0/page/webhooks).  This example is using [Sinatra](http://www.sinatrarb.com/).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This example is not meant to be put into production but rather to provide you with a starting point for your integration.\"\n}\n[/block]\n```\nrequire 'rubygems'\nrequire 'recurly'\nrequire 'sinatra'\n\nRecurly.subdomain      = 'YOUR-SUBDOMAIN'\nRecurly.api_key        = 'abcdef01234567890abcdef01234567890'\n\n# To set a default currency for your API requests:\nRecurly.default_currency = 'USD'\n\n# Expected example XML body\n#<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n#<successful_payment_notification>\n#  <account>\n#    ...\n#  </account>\n#  <transaction>\n#    ...\n#  </transaction>\n#</successful_payment_notification>\n\npost '/webhook' do\n  doc = Recurly::XML.new(request.body.string)\n  case doc.root.name\n  when \"successful_payment_notification\"\n    \"Successful Payment\"\n  when \"failed_payment_notification\"\n    \"Payment Failed\"\n  else\n    \"Unhandled Notification\"\n  end\nend\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Support\"\n}\n[/block]\nLooking for help? Please contact <support@recurly.com> or visit [support.recurly.com](https://support.recurly.com/).\n[Stackoverflow](http://stackoverflow.com/questions/tagged/recurly) is also a great place to talk to the community and find answers to common questions.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Announcements\"\n}\n[/block]\nFor the latest API and client library announcements follow Recurly on Twitter and join our Google Group:\n\n- [@recurly](https://twitter.com/recurly)\n- [Recurly Google Group](http://groups.google.com/group/recurly-api)","slug":"ruby","title":"Ruby"}

Ruby


The Recurly Ruby Client library is an open source library to interact with Recurly's subscription management from your Ruby application. The library interacts with Recurly's REST API. View the [GitHub project site](https://github.com/recurly/recurly-client-ruby) for a list of requirements and download/install instructions. * [Configuration](#configuration) * [Handling Dates](#handling-dates) * [Using the API](#using-the-api) * [Handling Errors](#handling-errors) * [Handle Webhooks](#handle-webhooks) [block:api-header] { "type": "basic", "title": "Configuration" } [/block] First, install the `recurly` gem and setup your [authentication credentials](https://dev.recurly.com/docs/getting-started): ``` require 'rubygems' require 'recurly' Recurly.subdomain = 'YOUR-SUBDOMAIN' Recurly.api_key = 'abcdef01234567890abcdef01234567890' # To set a default currency for your API requests: Recurly.default_currency = 'USD' ``` [block:callout] { "type": "info", "body": "All the examples will assume that you have properly set up your configuration." } [/block] [block:api-header] { "type": "basic", "title": "Handling Dates" } [/block] Dates from Recurly are converted into [Date](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/date/rdoc/Date.html) objects, which gives your methods to compare or format dates using that Ruby class. Dates are returned in ISO 8601 format. ``` subscription = Recurly::Subscription.find('1dd2129544f3e57ecf7d84467985eaf6') puts subscription.activated_at # => 2008-03-01T13:00:00Z ``` [block:api-header] { "type": "basic", "title": "Using the API" } [/block] Each endpoint is documented with examples [here](https://dev.recurly.com/docs/getting-started). Feel free to explore them for more information related to specific endpoints. [block:api-header] { "type": "basic", "title": "Handling Errors" } [/block] When using the Ruby library, Recurly recommends proper exception handling. Not handling exceptions properly could result in unexpected results or sudden termination of your code. Below is a sample example in Ruby as how to properly catch exceptions thrown by the Recurly Ruby library. ``` begin #if account does not exist, a NotFound Error will be thrown account = Recurly::Account.find '1' #subscription will fail because a plan_code is not set subscription = Recurly::Subscription.create!(:account => account) rescue Recurly::Resource::NotFound => e puts e.message rescue Recurly::API::UnprocessableEntity => e puts e.message else puts "Successfully Created" end ``` [block:api-header] { "type": "basic", "title": "Handle Webhooks" } [/block] There is a built in class to help handle [webhooks](https://docs.recurly.com/push-notifications). For a list of the different webhooks and their format, you can view the [documentation](https://recurly.readme.io/v2.0/page/webhooks). This example is using [Sinatra](http://www.sinatrarb.com/). [block:callout] { "type": "warning", "body": "This example is not meant to be put into production but rather to provide you with a starting point for your integration." } [/block] ``` require 'rubygems' require 'recurly' require 'sinatra' Recurly.subdomain = 'YOUR-SUBDOMAIN' Recurly.api_key = 'abcdef01234567890abcdef01234567890' # To set a default currency for your API requests: Recurly.default_currency = 'USD' # Expected example XML body #<?xml version="1.0" encoding="UTF-8"?> #<successful_payment_notification> # <account> # ... # </account> # <transaction> # ... # </transaction> #</successful_payment_notification> post '/webhook' do doc = Recurly::XML.new(request.body.string) case doc.root.name when "successful_payment_notification" "Successful Payment" when "failed_payment_notification" "Payment Failed" else "Unhandled Notification" end end ``` [block:api-header] { "type": "basic", "title": "Support" } [/block] Looking for help? Please contact <support@recurly.com> or visit [support.recurly.com](https://support.recurly.com/). [Stackoverflow](http://stackoverflow.com/questions/tagged/recurly) is also a great place to talk to the community and find answers to common questions. [block:api-header] { "type": "basic", "title": "Announcements" } [/block] For the latest API and client library announcements follow Recurly on Twitter and join our Google Group: - [@recurly](https://twitter.com/recurly) - [Recurly Google Group](http://groups.google.com/group/recurly-api)