{"id":23765807,"url":"https://github.com/solidusio-contrib/solidus_affirm_v2","last_synced_at":"2025-09-05T09:33:07.072Z","repository":{"id":47762614,"uuid":"258746487","full_name":"solidusio-contrib/solidus_affirm_v2","owner":"solidusio-contrib","description":"Solidus integration with Affirm financing payments using the new Transaction API ","archived":false,"fork":false,"pushed_at":"2022-08-02T04:02:27.000Z","size":80,"stargazers_count":0,"open_issues_count":1,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-20T14:33:01.882Z","etag":null,"topics":["hacktoberfest","payment","payment-gateway","solidus","solidus-extensions","solidus-gateway"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solidusio-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"open_collective":"solidus","github":"peterberkenbosch"}},"created_at":"2020-04-25T10:19:29.000Z","updated_at":"2022-08-02T04:02:31.000Z","dependencies_parsed_at":"2022-08-25T03:21:03.834Z","dependency_job_id":null,"html_url":"https://github.com/solidusio-contrib/solidus_affirm_v2","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/solidusio-contrib%2Fsolidus_affirm_v2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_affirm_v2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_affirm_v2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio-contrib%2Fsolidus_affirm_v2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solidusio-contrib","download_url":"https://codeload.github.com/solidusio-contrib/solidus_affirm_v2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232034914,"owners_count":18463363,"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":["hacktoberfest","payment","payment-gateway","solidus","solidus-extensions","solidus-gateway"],"created_at":"2024-12-31T23:17:54.600Z","updated_at":"2024-12-31T23:17:56.125Z","avatar_url":"https://github.com/solidusio-contrib.png","language":"Ruby","funding_links":["https://opencollective.com/solidus","https://github.com/sponsors/peterberkenbosch"],"categories":[],"sub_categories":[],"readme":"# SolidusAffirmV2\n\nPort and minor upgrade from [solidus_affirm](https://github.com/solidusio/solidus_affirm) using the [new Affirm Transaction API](https://docs.affirm.com/affirm-developers/changelog/transactions-api).\n\n\nThis extension uses the [Direct Connect API](https://docs.affirm.com/affirm-developers/docs/direct-connect-api) to integrate with Affirm.\n\n**The work done before October 1st 2020 is sponsored by the [Solidus Open Collective fund](https://opencollective.com/solidus)**\n\n[![CircleCI](https://circleci.com/gh/solidusio-contrib/solidus_affirm_v2.svg?style=shield)](https://circleci.com/gh/solidusio-contrib/solidus_affirm_v2)\n\n## Installation\n\nAdd solidus_affirm_v2 to your Gemfile:\n\n```ruby\ngem 'solidus_affirm_v2'\n```\n\nor use it directly from Github like this:\n\n```ruby\ngem 'solidus_affirm_v2', github: 'solidusio-contrib/solidus_affirm_v2'\n```\n\nBundle your dependencies and run the installation generator:\n\n```shell\nbundle\nbundle exec rails g solidus_affirm_v2:install\n```\n\n## Configuration\n\nTo generate the correct URL's in the JSON payload we need to specify the\n`default_url_options` for the Solidus engine. You can do that like this:\n\n```\nSpree::Core::Engine.routes.default_url_options = {\n  host: 'example.com'\n}\n```\n\nYou will need to get your public and private API keys from the Affirm Dashboard, see the [Affirm Documentation](https://docs.affirm.com/affirm-developers/docs/direct-connect-api).\n\nWhen you configure the payment gateway you need to provide those keys to\nthe payment gateway and also the link to the Affirm JS Runtime script.\n\nMake sure that during development and testing you use the sandbox version:\n* Sandbox = https://cdn1-sandbox.affirm.com/js/v2/affirm.js\n* Live = https://cdn1.affirm.com/js/v2/affirm.js\n\n### Configure via database configuration\n\nIf you want to store your Affirm credentials in the database just\nfill the new fields in the form, selecting `custom` (default) in the\nPreference Source field.\n\n### Configure via static configuration\n\nIf you want to store your credentials into your codebase or use ENV\nvariables you can create the following static configuration:\n\n```ruby\n# config/initializers/spree.rb\n\nSpree.config do |config|\n  # ...\n  config.static_model_preferences.add(\n    SolidusAffirmV2::PaymentMethod,\n    'affirm_env_credentials',\n    public_api_key: ENV['AFFIRM_PUBLIC_KEY'],\n    private_api_key: ENV['AFFIRM_PRIVATE_KEY'],\n    javascript_url: ENV['AFFIRM_JS_RUNTIME_URL'],\n    test_mode: !Rails.env.production?\n  )\nend\n```\n\nOnce your server has been restarted, you can select `affirm_env_credentials` in\nthe Preference Source field. After saving, your application will start using the\nstatic configuration to process Affirm payments.\n\n## Hooks and extension points\n\nWe provide a configuration class the allows you customize the complete setup.\n\nTo do so, you can use the `SolidusAffirmV2::Config` class in an initializer,\nlike `config/initializers/spree.rb` for example.\n\n### Callback controller\n\nWhen performing a checkout on Affirm, there are 2 callbacks that Affirm\ncould send to our system.\n\n1) a `POST` to the `confirm` action.\n2) a `GET` to the `cancel` action.\n\nTo change the controller that is handling those actions you can specify\nthe route name like this:\n\n```ruby\nSolidusAffirmV2::Config.callback_controller_name = 'my_custom_affirm'\n```\n\nSince the routes file here is within the `Spree` and `AffirmV2` namespace you will have to\nprovide the controller in that namespace. So with the above sample, `my_controller`,\nyou should define a controller like this:\n\n```ruby\nclass Spree::AffirmV2::MyCustomAffirmController \u003c Spree::StoreController\n  def confirm\n    #implement your own confirm action here.\n  end\n\n  def cancel\n    #implement your own cancel action here.\n  end\nend\n```\n\nNote that you could inherit from the provided controller as well if you\njust want to override one part. The default controller we have setup here\nis `Spree::AffirmV2::CallbackController`.\n\nIf you just need to change the way you like to handle the confirm and cancel\nactions, read below. We provide a hook for that as well.\n\n### Callback flow for confirming and canceling\n\nFor confirming or canceling an Affirm payment we provide sane defaults for\nthat in the `SolidusAffirmV2::CallbackHook::Base` class.\n\nThat class provides 3 methods that we use in the controller for:\n* setup the payment on the order correctly and use the checkout state_machine\n* the redirect url after the confirm action is done\n* the redirect url after the cancel action\n\nTo change that behaviour you can provide your own callback hook class like this:\n\n```ruby\nclass MyCallbackHook \u003c SolidusAffirmV2::CallbackHook::Base\n  def authorize!(payment)\n    #do your magic here.\n  end\n\n  def after_authorize_url(order)\n    'sample/endpoint/success'\n  end\n\n  def after_cancel_url(order)\n    'sample/endpoint/cancel'\n  end\nend\n```\n\nThen configure this class name in an initializer like this:\n\n```ruby\nSolidusAffirmV2::Config.callback_hook = MyCallbackHook\n```\n\n### Checkout payload serializer\n\nTo generate the JSON payload for the order that Affirm needs to setup the\npayment we provide a default serializer in `SolidusAffirmV2::CheckoutPayloadSerializer`.\n\nYou can change that by providing your custom serializer. If you just need to\noverride a few attributes you should inherit from `SolidusAffirmV2::CheckoutPayloadSerializer` and just provide the implementations of the attributes you would like to change. The untouched attributes will be inherited by default.\n\nFor example, to just override the shipping attribute you can do something like this:\n\n```ruby\nclass MyCustomPayloadSerializer \u003c SolidusAffirmV2::CheckoutPayloadSerializer\n  def shipping\n    MyCustomAddressSerializerImpl(object.ship_address)\n  end\nend\n```\n\nThen configure this new class to be the serializer:\n\n```ruby\nSolidusAffirmV2::Config.checkout_payload_serializer = MyCustomPayloadSerializer\n```\n\n## Testing\n\nFirst bundle your dependencies, then run `bin/rake`. `bin/rake` will default to building the dummy app if it does not exist, then it will run specs. The dummy app can be regenerated by using `bin/rake extension:test_app`.\n\n```shell\nbundle\nbin/rake\n```\n\nTo run [Rubocop](https://github.com/bbatsov/rubocop) static code analysis run\n\n```shell\nbundle exec rubocop\n```\n\nWhen testing your application's integration with this extension you may use its factories.\nSimply add this require statement to your spec_helper:\n\n```ruby\nrequire 'solidus_affirm_v2/factories'\n```\n\n## Sandbox app\n\nTo run this extension in a sandboxed Solidus application you can run `bin/sandbox`\nThe path for the sandbox app is `./sandbox` and `bin/rails` will forward any Rails command\nto `sandbox/bin/rails`.\n\nExample:\n\n```shell\n$ bin/rails server\n=\u003e Booting Puma\n=\u003e Rails 6.0.2.1 application starting in development\n* Listening on tcp://127.0.0.1:3000\nUse Ctrl-C to stop\n```\n\n## Releasing\n\nYour new extension version can be released using `gem-release` like this:\n\n```shell\nbundle exec gem bump -v VERSION --tag --push --remote upstream \u0026\u0026 gem release\n```\n\nCopyright (c) 2020 Peter Berkenbosch, released under the New BSD License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_affirm_v2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidusio-contrib%2Fsolidus_affirm_v2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio-contrib%2Fsolidus_affirm_v2/lists"}