Documentation You are here: start » gateways » stripe


This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Previous revision
gateways:stripe [2020/01/09 16:49]
gateways:stripe [2020/10/06 09:22] (current)
adam [Migrating from previous Stripe integrations or other gateways to Stripe]
Line 1: Line 1:
 +---- dataentry gateway ----
 +type                   : gateway # do not change this line
 +name                   : Stripe
 +countries ​             : AU, AT, BE, CA, DK, FI, FR, DE, HK, IE, IT, JP, LU, NL, NZ, NO, PT, SG, ES, SE, CH, GB, US, BR, MX
 +support-added ​         : 2.0.0
 +support-removed ​       : 
 +auth-net-emulation ​    : ​ # no
 +supports-3dsecure ​     : yes # no
 +supports-multicurrency : yes # enter "​yes"​ or "​no"​ (without quotes)
 +gateway_url ​           : http://​​
 +====== Stripe ======
 +===== Setting Up Stripe for FoxyCart =====
 +  - Create your account [[https://​​register|here]].
 +  - Go to the [[https://​​admin.php?​ThisAction=EditPaymentGateway|Payment Settings]] page in the FoxyCart administration.
 +  - Once logged in, make sure your store is set to "Live Servers"​ \\ {{:​gateways:​stripe_-_foxycart_live_servers.png?​direct&​400|}}
 +  - Go to the //Accept payments using your Stripe account// option, check the box, and click the //Connect to Stripe// button.
 +  - Follow the instructions that appear.
 +  - 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.
 +<WRAP center round important 80%>
 +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.
 +==== 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''​. [[https://​​docs/​statement-descriptors#​dynamic|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.
 +  - 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: \\ {{ :​gateways:​stripe_legacy_foxy_admin.png?​400 |}}
 +    * Note that if you have multiple payment sets that you will be updating to Stripe, we recommend updating them one at a time.
 +  - Leave the "Let customers pay with a Credit or Debit Card" option enabled for now. We'll come back to it later.
 +  - Further down the page, look for the checkbox labelled "​Accept payments using your Stripe account"​. Enable this option.
 +  - 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.
 +  - Once redirected back to the checkout, you should see Stripe enabled, but leave the "show credit card form" unchecked for now.
 +  - <wrap hi>If you have subscriptions,​ or if you allow customers to save their credit cards during checkout,</​wrap>​ 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.
 +  - <wrap hi>If you don't have saved customers or subscriptions,​ or once our support team has confirmed the migration is complete…</​wrap>​
 +    - Make sure you're on the "​payments"​ page in the Foxy admin.
 +    - 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.
 +    - Check the "show credit card form" checkbox within the Stripe Connect options (towards the bottom of the page) to enable the new Stripe integration.
 +    - Save the page.
 +  - 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.)
 +  - OPTIONAL but RECOMMENDED:​ Login to your Stripe account, go to [[https://​​settings/​integration|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.
 +<WRAP center round important 90%>
 +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 [[https://​​FoxyCart/​2.0-templates/​blob/​master/​|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 [[https://​​questions/​which-currencies-does-stripe-support|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 [[https://​​rels/​attributes|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.
 +===== Testing =====
 +==== 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. <wrap help>​Know more? Feel free to edit this page with info.</​wrap>​
 +==== User Notes and Experiences =====
 +<wrap tip>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.</​wrap>​ We reserve the right to edit or remove comments that don't add value to this page.

Site Tools