{"id":13835586,"url":"https://github.com/solidusio/solidus_paypal_commerce_platform","last_synced_at":"2026-03-10T04:03:34.116Z","repository":{"id":38845055,"uuid":"262076694","full_name":"solidusio/solidus_paypal_commerce_platform","owner":"solidusio","description":"💳 Integrate Solidus with Paypal Commerce Platform","archived":false,"fork":false,"pushed_at":"2025-02-20T19:41:57.000Z","size":663,"stargazers_count":18,"open_issues_count":15,"forks_count":22,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-02-11T06:59:12.852Z","etag":null,"topics":["hacktoberfest","paypal","paypal-commerce-platform","solidus","solidus-extensions","solidusio"],"latest_commit_sha":null,"homepage":"https://developer.paypal.com/docs/platforms/","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.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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},"funding":{"open_collective":"solidus"}},"created_at":"2020-05-07T14:42:09.000Z","updated_at":"2025-02-20T19:42:00.000Z","dependencies_parsed_at":"2023-12-06T11:10:17.076Z","dependency_job_id":"40bd2652-ffed-4b5f-9492-2eab76da793e","html_url":"https://github.com/solidusio/solidus_paypal_commerce_platform","commit_stats":{"total_commits":311,"total_committers":16,"mean_commits":19.4375,"dds":0.5594855305466238,"last_synced_commit":"4c458620fdbcbbf4374d4c9ad41e46b8fff26997"},"previous_names":["nebulab/solidus_paypal_commerce_platform"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/solidusio/solidus_paypal_commerce_platform","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_paypal_commerce_platform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_paypal_commerce_platform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_paypal_commerce_platform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_paypal_commerce_platform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solidusio","download_url":"https://codeload.github.com/solidusio/solidus_paypal_commerce_platform/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solidusio%2Fsolidus_paypal_commerce_platform/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30324185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T01:36:58.598Z","status":"online","status_checked_at":"2026-03-10T02:00:06.579Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","paypal","paypal-commerce-platform","solidus","solidus-extensions","solidusio"],"created_at":"2024-08-04T14:01:05.847Z","updated_at":"2026-03-10T04:03:34.076Z","avatar_url":"https://github.com/solidusio.png","language":"Ruby","readme":"# Solidus Paypal Commerce Platform\n\n[![CircleCI](https://circleci.com/gh/solidusio/solidus_paypal_commerce_platform.svg?style=shield)](https://circleci.com/gh/solidusio/solidus_paypal_commerce_platform)\n[![codecov](https://codecov.io/gh/solidusio-contrib/solidus_paypal_commerce_platform/branch/main/graph/badge.svg?token=J8HCLE0CZW)](https://codecov.io/gh/solidusio-contrib/solidus_paypal_commerce_platform)\n\nThe official PayPal integration of Solidus.\n\n## Installation\n\nAdd solidus_paypal_commerce_platform to your Gemfile:\n\n```ruby\ngem 'solidus_paypal_commerce_platform'\n```\n\nBundle your dependencies and run the installation generator:\n\n```shell\nbundle install\nbin/rails generate solidus_paypal_commerce_platform:install\n```\n\n### Compatibility with solidus_frontend (deprecated)\n\nSupport for the old frontend is terminated but if you are using the\n`solidus_frontend` gem instead of Solidus Starter Frontend, you can\nstill use this gem for some time. Please, use `0.x` version.\n\n```ruby\ngem 'solidus_paypal_commerce_platform', '\u003c 1'\n```\n\nBundle your dependencies and run the installation generator:\n\n```shell\nbundle install\nbin/rails generate solidus_paypal_commerce_platform:install\n```\n\n### PayPal Sandbox/Live Environment\n\nThis extension will automatically select a PayPal environment based on Rails environment so that \"production\" will be mapped to the \"live\" PayPal environment, and everything else will be routed to the \"sandbox\" PayPal environment.\n\nIf you want to override these values you can either set `SolidusPaypalCommercePlatform.config.env` to `\"live\"` or `\"sandbox\"` inside an initializer. Or, alternatively, you can set the `PAYPAL_ENV` environment variable to one of the same two values.\n\n## Address Phone Number Validation\n\nSince PayPal is being used as the checkout if the user checks out on the product or cart page, and PayPal doesn't collect phone numbers, this extension disables phone number required validation for `Spree::Address`. To turn phone number validation back on, you'll need to either:\n\nA) Turn off cart and product page checkout - configurable on the admin payment method page for PayPal Commerce Platform.\n-OR-\nB) Collect the users phone number separately\n\nand then override the `Spree::Address` method `require_phone?` to return `true`.\n\n## Usage\n\n### I already have API credentials\n\nIf you already have API credentials, then you'll need to store them somewhere. You can do this directly in the\npreferences of the payment method, but we recommend storing your API credentials as an ENV variable and loading\nthem in as a preference on initialization.\n\n```ruby\n# config/initializers/spree.rb\nRails.application.config.to_prepare do\n  Spree::Config.configure do |config|\n    config.static_model_preferences.add(\n      SolidusPaypalCommercePlatform::PaymentMethod,\n      'paypal_commerce_platform_credentials', {\n        test_mode: !Rails.env.production?,\n        client_id: ENV['PAYPAL_CLIENT_ID'],\n        client_secret: ENV['PAYPAL_CLIENT_SECRET'],\n        display_on_product_page: true,\n        display_on_cart: true,\n        venmo_standalone: 'disabled'\n      }\n    )\n  end\nend\n```\n\nWith the payment method credentials statically configured, you can now go to the payment methods admin page and\ncreate a payment method for PayPal. Remember that you need to create the payment method first before you can set its\nPreference Source to `paypal_commerce_platform_credentials`.\n\n### I don't have API credentials\n\nIn this case, we still recommend following the above flow for security, but we have made a payment method setup\nwizard to make it easier to get started. On the payment methods admin page, you'll see a button to set up your\nPayPal Commerce Platform payment method. Click on this button and follow the instructions provided by PayPal.\nWhen you return to your app, your payment method should be set up and ready to go.\n\n## Usage in development environment\n\nWhen testing your PayPal integration, we recommend that you utilize the sandbox business and personal accounts that come\nwith your PayPal developer account. These sandbox accounts are designed to generate mock transactions for testing your\napp. You can learn more about sandbox accounts at https://developer.paypal.com/tools/sandbox.\n\nPlease take note of a gotcha when you're in development environment and you click on the \"Setup PayPal Commerce\nPlatform\" button in the payment methods admin page. Once PayPal asks you to connect to a business account, we recommend\nthat you log in with the sandbox business account that comes with your PayPal developer account. If you create a new\nsandbox business account here, the resulting account may not recognize your sandbox personal accounts, which can make\nit difficult to test a successful cart checkout.\n\n### Email Confirmation\n\nA confirmed email is required to get paid by PayPal. You'll need to check `Paypal Email Confirmed` on your new\npayment method before being able to select `Available To Users`.\n\n### Messaging Component\n\nPayPal offers a messaging component that displays credit messaging to the user. You can find more information [here.](https://www.paypal.com/us/webapps/mpp/on-site-messaging) This messaging is enabled by default on all pages that use the paypal payment buttons, but can be disabled via preferences. PayPal recommends that this messaging be displayed near product or order totals, so please keep that in mind during implementation.\n\n## Wizards\n\nThis gem adds support for payment method wizards to be set up. Payment wizards can be used to automatically set up\npayment methods by directing the user to a sign-in page for whatever service they're connecting. In this gem, the\nuser is directed to sign up/in for PayPal, and then give their app access to their credentials, which is store in\npreferences.\n\nTo add a payment wizard, add the class where your wizard is stored on initialization:\n\n```ruby\ninitializer \"register_solidus_paypal_commerce_platform_wizard\", after: \"spree.register.payment_methods\" do |app|\n  app.config.spree.payment_setup_wizards \u003c\u003c \"SolidusPaypalCommercePlatform::Wizard\"\nend\n```\n\nThe instances of your wizard class should respond to `#name` and `#partial_name`, where `partial_name` will return the path to the partial you'd like to display on the wizard setup section. In our case, we just display a button to direct the user to PayPal.\n\n## State Guesser\n\nPayPal users can change their shipping address directly on PayPal, which will\nupdate their address on Solidus as well. However, in some instances, Solidus\nuses the incorrect subregion level for states, which causes validation problems\nwith the addresses that PayPal sends to us.\n\nFor instance, if your user lives in Pescara, Italy, then PayPal will return\n\"Pescara\" as the state. However on older version of Solidus, the region\n\"Abruzzo\" is used, so the address will not be able to validate. To solve this\nissue, we've implemented a class that attempts to guess the state of the user\nusing Carmen subregions if the state cannot be initially found. You can, of\ncourse, implement your own state guesser and set it like this:\n\n```ruby\n# config/initializers/use_my_guesser.rb\nSolidusPaypalCommercePlatform.configure do |config|\n  config.state_guesser_class = \"MyApp::MyStateGuesser\"\nend\n```\n\n## Custom Checkout Steps\n\nWith product and cart page checkout, the user is directed to the checkout confirmation step when they return from PayPal. If you've removed the confirmation step, you'll need to override the `SolidusPaypalCommercePlatform.finalizeOrder` JavaScript method to instead complete the order.\n\n## Backend Payments\n\nPayPals API does not allow for admin-side payments. Instead, backend users taking payments for customers will need to use the PayPal Virtual Terminal to take payments. [More info is available on the PayPal website.](https://www.paypal.com/merchantapps/appcenter/acceptpayments/virtualterminal?locale.x=en_US)\n\n## Venmo\n\nVenmo is currently available to US merchants and buyers. There are also other [prequisites](https://developer.paypal.com/docs/business/checkout/pay-with-venmo/#eligibility).\n\nIf the transaction supports Venmo and it is enabled by the following, then a button should appear for it on checkout payment page. Note, Venmo cannot currently be rendered on the product or cart pages.\n\nSet the PaypalCommercePlatform `PaymentMethod` `venmo_standalone` preference to:\n- `render only standalone`, show Venmo on the payment page and do not show the other funding sources (i.e. PayPal, Credit); or\n- `enabled`, show Venmo on the payment page; or\n- `disabled` (default), do not show the Venmo button.\n\nSee more about preferences([Configuration](#configuration)) below.\n\n[_As Venmo is only available in the US, you may want to mock your location for testing_](#mocking-your-buyer-country)\n\n## Configuration\n\nThe easiest way to change the `Payment Method`'s preferences is through admin: `Settings \u003e Payments \u003e \"PayPal Commerce Platform\" \u003e Edit`.\n\nSee more about preferences [here](https://guides.solidus.io/developers/preferences/add-model-preferences.html#access-your-preferences)/\n\n## Development\n\n### Testing the extension\n\nFirst bundle your dependencies, then run `bin/rake`. `bin/rake` will default to building the dummy\napp if it does not exist, then it will run specs. The dummy app can be regenerated by using\n`bin/dummy-app`.\n\n```shell\nbin/setup\nbin/rake\n```\n\nTo run [Rubocop](https://github.com/bbatsov/rubocop) static code analysis run\n\n```shell\nbundle exec rubocop\n```\n\n### Running the sandbox\n\nTo run this extension in a sandboxed Solidus application, you can run `bin/sandbox`. The path for\nthe sandbox app is `./sandbox` and `bin/rails` will forward any Rails commands to\n`sandbox/bin/rails`.\n\nHere's an example:\n\n```\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### Mocking your buyer country\n\nPayPal normally looks at your IP geolocation to see where you are located to determine what funding sources are available to you. For example, Venmo is currently only available to US buyers.\nBecause of this, you may want to pretend you are from US check that that Venmo is correctly integrated for these customers. To do this, set the payment method's preference of `force_buyer_country` to \"US\". See more information about preferences above.\n\nThis preference has no effect on production.\n\n### Releasing new versions\n\nPlease refer to the [dedicated page](https://github.com/solidusio/solidus/wiki/How-to-release-extensions) in the Solidus wiki.\n\n## Referral Fee\n\nBy using this extension, you are giving back to Solidus. PayPal will pay a fee to the maintainers ([Nebulab](https://nebulab.it)) for each order made through the payment gateway.\n\n## License\n\nCopyright (c) 2022 Nebulab srls, released under the New BSD License\n","funding_links":["https://opencollective.com/solidus","https://developer.paypal.com/tools/sandbox","https://www.paypal.com/us/webapps/mpp/on-site-messaging","https://www.paypal.com/merchantapps/appcenter/acceptpayments/virtualterminal?locale.x=en_US","https://developer.paypal.com/docs/business/checkout/pay-with-venmo/"],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio%2Fsolidus_paypal_commerce_platform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolidusio%2Fsolidus_paypal_commerce_platform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolidusio%2Fsolidus_paypal_commerce_platform/lists"}