Use the Shopper Payments API to:

Retrieve payment configuration information for storefronts when Salesforce Payments is enabled.

The API returns the available payment methods, merchant account details, and payment gateway configurations for a specific payment zone site assignment.

The response includes:

Zone ID: The unique identifier for the Payments zone.
Payment Method Set Accounts: List of configured payment processor accounts with API keys, vendor information (Stripe, Adyen, PayPal, etc.), and live/test mode indicators.
Payment Methods: List of available payment methods with their associated accounts, payment method types, and supported payment modes.

Authentication & Authorization

The client requesting payment configuration must have access to the /payment-configuration resource. The Shopper Payments API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

For details on how to request a shopper access token from SLAS, see the guest user flows for public clients and private clients in the SLAS guides.

You must include sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, or sfcc.shopper-standard in the client ID used to generate the SLAS token. For a full list of permissions, see the Authorization Scopes Catalog.

Response Details

Personalization

Responses from this API are not personalized via the Shopper Context API.

Caching

Responses from this API are not cached.

Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see Timeouts and Limits.

Error Handling

Error responses follow the RFC 7807 problem detail format. To trace errors, include a correlation-id header in your request — the response returns it as x-correlation-id. For details, see HTTP Status Codes and Errors.

Use Cases

Get Payment Configuration

Retrieve the available payment methods for a site.

curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-payments/v1/organizations/{organizationId}/payment-configuration?siteId=RefArch" \
-H "Authorization: Bearer {access_token}"

Retrieve Payment Configuration

Retrieve payment configuration settings for Stripe, PayPal, and Adyen based on the payment methods enabled in the merchant's payment zone site. This includes API keys, vendor details, and live/test mode status. Specify a zone via zoneId or use currency and countryCode for automatic resolution.

Shopper Baskets — Build baskets and add payment instruments.*

Simple example:

  import { ShopperPayments } from "commerce-sdk-isomorphic";

  const clientConfig = {
    parameters: {
      clientId: "XXXXXX",
      organizationId: "XXXX",
      shortCode: "XXX",
      siteId: "XX"
    }
  };
  const shopperPaymentsClient = new ShopperPayments(clientConfig);

API Version: 0.0.33
Last Updated:

Type parameters

ConfigParameters: ShopperPaymentsParameters & Record<string, unknown>

Hierarchy

ShopperPayments

Index

Constructors

constructor

Properties

Methods

Object literals

apiPaths

Constructors

constructor

new ShopperPayments(config: ClientConfigInit<ConfigParameters>): ShopperPayments

- Defined in src/lib/shopperPayments/apis/DefaultApi.ts:179
Parameters
- config: ClientConfigInit<ConfigParameters>
Returns ShopperPayments

Properties

clientConfig

clientConfig: ClientConfig<ConfigParameters> & { baseUri: string }

Static Readonly defaultBaseUri

defaultBaseUri: "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-payments/v1" = currentBaseUri

Static Readonly paramKeys

paramKeys: { getPaymentConfiguration: ["organizationId", "siteId", "currency", "countryCode", "zoneId", "amount", "personalized"]; getPaymentConfigurationRequired: ["organizationId", "siteId", "currency"]; getPaymentInstrumentBalance: ["organizationId", "siteId"]; getPaymentInstrumentBalanceRequired: ["organizationId", "siteId"] } = {getPaymentConfiguration: ['organizationId','siteId','currency','countryCode','zoneId','amount','personalized',],getPaymentConfigurationRequired: ['organizationId','siteId','currency',],getPaymentInstrumentBalance: ['organizationId','siteId',],getPaymentInstrumentBalanceRequired: ['organizationId','siteId',],} as const

Type declaration

getPaymentConfiguration: ["organizationId", "siteId", "currency", "countryCode", "zoneId", "amount", "personalized"]
getPaymentConfigurationRequired: ["organizationId", "siteId", "currency"]
getPaymentInstrumentBalance: ["organizationId", "siteId"]
getPaymentInstrumentBalanceRequired: ["organizationId", "siteId"]

Methods

getPaymentConfiguration

getPaymentConfiguration(options?: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ amount?: number | null; countryCode?: undefined | string; currency: string; organizationId: string; personalized?: GetPaymentConfigurationPersonalizedEnum; siteId: string; zoneId?: string | null } & QueryParameters, ConfigParameters> }>): Promise<PaymentConfiguration>
getPaymentConfiguration<T>(options?: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ amount?: number | null; countryCode?: undefined | string; currency: string; organizationId: string; personalized?: GetPaymentConfigurationPersonalizedEnum; siteId: string; zoneId?: string | null } & QueryParameters, ConfigParameters> }>, rawResponse?: T): Promise<T extends true ? Response : PaymentConfiguration>

- Defined in src/lib/shopperPayments/apis/DefaultApi.ts:247
Retrieves the payment configuration for the organization.

Parameters:*
- siteId: Required. The site identifier for context-specific configuration
- currency: Required. Three-letter currency code (ISO 4217) for payment method configuration
- countryCode: Optional. Two-letter country code (ISO 3166-1 alpha-2) for country-specific payment configuration
- amount: Optional. Transaction amount for payment method configuration
- zoneId: Optional. Payment zone identifier to retrieve zone-specific configuration
Response Behavior:*
- Returns payment configuration data when available
- Returns null values for missing data (e.g., when account not found or payments zone not found)
If you would like to get a raw Response object use the other getPaymentConfiguration function.
Parameters
- Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ amount?: number | null; countryCode?: undefined | string; currency: string; organizationId: string; personalized?: GetPaymentConfigurationPersonalizedEnum; siteId: string; zoneId?: string | null } & QueryParameters, ConfigParameters> }>
  
  An object containing the options for this method.
Returns Promise<PaymentConfiguration>

A promise of type PaymentConfiguration.
- Defined in src/lib/shopperPayments/apis/DefaultApi.ts:294
Retrieves the payment configuration for the organization.

Parameters:*
- siteId: Required. The site identifier for context-specific configuration
- currency: Required. Three-letter currency code (ISO 4217) for payment method configuration
- countryCode: Optional. Two-letter country code (ISO 3166-1 alpha-2) for country-specific payment configuration
- amount: Optional. Transaction amount for payment method configuration
- zoneId: Optional. Payment zone identifier to retrieve zone-specific configuration
Response Behavior:*
- Returns payment configuration data when available
- Returns null values for missing data (e.g., when account not found or payments zone not found)
Type parameters
- T: boolean
Parameters
- Optional options: RequireParametersUnlessAllAreOptional<{ headers?: undefined | {}; parameters?: CompositeParameters<{ amount?: number | null; countryCode?: undefined | string; currency: string; organizationId: string; personalized?: GetPaymentConfigurationPersonalizedEnum; siteId: string; zoneId?: string | null } & QueryParameters, ConfigParameters> }>
  
  An object containing the options for this method.
- Optional rawResponse: T
  
  Set to true to return entire Response object instead of DTO.
Returns Promise<T extends true ? Response : PaymentConfiguration>

A promise of type Response if rawResponse is true, a promise of type PaymentConfiguration otherwise.

getPaymentInstrumentBalance

getPaymentInstrumentBalance(options: RequireParametersUnlessAllAreOptional<{ body: PaymentInstrumentBalanceRequest & CustomRequestBody; headers?: undefined | {}; parameters?: CompositeParameters<{ organizationId: string; siteId: string } & QueryParameters, ConfigParameters> }>): Promise<PaymentInstrumentBalanceResponse>
getPaymentInstrumentBalance<T>(options: RequireParametersUnlessAllAreOptional<{ body: PaymentInstrumentBalanceRequest & CustomRequestBody; headers?: undefined | {}; parameters?: CompositeParameters<{ organizationId: string; siteId: string } & QueryParameters, ConfigParameters> }>, rawResponse?: T): Promise<T extends true ? Response : PaymentInstrumentBalanceResponse>

- Defined in src/lib/shopperPayments/apis/DefaultApi.ts:484
Checks the balance of a payment instrument. Currently supports gift card balance inquiries.

Parameters:*
- siteId: Required. Specifies the site identifier for context-specific configuration.
Request Body:*
- paymentMethodId: Required. The payment method ID, for example: GIFT_CERTIFICATE
- giftCard: Required when paymentMethodId is GIFT_CERTIFICATE. Specifies the gift card details.
- brand: The gift card type or brand, for example: givex, blackhawk
- cardNumber: The gift card number
- cvc: The card verification code
- expirationMonth: The expiration month
- expirationYear: The expiration year
Response Behavior:*
- Returns the balance amount and currency when the payment instrument is valid.
If you would like to get a raw Response object use the other getPaymentInstrumentBalance function.
Parameters
- options: RequireParametersUnlessAllAreOptional<{ body: PaymentInstrumentBalanceRequest & CustomRequestBody; headers?: undefined | {}; parameters?: CompositeParameters<{ organizationId: string; siteId: string } & QueryParameters, ConfigParameters> }>
  
  An object containing the options for this method.
Returns Promise<PaymentInstrumentBalanceResponse>

A promise of type PaymentInstrumentBalanceResponse.
- Defined in src/lib/shopperPayments/apis/DefaultApi.ts:523
Checks the balance of a payment instrument. Currently supports gift card balance inquiries.

Parameters:*
- siteId: Required. Specifies the site identifier for context-specific configuration.
Request Body:*
- paymentMethodId: Required. The payment method ID, for example: GIFT_CERTIFICATE
- giftCard: Required when paymentMethodId is GIFT_CERTIFICATE. Specifies the gift card details.
- brand: The gift card type or brand, for example: givex, blackhawk
- cardNumber: The gift card number
- cvc: The card verification code
- expirationMonth: The expiration month
- expirationYear: The expiration year
Response Behavior:*
- Returns the balance amount and currency when the payment instrument is valid.
Type parameters
- T: boolean
Parameters
- options: RequireParametersUnlessAllAreOptional<{ body: PaymentInstrumentBalanceRequest & CustomRequestBody; headers?: undefined | {}; parameters?: CompositeParameters<{ organizationId: string; siteId: string } & QueryParameters, ConfigParameters> }>
  
  An object containing the options for this method.
- Optional rawResponse: T
  
  Set to true to return entire Response object instead of DTO.
Returns Promise<T extends true ? Response : PaymentInstrumentBalanceResponse>

A promise of type Response if rawResponse is true, a promise of type PaymentInstrumentBalanceResponse otherwise.

Object literals

Static Readonly apiPaths

apiPaths: object

getPaymentConfiguration

getPaymentConfiguration: string = "/organizations/{organizationId}/payment-configuration"

getPaymentInstrumentBalance

getPaymentInstrumentBalance: string = "/organizations/{organizationId}/payment-instruments/balance"

Shopper Payments

API Overview

Authentication & Authorization

Response Details

Personalization

Caching

Timeouts

Error Handling

Use Cases

Get Payment Configuration

Retrieve Payment Configuration

Related APIs

Type parameters

ConfigParameters: ShopperPaymentsParameters & Record<string, unknown>

Hierarchy

Index

Constructors

Properties

Methods

Object literals

Constructors

constructor

Parameters

config: ClientConfigInit<ConfigParameters>

Returns ShopperPayments

Properties

clientConfig

Static Readonly defaultBaseUri

Static Readonly paramKeys

Type declaration

getPaymentConfiguration: ["organizationId", "siteId", "currency", "countryCode", "zoneId", "amount", "personalized"]

getPaymentConfigurationRequired: ["organizationId", "siteId", "currency"]

getPaymentInstrumentBalance: ["organizationId", "siteId"]

getPaymentInstrumentBalanceRequired: ["organizationId", "siteId"]

Methods

getPaymentConfiguration

Parameters

Returns Promise<PaymentConfiguration>

Type parameters

T: boolean

Parameters

Optional rawResponse: T

Returns Promise<T extends true ? Response : PaymentConfiguration>

getPaymentInstrumentBalance

Parameters

options: RequireParametersUnlessAllAreOptional<{ body: PaymentInstrumentBalanceRequest & CustomRequestBody; headers?: undefined | {}; parameters?: CompositeParameters<{ organizationId: string; siteId: string } & QueryParameters, ConfigParameters> }>

Returns Promise<PaymentInstrumentBalanceResponse>

Type parameters

T: boolean

Parameters

options: RequireParametersUnlessAllAreOptional<{ body: PaymentInstrumentBalanceRequest & CustomRequestBody; headers?: undefined | {}; parameters?: CompositeParameters<{ organizationId: string; siteId: string } & QueryParameters, ConfigParameters> }>

Optional rawResponse: T

Returns Promise<T extends true ? Response : PaymentInstrumentBalanceResponse>

Object literals

Static Readonly apiPaths

getPaymentConfiguration

getPaymentInstrumentBalance