Configure payment methods

FastSpring supports multiple strategies for influencing how payment methods appear during checkout. You can preselect one method, control display order, hide specific methods, or allow-list only the ones you want buyers to use.

The sections below explain each configuration strategy, show supported parameters, and help you understand which combinations are allowed. Select a section or use the TOC on the right to jump ahead.

Prerequisites

Before configuring payment methods, make sure you have:

• A FastSpring checkout (Popup or Embedded) configured in your store
• Familiarity with the FastSpring Store Builder Library (SBL)
• At least one payment method enabled and supported for your target region and currency

Note on checkout terminology: When discussing payment controls, we use Inline and Stacked checkout to describe layout display modes. Popup checkout always uses the Inline mode, while Embedded checkout can be configured for either Inline or Stacked display. Visit our Compare payment method layouts documentation to learn more.

How it works

Payment method behavior is controlled by four SBL parameters:

• paymentMethod preselects a method in the Inline checkout.
• paymentMethodOrder defines display order.
• hideOtherPaymentMethods shows only the specified methods (allow-list mode).
• hidePaymentMethods hides selected methods from checkout.

FastSpring applies these settings together based on the buyer’s region, your store configuration, and product eligibility. Inline checkout may preselect a method, but Stacked checkout never does.

Summary table

Use this table to quickly identify which parameters to use based on the checkout behavior you want.

Supported parameters

Use these parameters in your SBL configuration or secure payload to control how payment methods behave in checkout.

Valid payment method values

The table below lists the valid values for each supported payment method. Use these values in the paymentMethod and paymentMethodOrder fields, or as arguments to fastspring.builder.payment().

Configuration options

Below are common configuration options for controlling payment methods. Each option includes examples using both fastspring.builder.secure() and the payment directive where applicable.

Preselect one method and hide all others

Use this option when you want checkout to show only one payment method and prevent buyers from switching.

fastspring.builder.secure({
  "country": "DE",
  "language": "en",
  "items": [
    { "product": "virtuso-100-credits", "quantity": 2 }
  ],
  "paymentMethod": "paypal",
  "hideOtherPaymentMethods": true
});

Result: In this example, only PayPal appears at checkout. Buyers cannot select any other payment method.

Notes:

• Do not combine hideOtherPaymentMethods with hidePaymentMethods.
• The requested method must be eligible for the buyer’s region and currency.

Preselect one method and show other methods

Use this option when you want to recommend a method but still allow buyers to choose an alternative.

fastspring.builder.secure({
  "country": "DE",
  "language": "en",
  "items": [
    { "product": "virtuso-100-credits", "quantity": 2 }
  ],
  "paymentMethod": "paypal"
});

Result: In this example, PayPal is preselected, and other eligible payment methods remain visible and selectable.

Notes:

• Do not include hideOtherPaymentMethods or hidePaymentMethods.
• All other eligible methods remain available to the buyer.

Preselect one method and hide specific others

Use this option when you want to preselect a method but hide only specific alternatives.

fastspring.builder.secure({
  "country": "DE",
  "language": "en",
  "items": [
    { "product": "virtuso-100-credits", "quantity": 2 }
  ],
  "paymentMethod": "paypal",
  "hidePaymentMethods": ["sepa", "wire", "klarna", "card"]
});

Result: In this example, PayPal is preselected unless it appears in hidePaymentMethods. If the preselected method is hidden, checkout will not preselect a method, and all other eligible methods remain visible.

Notes:

• hidePaymentMethods accepts an array of method identifiers.
• Never use hidePaymentMethods with hideOtherPaymentMethods.

Compatibility matrix

Note: Some valid combinations may return a 201 informational response. See Priority override in the Error handling section.

Error handling

FastSpring validates your configuration before checkout loads. If your request contains conflicting or unsupported settings, FastSpring returns a 400 error. In some cases, FastSpring may return an informational 201 response.

Behavior by checkout display mode

Payment method behavior and parameter compatibility differ significantly across display modes.

Inline checkout

• User experience: Payment methods display horizontally at the top of the checkout form. All Popup checkouts use this display mode and is an option for Embedded checkouts.
• Behavior:
  • Can preselect using paymentMethod
  • paymentMethodOrder controls order and may preselect the first visible method
  • hideOtherPaymentMethods acts as an allow-list
  • hidePaymentMethods hides specific methods. If the preselected method is hidden, checkout does not preselect

Stacked checkout

• User experience: Payment methods are presented as a vertically stacked list (accordion). When a buyer selects a method, its form details expand within the accordion directly on the same screen. This mode is only available for Embedded checkouts.
• Behavior:
  • Never preselects a payment method
  • paymentMethodOrder reorders accordion methods only
  • Express methods maintain a fixed order
  • hideOtherPaymentMethods acts as an allow-list
  • hidePaymentMethods hides specific methods

Examples

Show only listed methods

Use this configuration when you want checkout to show only the methods you specify and hide everything else.

{
  "paymentMethodOrder": ["card", "paypal", "applepay"],
  "hideOtherPaymentMethods": true
}

Order methods and hide one

Use this configuration when you want a specific method order but need to remove one or more methods.

{
  "paymentMethodOrder": ["paypal", "amazonpay", "card"],
  "hidePaymentMethods": ["googlepay"]
}

Over-hide with fallback

This example shows how FastSpring falls back to the eligible set when too many methods are hidden without allow-list mode.

{
  "hidePaymentMethods": ["card", "paypal", "applepay", "googlepay"],
  "hideOtherPaymentMethods": false
}

FAQs