{"id":20290632,"url":"https://github.com/gocardless/gocardless-pro-ruby","last_synced_at":"2025-04-08T03:19:34.952Z","repository":{"id":744990,"uuid":"33177890","full_name":"gocardless/gocardless-pro-ruby","owner":"gocardless","description":"GoCardless Pro Ruby Client","archived":false,"fork":false,"pushed_at":"2025-04-04T09:31:28.000Z","size":1224,"stargazers_count":30,"open_issues_count":3,"forks_count":12,"subscribers_count":90,"default_branch":"master","last_synced_at":"2025-04-06T10:03:23.101Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gocardless.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-31T09:52:52.000Z","updated_at":"2025-04-04T08:56:10.000Z","dependencies_parsed_at":"2023-07-05T18:31:22.729Z","dependency_job_id":"b385d153-7d94-480f-a971-0755df482209","html_url":"https://github.com/gocardless/gocardless-pro-ruby","commit_stats":{"total_commits":381,"total_committers":12,"mean_commits":31.75,"dds":0.4776902887139107,"last_synced_commit":"caff045c0eead5b945008ff152cef856f18afdaf"},"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fgocardless-pro-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gocardless","download_url":"https://codeload.github.com/gocardless/gocardless-pro-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464160,"owners_count":20942965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T15:08:33.498Z","updated_at":"2025-04-08T03:19:34.926Z","avatar_url":"https://github.com/gocardless.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruby Client for the GoCardless API\n\nA Ruby client for the GoCardless API. For full details of the GoCardless API, see the [API docs](https://developer.gocardless.com/pro/).\n\n[![Gem Version](https://badge.fury.io/rb/gocardless_pro.svg)](http://badge.fury.io/rb/gocardless_pro)\n[![Build Status](https://travis-ci.org/gocardless/gocardless-pro-ruby.svg?branch=master)](https://travis-ci.org/gocardless/gocardless-pro-ruby)\n\n- [\"Getting started\" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=ruby) with copy and paste Ruby code samples\n- [API Reference](https://developer.gocardless.com/api-reference)\n\n## Usage Examples\n\nThis README will use `customers` throughout but each of the resources in the\n[API](https://developer.gocardless.com/api-reference/) is available in this library.\n\n### Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'gocardless_pro'\n```\n\nAnd then load it into your application:\n\n```ruby\nrequire 'gocardless_pro'\n```\n\n### Initialising the client\n\nThe client is initialised with an Access Token.\nYou can also pass in `environment` as `:sandbox` to make requests to the sandbox\nenvironment rather than production.\n\n```rb\n@client = GoCardlessPro::Client.new(\n  access_token: ENV[\"GOCARDLESS_TOKEN\"]\n)\n```\n\n### GET requests\n\nYou can get details about one or many resources in the API by calling the\n`#get`, `#list` and `#all` methods.\n\n#### Getting a single resource\n\nTo request a single resource, use the `#get` method:\n\n```rb\n@client.customers.get(customer_id)\n```\n\nA call to `get` returns an instance of the resource:\n\n```rb\np @client.customers.get(customer_id).given_name\n```\n\n#### Getting a list of resources\n\nTo get a list of resources, use the `#list` method:\n\n```rb\n@client.customers.list\n```\n\nA call to `list` returns an instance of `GoCardlessPro::ListResponse`. You can call `records` on this to iterate through results:\n\n```rb\n@client.customers.list.records.each do |customer|\n  p customer.given_name\nend\n```\n\nIf you need to pass any options, the last (or in the absence of URL params, the only) argument is an options hash. This is used to pass query parameters for `GET` requests:\n\n```rb\n@client.customers.list(params: { limit: 400 })\n```\n\n#### Getting all resources\n\nIf you want to get all of the records for a given resource type, you can use the\n`#all` method to get a lazily paginated list. `#all` will deal with making extra\nAPI requests to paginate through all the data for you:\n\n```rb\n@client.customers.all.each do |customer|\n  p customer.given_name\nend\n```\n\n#### Raw response details\n\nIn addition to providing details of the requested resource(s), all GET requests\ngive you access the following properties of the response:\n\n- `status`\n- `headers`\n- `body`\n\n### POST/PUT Requests\n\nFor POST and PUT requests you need to pass in the body in under the `params` key:\n\n```rb\n@client.customers.create(\n  params: {\n    given_name: \"Pete\",\n    family_name: \"Hamilton\",\n    email: \"pete@hamilton.enterprises\",\n    ...\n  }\n)\n```\n\nWhen creating a resource, the library will automatically include a randomly-generated\n[idempotency key](https://developer.gocardless.com/api-reference/#making-requests-idempotency-keys)\n- This means that if a request appears to fail but is in fact successful (for example due\nto a timeout), you will not end up creating multiple duplicates of the resource.\n- By default if a request results in an Idempotency Key conflict\n  the library will make a second request and return the object that was\n  originally created with the Idempotency Key. If you wish, you can instead configure\n  the client to raise the conflict for you to handle. e.g\n  ```rb\n  @client = GoCardlessPro::Client.new(\n    access_token: ENV[\"GOCARDLESS_TOKEN\"],\n    on_idempotency_conflict: :raise,\n  )\n  ```\n\nIf any parameters are required they come first:\n\n```rb\n@client.customers.update(customer_id, {...})\n```\n\n### Custom headers\n\nCustom headers can be provided for a POST request under the `headers` key.\n\nThe most common use of a custom header would be to set a custom [idempotency key](https://developer.gocardless.com/pro/#making-requests-idempotency-keys) when making a request:\n\n```rb\n@client.customers.create(\n  params: {\n    given_name: \"Pete\",\n    family_name: \"Hamilton\",\n    ...\n  },\n  headers: {\n    \"Idempotency-Key\" =\u003e \"1f9630a9-0487-418d-bd37-8b77793c9985\"\n  }\n)\n```\n\n### Handling failures\n\nWhen the API itself returns an error, the client will raise a corresponding exception. There are four classes of exception which could be thrown, all of which subclass `GoCardlessPro::Error`:\n\n- `GoCardlessPro::GoCardlessError`\n- `GoCardlessPro::InvalidApiUsageError`\n- `GoCardlessPro::InvalidStateError`\n- `GoCardlessPro::ValidationError`\n\nThese different types of error are fully documented in the [API documentation](https://developer.gocardless.com/api-reference/#overview-errors). Exceptions raised by the library have the following methods to provide access to information in the API response:\n\n- `#documentation_url`\n- `#message`\n- `#type`\n- `#code`\n- `#request_id`\n- `#errors`\n\nWhen the API returns an `invalid_state` error due to an `idempotent_creation_conflict`,\nthis library will attempt to retrieve the existing record which was created using the\nidempotency key, however you can also configure the library to raise an exception instead:\n\n```ruby\n@client = GoCardlessPro::Client.new(\n  on_idempotency_conflict: :raise\n)\n\nbegin\n  @client.payments.create(...)\nrescue GoCardlessPro::IdempotencyConflict =\u003e e\n  # do something useful\nend\n```\n\nIf the client is unable to connect to GoCardless, an appropriate exception will be raised, for example:\n\n* `Faraday::TimeoutError`, in case of a timeout\n* `Faraday::ConnectionFailed`, in case of a connection issue (e.g. problems with DNS resolution)\n* `GoCardlessPro::ApiError`, for `5xx` errors returned from our infrastructure, but not by the API itself\n\nIf an error occurs which is likely to be resolved with a retry (e.g. a timeout or connection error), and the request being made is idempotent, the library will automatically retry the request twice (i.e. it will make up to 3 attempts) before giving up and raising an exception.\n\n### Handling webhooks\n\nGoCardless supports webhooks, allowing you to receive real-time notifications when things happen in your account, so you can take automatic actions in response, for example:\n\n* When a customer cancels their mandate with the bank, suspend their club membership\n* When a payment fails due to lack of funds, mark their invoice as unpaid\n* When a customer’s subscription generates a new payment, log it in their “past payments” list\n\nThe client allows you to validate that a webhook you receive is genuinely from GoCardless, and to parse it into `GoCardlessPro::Resources::Event` objects which are easy to work with:\n\n```ruby\nclass WebhooksController \u003c ApplicationController\n  include ActionController::Live\n\n  protect_from_forgery except: :create\n\n  def create\n    # When you create a webhook endpoint, you can specify a secret. When GoCardless sends\n    # you a webhook, it'll sign the body using that secret. Since only you and GoCardless\n    # know the secret, you can check the signature and ensure that the webhook is truly\n    # from GoCardless.\n    #\n    # We recommend storing your webhook endpoint secret in an environment variable\n    # for security, but you could include it as a string directly in your code\n    webhook_endpoint_secret = ENV['GOCARDLESS_WEBHOOK_ENDPOINT_SECRET']\n\n    begin\n      # This example is for Rails. In a Rack app (e.g. Sinatra), access the POST body with\n      # `request.body.tap(\u0026:rewind).read` and the Webhook-Signature header with\n      # `request.env['HTTP_WEBHOOK_SIGNATURE']`.\n      events = GoCardlessPro::Webhook.parse(\n        request_body: request.raw_post,\n        signature_header: request.headers['Webhook-Signature'],\n        webhook_endpoint_secret: webhook_endpoint_secret\n      )\n\n      events.each do |event|\n        # You can access each event in the webhook.\n        puts event.id\n      end\n\n      render status: 200, nothing: true\n    rescue GoCardlessPro::Webhook::InvalidSignatureError\n      # The webhook doesn't appear to be genuinely from GoCardless, as the signature\n      # included in the `Webhook-Signature` header doesn't match one computed with your\n      # webhook endpoint secret and the body\n      render status: 498, nothing: true\n    end\n  end\nend\n```\n\nFor more details on working with webhooks, see our [\"Getting started\" guide](https://developer.gocardless.com/getting-started/api/introduction/?lang=ruby).\n\n### Using the OAuth API\n\nThe API includes [OAuth](https://developer.gocardless.com/pro/2015-07-06/#guides-oauth) functionality, which allows you to work with other users' GoCardless accounts. Once a user approves you, you can use the GoCardless API on their behalf and receive their webhooks.\n\nOAuth simply provides a means by which you obtain an access token - once you have this access token, you can use this gem as usual.\n\nWe recommend using the [oauth2](https://github.com/intridea/oauth2) gem to handle the authorisation process and gain a token. For an example of this in action, see our [open-source OAuth demo app](https://github.com/gocardless/oauth-demo/blob/master/app.rb#L46).\n\n## Supporting Ruby \u003c 2.0.0\nThe client only supports Ruby \u003e= 2.0.0 out of the box due to our use of\nEnumerable::Lazy for lazy loading of paginated API resources.\n\nIf you wish to use this gem with a previous ruby version, you should be able to\ndo so with the [backports](https://github.com/marcandre/backports) gem:\n\n1. Add backports to your Gemfile\n   ```gem 'backports'```\n2. Require lazy enumerables\n   ```require 'backports/2.0.0/enumerable/lazy.rb'```\n\n## Contributing\n\nThis client is auto-generated from Crank, a toolchain that we hope to open source soon. For now, issues should be reported on this repository. __Please do not modify the source code yourself, your changes will be overriden!__\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fgocardless-pro-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgocardless%2Fgocardless-pro-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fgocardless-pro-ruby/lists"}