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.

Accepting ACH Direct Debit

Stripe can accept ACH Direct Debit — payment straight from a US bank account — alongside cards on your Foxy checkout. This is separate from Foxy's dedicated ACH gateways, and it is configured entirely on Stripe's side.

Enabling it

1. 1

   In your Stripe Dashboard, open your payment method settings.

2. 2

   Enable ACH Direct Debit.

There is nothing to turn on in Foxy. Foxy asks Stripe which payment methods are available on every transaction, so once ACH is enabled in Stripe it appears at your Foxy checkout on its own.

Stripe's own requirements apply: a US Stripe account, USD as your presentment currency, a US customer, and a minimum charge of $0.50. Stripe may also review your account after you activate it. See Stripe's ACH Direct Debit documentation for the current requirements.

ACH is not instant, and Foxy will not update the status

An ACH debit takes roughly four business days to settle. Foxy records the transaction as pending at the moment of checkout, which is correct — nothing has been decided yet.

Foxy will not move it out of pending. Whether the debit settles or is returned is known only to Stripe, and Foxy does not receive that outcome. Reconcile ACH payments in your Stripe Dashboard, and read ACH payments overview before you go live — the reconciliation and fulfilment advice there applies here in full.

If your fulfilment integration filters transactions on a status of approved, it will skip ACH orders entirely.

Saved bank accounts

A customer who saves their bank account at checkout can be charged again later, and Foxy will not need to ask them to re-authorise it — Stripe stores the mandate and applies it at charge time.

One thing to be careful about: keep ACH Direct Debit enabled in Stripe for as long as any customer has a saved bank account. Foxy resolves the allowed payment methods against your Stripe settings on every charge, not just at checkout. If you disable ACH later, charges against already-saved bank accounts will start failing with a Stripe error.

For subscriptions, we recommend cards.

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.