{"id":20454958,"url":"https://github.com/undr/cloud_pay","last_synced_at":"2025-04-13T03:35:50.597Z","repository":{"id":136417633,"uuid":"324645698","full_name":"undr/cloud_pay","owner":"undr","description":"Simple and flexible CloudPayments API client. (https://developers.cloudpayments.ru/, https://developers.cloudpayments.ru/en/)","archived":false,"fork":false,"pushed_at":"2024-08-21T07:42:26.000Z","size":52,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-26T20:51:19.724Z","etag":null,"topics":["api-client","cloud-payments","cloudpayments"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/undr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-12-26T22:30:32.000Z","updated_at":"2024-09-12T15:08:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"0bd7c146-83d9-4207-a880-9cc326cf3ccf","html_url":"https://github.com/undr/cloud_pay","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undr%2Fcloud_pay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undr%2Fcloud_pay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undr%2Fcloud_pay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/undr%2Fcloud_pay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/undr","download_url":"https://codeload.github.com/undr/cloud_pay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248660030,"owners_count":21141228,"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":["api-client","cloud-payments","cloudpayments"],"created_at":"2024-11-15T11:17:29.902Z","updated_at":"2025-04-13T03:35:50.573Z","avatar_url":"https://github.com/undr.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CloudPay\n\nSimple and flexible CloudPayments API client. (https://developers.cloudpayments.ru/, https://developers.cloudpayments.ru/en/)\n\n## Difference from `cloud_payments` gem\n\nIt's a kind of fork of the `cloud_payments` gem. The main idea to build a simple and flexible client.\n\nSo what is the difference:\n\n`CloudPay`\n\n- has fewer dependencies. It depends on only the `faraday` gem.\n- doesn't contain value objects for responses. Now, it is the responsibility of an app to provide value objects for all responses.\n- has a flexible system of configuration.\n- provides an ability to send idempotent requests.\n- allows using of namespaces as standalone classes.\n- provides a unified interface for API methods.\n- has two ways to handle errors: with exceptions and result object.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'cloud_pay'\n```\n\nAnd then execute:\n\n```\n$ bundle install\n```\n\nOr install it yourself as:\n\n```\n$ gem install cloud_pay\n```\n\n## Usage\n\n### Configuration\n\nWe can have a few configuration presets. It's easy to define using the `CloudPay.configure` method. Example:\n\n```ruby\nCloudPay.configure do |c|\n  # default configuration preset\nend\n\nCloudPay.confugure(:preset_name) do |c|\n  # named configuration preset\nend\n```\n\nThen, we can select the needed config when we are creating a client:\n\n```ruby\nconfig = CloudPay::Config.new(host: '...')\n\nCloudPay.client # Client with default config\nCloudPay.client(:preset_name) # Client with predefined config\nCloudPay::Client.new\nCloudPay::Client.new(:preset_name)\n```\n\nAlso, we can configure the client using an instance of the `CloudPay::Config` class or hash.\n\n```ruby\nconfig = CloudPay::Config.new(host: '...')\n\nCloudPay.client(host: '...')\nCloudPay.client(config)\nCloudPay::Client.new(host: '...')\nCloudPay::Client.new(config)\n```\n\nThis way to resolve config is also applied to all API namespaces and webhooks handler.\n\n```ruby\n# Namespaces\nCloudPay::Payments::Tokens.new\nCloudPay::Payments::Tokens.new(:preset_name)\nCloudPay::Payments::Tokens.new(host: '...')\nCloudPay::Payments::Tokens.new(config)\n\n# Webhooks\nCloudPay::Webhooks.new\nCloudPay::Webhooks.new(:preset_name)\nCloudPay::Webhooks.new(host: '...')\nCloudPay::Webhooks.new(config)\n```\n\nIt's also possible to switch the default config for some block of code. It can be used in middlewares, for example.\n\n```ruby\nCloudPay.with_config(Rails.env.to_sym) do\n  CloudPay.client # Client with `:development`, `:test` or `:production` config\nend\n```\n\n```ruby\nclass CloudPayMiddleware\n  def call(env)\n    config = config_name(env)\n\n    CloudPay.with_config(config) do\n      @app.call(env)\n    end\n  end\n\n  private\n\n  def config_name(env)\n    # choose predefined config name according to some conditions\n  end\nend\n```\n\nThe example above allows switching configs according to some conditions: domain name, headers, or some other. So when we use `CloudPay::Client.new` in the app, it will use config defined in the middleware.\n\nIt's also possible to use a simple hash to initialize the client (or any namespace). Such a solution allows implementing multitenancy systems when the config is a part of application data and cannot be predefined in the config stage.\n\n```ruby\nCloudPay::Client.new(public_key: '...', secret_key: '...')\n```\n\n__Note:__ All undefined options will be inherit from default config when we use hash as a config. That means we can override some options ad-hoc:\n\n```ruby\nCloudPay::Client.new(\n  public_key: '...',\n  secret_key: '...'\n).config\n# #\u003cCloudPay::Config:0x00007f8fd1af04e8\n#  @connection_block=nil,\n#  @connection_options={},\n#  @host=\"https://api.cloudpayments.ru\",\n#  @log=false,\n#  @public_key=\"...\",\n#  @secret_key=\"...\"\u003e\n\nCloudPay.with_config(:test) do\n  CloudPay::Client.new(\n    public_key: '...',\n    secret_key: '...'\n  ).config\n# #\u003cCloudPay::Config:0x00007f8fd1af04e8\n#  @connection_block=nil,\n#  @connection_options={},\n#  @host=\"http://localhost:9292\",\n#  @log=false,\n#  @public_key=\"...\",\n#  @secret_key=\"...\"\u003e\nend\n```\n\n### Error Handling\n\nThere are two ways to handle errors in the gem: using the result object and using exceptions. We use exceptions when we call a method with an exclamation mark (`!`), and we use the result object otherwise.\n\nThe result object has a simple interface that consists of only three meaningful methods: `success?`, `model`, and `error_message`. Every API method returns this result object so that we can check the result of the request. Look at the example below:\n\n```ruby\nresult = CloudPay.client.payments.cards.charge(params)\n\nif result.success?\n  # do something with data using the `model` method.\n  # pp result.model\nelse\n  # Handle an error.\n  # You can use the `error_message` method to get a real error message or\n  # You can use the `model` method to get response data.\n  # pp result.model\n  # pp result.error_message\nend\n```\n\nUsing an exclamation mark forces the client to raise an exception in case of an unsuccessful response. The specific exception depends on the type of response.\n\n- It can be a `CloulPay::ValidationError` exception if the request has missing attributes.\n\n- It can be an exception inherited from `CloudPay::ServerError` in the `CloudPay::HttpErrors` namespace if an HTTP request is ended with any status code more than or equal to 300.\n\n- It can be an exception inherited from `CloudPay::ReasonedGatewayError` in `CloudPay::GatewayErrors` namespace if `ReasonCode` key in the `Model` object has some meaningful code.\n\n- it can be a `CloudPay::GatewayError` exception if the gem cannot determine a specific reason for an error.\n\nIt can also raise other exceptions that depend on the HTTP transport, such as faraday's errors or network errors.\n\n```ruby\nbegin\n  model = CloudPay.client.payments.cards.charge!(params, idempotency_key: idempotency_key)\n  # do something with data\nrescue CloudPay::ValidationError =\u003e e\n  # handle validation errors\nrescue *CloudPay.retryable_errors =\u003e e\n  # put in queue to retry later\nrescue CloudPay::Error =\u003e e\n  # handle the rest of errors\nend\n```\n\nThe gem provides a list of retryable errors. This list is needed to catch exceptions that can be the reason for retrying the request. We can redefine this list using the `CloudPay.set_retryable_errors` method.\n\n```ruby\nCloudPay.set_retryable_errors([\n  CloudPay::GatewayErrors::FormatError,\n  CloudPay::GatewayErrors::InsufficientFunds,\n  CloudPay::GatewayErrors::Timeout,\n  CloudPay::GatewayErrors::CannotReachNetwork,\n  CloudPay::GatewayErrors::SystemError,\n  Faraday::ConnectionFailed,\n  Faraday::TimeoutError\n])\n```\n\n__Note:__ Use the `idempotency_key` option if you intend to retry requests. It can lead to multiple write-offs of funds if you retry your request without the idempotency key.\n\n```ruby\nCloudPay.client.payments.cards.charge(params, idempotency_key: 'some-unique-id')\n```\n\nIt should be an unique value for every separate payment.\n\n### API methods\n\nThis gem supports the following API methods:\n\n- [Test method](https://developers.cloudpayments.ru/en/#test-method) - The method to test the interaction with the API and returns `true` or `false`.\n\n  ```ruby\n  CloudPay.client.test\n  ```\n\n- [Payment by a Cryptogram](https://developers.cloudpayments.ru/en/#payment-by-a-cryptogram) - The method to make a payment by a cryptogram generated by the Checkout script, Apple Pay, or Google Pay.\n\n  ```ruby\n  CloudPay.client.payments.cards.charge(params)\n  CloudPay.client.payments.cards.auth(params)\n  # or\n  ns = CloudPay::Payments::Cards.new\n  ns.charge(params)\n  ns.auth(params)\n  ```\n\n- [3-D Secure Processing](https://developers.cloudpayments.ru/en/#3-d-secure-processing) - The method to complete the payment when 3-D Secure authentication is used.\n\n  ```ruby\n  CloudPay.client.payments.cards.post3ds(params)\n  # or\n  ns = CloudPay::Payments::Cards.new\n  ns.post3ds(id, params)\n  ```\n\n- [Payment by a Token (Recurring)](https://developers.cloudpayments.ru/en/#payment-by-a-token-recurring) - The method to make a payment by a token received either with payment by cryptogram or via Pay notification.\n\n  ```ruby\n  CloudPay.client.payments.tokens.charge(params)\n  CloudPay.client.payments.tokens.auth(params)\n  # or\n  ns = CloudPay::Payments::Tokens.new\n  ns.charge(params)\n  ns.auth(params)\n  ```\n\n- [Payment Confirmation](https://developers.cloudpayments.ru/en/#payment-confirmation) - For payments made by the DMS scheme, you need to confirm a transaction. Confirmation can be done through the Back office or via calling this API method.\n\n  ```ruby\n  CloudPay.client.payments.confirm(params)\n  # or\n  ns = CloudPay::Payments.new\n  ns.confirm(params)\n  ```\n\n- [Payment Cancellation](https://developers.cloudpayments.ru/en/#payment-cancellation) - Cancellation of payment can be executed through your Back Office or by calling the API method.\n\n  ```ruby\n  CloudPay.client.payments.void(id)\n  # or\n  ns = CloudPay::Payments.new\n  ns.void(id)\n  ```\n\n  It has a `cancel` alias.\n\n  ```ruby\n  CloudPay.client.payments.cancel(id)\n  # or\n  ns = CloudPay::Payments.new\n  ns.cancel(id)\n  ```\n\n- [Refund](https://developers.cloudpayments.ru/en/#refund) - Refund can be executed through your Back Office or by calling the API method.\n\n  ```ruby\n  CloudPay.client.payments.refund(id, params)\n  # or\n  ns = CloudPay::Payments.new\n  ns.refund(id, params)\n  ```\n\n- [Payout by a Cryptogram](https://developers.cloudpayments.ru/en/#payout-by-a-cryptogram) - Payment by a cryptogram can be executed through the calling of this API method.\n\n  ```ruby\n  CloudPay.client.payments.cards.topup(params)\n  # or\n  ns = CloudPay::Payments::Cards.new\n  ns.topup(params)\n  ```\n\n- [Payout by a Token](https://developers.cloudpayments.ru/en/#payout-by-a-token) - Payout by a token can be executed through the calling of the following API method.\n\n  ```ruby\n  CloudPay.client.payments.tokens.topup(params)\n  # or\n  ns = CloudPay::Payments::Tokens.new\n  ns.topup(params)\n  ```\n\n- [Transaction Details](https://developers.cloudpayments.ru/en/#transaction-details) - The method returns a transaction details.\n\n  ```ruby\n  CloudPay.client.payments.get(id)\n  # or\n  ns = CloudPay::Payments.new\n  ns.get(id)\n  ```\n\n- [Payment Status Check](https://developers.cloudpayments.ru/en/#payment-status-check) - The method for payment searching, which returns its status.\n\n  ```ruby\n  CloudPay.client.payments.find(invoice_id)\n  # or\n  ns = CloudPay::Payments.new\n  ns.find(invoice_id)\n  ```\n\n  This method has two versions. It performs first version by default. However, you can specify the version as an `:version` option in the last argument:\n\n  ```ruby\n  CloudPay.client.payments.find(invoice_id, version: 2)\n  # or\n  ns = CloudPay::Payments.new\n  ns.find(invoice_id, version: 2)\n  ```\n\n- [Transaction List](https://developers.cloudpayments.ru/en/#transaction-list) - The method to get a list of transactions for a day.\n\n  ```ruby\n  CloudPay.client.payments.list(params)\n  # or\n  ns = CloudPay::Payments.new\n  ns.list(params)\n  ```\n\n- [Token List](https://developers.cloudpayments.ru/en/#token-list) - The method to get a list of all payment tokens of CloudPayments.\n\n  ```ruby\n  CloudPay.client.payments.tokens.list\n  # or\n  ns = CloudPay::Payments::Tokens.new\n  ns.list\n  ```\n\n- [Creation of Subscriptions on Recurrent Payments](https://developers.cloudpayments.ru/en/#creation-of-subscriptions-on-recurrent-payments) - The method to create subscriptions on recurrent payments.\n\n  ```ruby\n  CloudPay.client.subscriptions.create(params)\n  # or\n  ns = CloudPay::Subscriptions.new\n  ns.create(params)\n  ```\n\n- [Subscription Details](https://developers.cloudpayments.ru/en/#subscription-details) - The method to get an information about subscription status.\n\n  ```ruby\n  CloudPay.client.subscriptions.get(id)\n  # or\n  ns = CloudPay::Subscriptions.new\n  ns.get(id)\n  ```\n\n- [Subscriptions Search](https://developers.cloudpayments.ru/en/#subscriptions-search) - The method to get a list of subscriptions for a particular account.\n\n  ```ruby\n  CloudPay.client.subscriptions.find(account_id)\n  # or\n  ns = CloudPay::Subscriptions.new\n  ns.find(account_id)\n  ```\n\n- [Recurrent Payments Subscription Change](https://developers.cloudpayments.ru/en/#recurrent-payments-subscription-change) - The method to change a subscription on recurrent payments.\n\n  ```ruby\n  CloudPay.client.subscriptions.update(params)\n  # or\n  ns = CloudPay::Subscriptions.new\n  ns.update(params)\n  ```\n\n- [Subscription on Recurrent Payments Cancellation](https://developers.cloudpayments.ru/en/#subscription-on-recurrent-payments-cancellation) - The method to cancel subscription on recurrent payments.\n\n  ```ruby\n  CloudPay.client.subscriptions.cancel(id)\n  # or\n  ns = CloudPay::Subscriptions.new\n  ns.cancel(id)\n  ```\n\n- [Invoice Creation on Email](https://developers.cloudpayments.ru/en/#invoice-creation-on-email) - The method to generate a payment link and sending it to a payer's email.\n\n  ```ruby\n  CloudPay.client.orders.create(params)\n  # or\n  ns = CloudPay::Orders.new\n  ns.create(params)\n  ```\n\n- [Created Invoice Cancellation](https://developers.cloudpayments.ru/en/#created-invoice-cancellation) - The method to create invoice cancellation.\n\n  ```ruby\n  CloudPay.client.orders.cancel(id)\n  # or\n  ns = CloudPay::Orders.new\n  ns.cancel(id)\n  ```\n\n- [View of Notification Settings](https://developers.cloudpayments.ru/en/#view-of-notification-settings) - The method to view notification settings.\n\n  ```ruby\n  CloudPay.client.notifications.get(type)\n  # or\n  ns = CloudPay::Notifications.new\n  ns.get(type)\n  ```\n\n- [Change of Notification Settings](https://developers.cloudpayments.ru/en/#change-of-notification-settings) - The method to change notification settings.\n\n  ```ruby\n  CloudPay.client.notifications.update(type, params)\n  # or\n  ns = CloudPay::Notifications.new\n  ns.update(type, params)\n  ```\n\n- [Start of Apple Pay Session](https://developers.cloudpayments.ru/en/#start-of-apple-pay-session) - Start of a session is required to take payments via Apple Pay on Web.\n\n  ```ruby\n  CloudPay.client.apple_pay.start_session(params)\n  # or\n  ns = CloudPay::ApplePay.new\n  ns.start_session(params)\n  ```\n\n- [CloudKassir: Register Fiscalization](https://developers.cloudkassir.ru/en/#register-fiscalization) - The method of launching a cash register to the fiscal operation mode.\n\n  ```ruby\n  CloudPay.client.kassir.fiscalize(params)\n  # or\n  ns = CloudPay::Kassir.new\n  ns.fiscalize(params)\n  ```\n\n- [CloudKassir: Online Receipt Generation](https://developers.cloudkassir.ru/en/#online-receipt-generation) - Method of an online receipt generation.\n\n  ```ruby\n  CloudPay.client.kassir.receipt.create(params)\n  # or\n  ns = CloudPay::Kassir::Receipt.new\n  ns.create(params)\n  ```\n\n- [CloudKassir: Receipt Status Request](https://developers.cloudkassir.ru/en/#receipt-status-request) - Method of getting the receipt status.\n\n  ```ruby\n  CloudPay.client.kassir.receipt.status(id)\n  # or\n  ns = CloudPay::Kassir::Receipt.new\n  ns.status(id)\n  ```\n\n- [CloudKassir: Receipt Details Request](https://developers.cloudkassir.ru/en/#receipt-details-request) - Method of getting the receipt details.\n\n  ```ruby\n  CloudPay.client.kassir.receipt.get(id)\n  # or\n  ns = CloudPay::Kassir::Receipt.new\n  ns.get(id)\n  ```\n\n- [CloudKassir: Cash Register State Change](https://developers.cloudkassir.ru/en/#cash-register-state-change) - The method of manual control of the state of the cash register. The cash register can be turned off (for maintenance) and activated (put into operation).\n\n  ```ruby\n  CloudPay.client.kassir.state.update(params)\n  # or\n  ns = CloudPay::Kassir::State.new\n  ns.update(params)\n  ```\n\n- [CloudKassir: Receiving Cash Register Data](https://developers.cloudkassir.ru/en/#receiving-cash-register-data) - Method of receiving cash register data.\n\n  ```ruby\n  CloudPay.client.kassir.state.get(params)\n  # or\n  ns = CloudPay::Kassir::State.new\n  ns.get(params)\n  ```\n\n### Webhooks\n\n*- Coming soon -*\n\n## Development\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/undr/cloud_pay.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundr%2Fcloud_pay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fundr%2Fcloud_pay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fundr%2Fcloud_pay/lists"}