Documentation You are here: start » gateways » stripe


Setting Up Stripe for FoxyCart

  1. Create your account here.
  2. Go to the Payment Settings page in the FoxyCart administration.
  3. Once logged in, make sure your store is set to “Live Servers”
  4. Go to the Accept payments using your Stripe account option, check the box, and click the Connect to Stripe button.
  5. Follow the instructions that appear.
  6. Once returned to the Foxy admin with Stripe successfully connected, enable the Show Credit Card form option​ if it isn't already and save the configuration. This option will show the credit card entry on the Foxy checkout. If you're already using an integration that shows a credit card input on the checkout, you'll need to disable that in order to show the Stripe credit card input.

Please note that when using the Stripe option, you won't be able to have a gateway enabled under the Let Customers Pay with a Credit or Debit Card option, since the Stripe option shows a credit card form within the checkout already, and only one is allowed on the checkout at a time. Don't worry though - customers will be able to pay with Credit and Debit cards through the Stripe payment fields.

Adding a custom statement descriptor suffix

As part of the configuration for Stripe in the Foxy admin, it's also possible to specify a statement descriptor suffix, which will be appended to the statement descriptor as set in your Stripe configuration which appears on your customers card statements.

This can be set using the optional “statement descriptor suffix” field within the Stripe settings on the “payment” section in the Foxy administration. The statement descriptor can be a maximum of 22 characters in length - which includes the descriptor already set on your Stripe account, and 2 additional characters of * . This means that if your statement descriptor was MYSTORE, you would have 13 characters for your suffix. If you set the statement descriptor suffix to CUSTOM-SUFFIX, the descriptor on the customers card statement would show as MYSTORE* CUSTOM-SUFFIX. See this page on Stripe's documentation for more details.

Migrating from previous Stripe integrations or other gateways to Stripe

If your store is currently making use of one of our older Stripe integrations, or another debit/credit card based payment gateway, you will need to update your store to switch over to the new Stripe integration. You can follow these steps to complete that.

  1. Log in to your store's Foxy administration and head to the payments page. If you're using an older Stripe integration or other card payment gateway, you will have the “Let customers pay with a Credit or Debit Card” option selected, with your current gateway set in the dropdown.
    • It'll look like this:
    • Note that if you have multiple payment sets that you will be updating to Stripe, we recommend updating them one at a time.
  2. Leave the “Let customers pay with a Credit or Debit Card” option enabled for now. We'll come back to it later.
  3. Further down the page, look for the checkbox labelled “Accept payments using your Stripe account”. Enable this option.
  4. Click the “Connect to Stripe” button within the option. This will redirect you to Stripe to sign in to your Stripe account and authenticate Foxy to interact with your account. After completing this, you will be redirected back to your Foxy administration.
  5. Once redirected back to the checkout, you should see Stripe enabled, but leave the “show credit card form” unchecked for now.
  6. If you have subscriptions, or if you allow customers to save their credit cards during checkout, click the “Request customer migration” button. This will send an email to our support team and we'll follow up when the migration has been completed. (This typically can be done within 1 business day.) Stop for now. You'll come back to finish the final step once you hear back from Foxy support that the migration is complete.
  7. If you don't have saved customers or subscriptions, or once our support team has confirmed the migration is complete…
    1. Make sure you're on the “payments” page in the Foxy admin.
    2. Uncheck the checkbox for “Let customers pay with a Credit or Debit Card” at the top of the page. This will disable the older Stripe integration.
    3. Check the “show credit card form” checkbox within the Stripe Connect options (towards the bottom of the page) to enable the new Stripe integration.
    4. Save the page.
  8. Load up your website and simulate a purchase. Make sure your checkout still shows a credit card form. If you'd like, run a test transaction (and then void/refund your order in Stripe). (Don't do this more than once, as testing on a live account should only be done sparingly.)
  9. OPTIONAL but RECOMMENDED: Login to your Stripe account, go to Settings -> Integration, and turn off Unsafe processing by disabling the “Handle card information directly” checkbox.

At this point, your store has been successfully updated to use our Stripe integration.

If you have set your checkout template to “Custom Template”, and embedded the raw template directly, or have embedded the payment_method Twig block, you will need to update your checkout template with some new code for Stripe. You can reference the current iteration of the checkout template on Github here.

Supported Countries

Stripe is continually expanding the countries that they support. The good news is, FoxyCart's existing Stripe integration should support any new countries that they do add support for. For a list of the countries that Stripe currently support, see this page on their site.

Overriding the Order ID

As of Foxy v2.0, the “Order ID” that Foxy passes to Stripe (which is normally the Foxy transaction ID) can be overridden. This is considered advanced functionality, and is only relevant for very specific use cases (such as complex fulfillment processes where multiple authorizations and captures may need to be grouped by the Order ID).

To override the default Foxy transaction ID, add an ''attribute'' via the API named fx_transaction_id_gateway_override, to the cart resource. The value of that attribute will be passed to Stripe as the Order ID.


Obtaining a Test Account

For configuring a test account with Stripe, you can simply complete the same process as detailed above, but leaving your payment servers set to “Test Servers”. When you click to connect to Stripe, on the following page will be an option at the top of the page to “Skip this step”, which will bring you back to Foxy with a test Stripe account connected and ready to use.

Test Card Numbers

You can use 4242424242424242 to simulate successful card validations in test mode (this number fails in production of course).

Technically, any card number that passes the Luhn Check will validate successfully in test mode – this includes real credit card numbers. You might not want to use real card numbers while testing though, to avoid accidentally checking them into your codebase.

The following are also true in test mode:

  • All 3 or 4 digit numbers pass as valid CVCs.
  • All future expiration dates are considered valid.

To simulate the 'Card Declined' error use this special card number - 4000000000000002.

Troubleshooting & Interpreting Response Codes

Contact stripe for info. Know more? Feel free to edit this page with info.

User Notes and Experiences

If you have tips, experience, or helpful notes related to this gateway that would benefit others, please add them below, including your name and the date. We reserve the right to edit or remove comments that don't add value to this page.

Site Tools