Submitting Your Gateway

At this point your gateway is coded and tested. Now it is time to submit it back to ActiveMerchant for inclusion in the project. Remember to remove any private test account credentials that you may have added during testing BEFORE you submit your work publicly.

Creating the Pull Request

Once you finish the development of your gateway you will need to submit a pull request to be reviewed for permanent addition to the project.

To do this you need to commit your work on a new branch (replacing my_new_gateway with your gateway name) and push it to your forked repository on GitHub:

$ git checkout -b add_my_new_gateway
$ git add [filename(s)]
$ git commit -m "MyNewGateway: generate new gateway"
$ git push origin add_my_new_gateway

While you are working on your gateway and prior to submitting your work for review, we encourage you to make multiple commits to your branch to keep your work organized and easily reviewable. The number of commits will always depend on the complexity of your changes, but a logical organization of commits for a new gateway might look something like:

MyNewGateway: generate new gateway; test successful purchase
MyNewGateway: add authorize, capture, and scrub actions, plus assoc. tests
MyNewGateway: add 3DS options, plus assoc. tests
MyNewGateway: add testing for different card types

Once you have finished building your gateway and you have pushed all of your changes to your forked repository, you will need to use GitHub to open a PR:

1. Login to your GitHub Account.
2. Navigate to your forked repository of ActiveMerchant.
3. Select your add_my_new_gateway branch from the branch dropdown.
4. Click on Pull Request.
5. On the Compare Changes page you should be able to see that you are comparing branches across forks. For the base repository you should select active_merchant/active_merchant and the base branch should be master. For head repository select YOUR-GITHUB-USERNAME/active_merchant and for the compare branch select your add_my_new_gateway branch.
6. Click on Create Pull Request.
7. You should be able to see the Pull Request you just opened with the official project at https://github.com/active_merchant/active_merchant/pulls

(More detailed instructions on how to use GitHub to create a PR from a fork, including screenshots, can be found here.)

Way to go! Your work is now submitted and awaiting review from ActiveMerchant’s maintainers.

Rebasing After Review

Once you have opened a PR according to the guidelines above, an ActiveMerchant maintainer will pull down your branch, run tests, review your changes, and ask you to make adjustments if necessary. When your PR has been approved, you will be asked to rebase your branch with master and squash your branch down to one commit. To rebase your branch, make sure that your local master branch is up to date:

git checkout master
git pull upstream master
git checkout add_my_new_gateway
git rebase upstream/master

Then run all of your tests again to make sure everything is still passing:

bundle exec rake test:local
ruby -Itest test/unit/gateways/my_new_gateway_test.rb
ruby -Itest test/remote/gateways/remote_my_new_gateway_test.rb

Finally, use an interactive rebase to squash all of your commits into one commit (if your branch only has one commit, this step is not necessary):

git rebase -i master

More detailed instructions on how to squash your commits (and about rebasing in general) can be found here.

Once you have completed the above steps, you should have a local branch that has been squashed down to one commit, is up-to-date with ActiveMerchant’s official repository, and has a green test suite. You can now push to the branch on your fork where you opened the PR:

git push origin add_my_new_gateway

Our maintainers will see that you have updated your submission, and once your work has received final approval we will merge it into the project. Thank you for your contribution!

Best Practices

ActiveMerchant recommends Ruby version 2.5.7 for your ActiveMerchant development environment.

Submission Checklist: before submitting your work, please verify that your submission meets the following requirements:

• Includes test/fixtures.yml if the gateway's test credentials are shareable (recommended)
• Includes unit tests that run without warnings, errors, or failures
• Includes remote tests that run without warnings, errors, or failures
• Remote tests cover all applicable transaction methods for the gateway (authorize, purchase, capture, void, verify, store, and scrub) AND validate critical response formats such as charge amounts
• Supports all the Ruby versions and ActiveSupport versions we have enabled in .github/workflows/ruby-ci.yml
• Uses Nokogiri for generating and parsing any XML
• Uses JSON in the Ruby standard library for generating and parsing any JSON
• Implements a scrub method which scrubs all sensitive fields, including PAN, CVV, and password/secret. Also returns true for supports_scrubbing?
• Does not introduce any new gem dependencies
• Does not update the CHANGELOG, or the ActiveMerchant::VERSION constant
• Does not contain any debug output or logic, or extraneous commented-out code

PR Submission Template

Once you’ve confirmed that your submission meets the above requirements, you can use the following template for your commit message before submitting your pull request:

# Short Summary: #####################


# ^^^ Line above intentionally left blank
# Full Description: ##########################


# Successful Test Summary

Short Summary should begin with the name of your new gateway and a brief summary of what’s included in the PR.

Full Description should include additional details of what’s included such as the different methods built out for your new gateway.

Successful Test Summary should include the results of running local, unit and remote tests.

Here’s an example of what that looks like filled out:

AwesomesauceGateway: Integration of new Awesomesauce Gateway

Integrate new AwesomesauceGateway with the following methods: authorize, verify, capture, refund, etc.

Test Summary
Local: 4650 tests, 73149 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
100% passed
Unit: 71 tests, 372 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
100% passed
Remote: 94 tests, 361 assertions, 0 failures, 0 errors, 0 pendings, 0 omissions, 0 notifications
100% passed