Stripe

Setting up Stripe

1. 1

   Create your Stripe account.

2. 2

   Go to the payment settings page in the legacy Foxy administration. Stripe can't be connected from the new admin yet.

3. 3

   Make sure your store is set to Live Servers.

4. 4

   Find the Accept payments using your Stripe account option, check the box, and click Connect to Stripe.

5. 5

   Follow the instructions that appear.

6. 6

   Once returned to the Foxy admin, you should see a confirmation that Stripe has been successfully connected.

Configuring Apple Pay and Google Pay

1. 1

   Go to your Stripe dashboard. Click the gear in the upper right, then click Payments in the Product Settings section.

2. 2

   Click the Payment Method Domains tab.

3. 3

   Add your Foxy store's checkout domain, such as example.foxycart.com or secure.example.tld. This should match where your /checkout is loaded from — contact Foxy support if you're not sure.

4. 4

   Go to the payments settings page in your Foxy admin, toggle express checkout, and save.

5. 5

   Test.

Adding a custom statement descriptor suffix

As part of the Stripe configuration in the Foxy admin you can specify a statement descriptor suffix, which is appended to the statement descriptor set in your Stripe configuration and appears on your customers' card statements.

Set it using the optional statement descriptor suffix field within the Stripe settings. The statement descriptor can be a maximum of 22 characters, which includes the descriptor already set on your Stripe account plus 2 additional characters for * . So if your statement descriptor is MYSTORE, you have 13 characters for your suffix. If you set the suffix to CUSTOM-SUFFIX, the descriptor on the customer's card statement shows as MYSTORE* CUSTOM-SUFFIX. See Stripe's documentation on statement descriptors for more details.

Migrating from previous Stripe integrations or other gateways to Stripe

If your store currently uses one of our older Stripe integrations, or another debit/credit card based payment gateway, you'll need to update your store to switch over to the new Stripe integration.

If you have multiple payment sets to update, we recommend updating them one at a time.

1. 1

   Log in to your store's Foxy administration and go to the payments page. If you're using an older Stripe integration or another card payment gateway, you'll have the Let customers pay with a Credit or Debit Card option selected with your current gateway in the dropdown. It'll look like this:

2. 2

   Leave Let customers pay with a Credit or Debit Card enabled for now. You'll come back to it.

3. 3

   Further down the page, find the checkbox labelled Accept payments using your Stripe account and enable it.

4. 4

   Click Connect to Stripe within that option. You'll be redirected to Stripe to sign in and authorise Foxy to interact with your account, then redirected back to your Foxy administration.

5. 5

   Once back, you should see Stripe enabled. Leave show credit card form unchecked for now.

6. 6

   If you have subscriptions, or if you allow customers to save their credit cards during checkout, click Request customer migration. This emails our support team and we'll follow up when the migration is complete, typically within 1 business day. Stop here until you hear back.

7. 7

   If you don't have saved customers or subscriptions, or once our support team confirms the migration is complete, continue:

   • Make sure you're on the payments page in the Foxy admin.

   • Uncheck Let customers pay with a Credit or Debit Card at the top of the page. This disables your previous credit card payment integration.

   • Check show credit card form within the Stripe Connect options, towards the bottom of the page, to enable the new Stripe integration.

   • Save the page.

8. 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 or refund the order in Stripe. Don't do this more than once — testing on a live account should be done sparingly.

9. 9

   Optional but recommended: log in 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.

Supported countries

Stripe is continually expanding the countries they support, and Foxy's Stripe integration should support any new countries they add. For a list of the countries Stripe currently support, see their documentation.

Overriding the order ID

As of Foxy v2.0, the Order ID that Foxy passes to Stripe — normally the Foxy transaction ID — can be overridden. This is advanced functionality and is only relevant for very specific use cases, such as complex fulfillment processes where multiple authorizations and captures need to be grouped by 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 is passed to Stripe as the Order ID.

Testing

Obtaining a test account

To configure a test account with Stripe, complete the same process described above but leave your payment servers set to Test Servers. When you click to connect to Stripe, the following page has an option at the top to Skip this step, which brings you back to Foxy with a test Stripe account connected and ready to use.

Test card numbers

Use 4242 4242 4242 4242 to simulate successful card validations in test mode. This number fails in production.

Technically any card number that passes the Luhn check will validate successfully in test mode, including real credit card numbers. You may not want to use real card numbers while testing, 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 4000 0000 0000 0002.

Troubleshooting & interpreting response codes

Contact Stripe for info.