--- schema_version: "1" id: 673df3dccb0adf02b68a36ea141176610b07c5c2a0b393014435dad2b911e4c6 title: Shopper Payments collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-payments.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments source_site: developer.salesforce.com content_type: documentation content_hash: 6701968ea9d22382a6207ff45884568910e519487576e51b3d31d60418ed6857 products: - B2C Commerce API - Salesforce APIs --- Shopper Payments # Shopper Payments [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-payments/shopper-payments-oas-v1-public.yaml) ## API Overview 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) ### 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) #### Error Handling Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html) ### Use Cases #### Get Payment Configuration Retrieve the available payment methods for a site. ```sh 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. ### Related APIs * [Shopper Baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) — Build baskets and add payment instruments. **Version:** 1.7.2 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-payments/v1` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints * Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints ## Operations ### GET Get payment configuration `GET /organizations/{organizationId}/payment-configuration` Operation ID: `getPaymentConfiguration`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). 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) #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `currency` (query, CurrencyCode, required) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. _Example: CurrencyCode_ ``` USD ``` * `countryCode` (query, CountryCode) The country code (ISO 3166-1 alpha-2) for country-specific payment configuration filtering. * `zoneId` (query, ZoneId) The zone identifier for the payment configuration. Optional, if specified will return zone specific payment configuration instead of resolving based on the currency and country. _Example: ZoneId_ ``` Amer-Zone ``` * `amount` (query, Amount) The transaction amount. Optional. Some gateways, such as Adyen, allow for payment methods to be qualified or disqualified based on the amount of the transaction. * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. * `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response. Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Payment configuration details. Media type: `application/json`. Schema: `PaymentConfiguration`. _Example: stripeConfiguration_ ``` { "zoneId": "Amer-Zone", "paymentMethodSetAccounts": [ { "accountId": "acct_1RegszI5I22eU0I3", "config": { "key": "pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV" }, "live": false, "vendor": "Stripe" } ], "paymentMethods": [ { "accountId": "acct_1RegszI5I22eU0I3", "paymentMethodType": "card", "paymentModes": [ "Multistep" ] } ] } ``` _Example: stripeAndPaypalConfiguration_ ``` { "zoneId": "Amer-Zone", "paymentMethodSetAccounts": [ { "accountId": "acct_1RegszI5I22eU0I3", "config": { "key": "pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV" }, "live": false, "vendor": "Stripe" }, { "accountId": "XK92PMVFNRBDG", "config": { "bnCode": "SalesforceCommerceCloud_PPCP", "key": "AYzMrnD7y4Zc5m5QJZTQ4zPKbP8TMn0r7aStK_3hM9gnaykL-VwK5tGQj4g1y93V6UNvC5j_FZSSa6xpR" }, "live": false, "vendor": "Paypal" } ], "paymentMethods": [ { "accountId": "acct_1RegszI5I22eU0I3", "paymentMethodType": "card", "paymentModes": [ "Multistep" ] }, { "accountId": "XK92PMVFNRBDG", "paymentMethodType": "paypal", "paymentModes": [ "Multistep" ] } ] } ``` _Example: adyenConfiguration_ ``` { "zoneId": "Amer-Zone", "paymentMethodSetAccounts": [ { "accountId": "TestAccount941ECOM", "config": { "country": "US", "key": "test_JE2ML2CMKZHJRL3QWUW4YCE32A3SL3BH", "paymentMethods": { "paymentMethods": [ { "brands": [ "amex", "cup", "diners", "discover", "mc", "visa" ], "name": "Cards", "type": "scheme" } ] } }, "live": false, "vendor": "Adyen" } ], "paymentMethods": [ { "accountId": "TestAccount941ECOM", "paymentMethodType": "card", "paymentModes": [ "Multistep" ] } ] } ``` _Example: noDataFound_ ``` { "zoneId": null, "paymentMethodSetAccounts": [], "paymentMethods": [] } ``` * **400** Possible reasons: * the site ID is required and must not be null. * the specified currency is invalid (must be ISO 4217) or not supported by the site. * the provided country code is invalid (must be 2 uppercase letters matching ISO 3166-1 alpha-2). * the provided zone ID is invalid (must match pattern \[a-zA-Z0-9-\_\]{1,100}). * the provided amount is invalid (must be non-negative). Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: BadRequest_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'." } ``` _Example: InvalidPaymentConfigurationRequest_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-payment-configuration-request", "title": "Bad Request", "detail": "The payment configuration request field 'countryCode' is invalid.", "invalidField": "countryCode" } ``` ### POST Check payment instrument balance `POST /organizations/{organizationId}/payment-instruments/balance` Operation ID: `getPaymentInstrumentBalance`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard). Checks the balance of a payment instrument. **Parameters:** * `siteId`: Required. Specifies the site identifier for context-specific configuration. **Request Body:** * `paymentMethodId`: Required. The payment method ID. * `provider`: Required. Identifies the payment provider that handles the balance inquiry. * `providerProperties`: Required. Provider-specific balance inquiry properties. Do not include PCI-relevant data, such as a primary account number (PAN), in this object. Use client-side tokenization or encrypted fields when payment-instrument data is required. **Response Behavior:** * Returns the balance amount and currency when the payment instrument is valid. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Request body (required) Media type: `application/json`. Schema: `PaymentInstrumentBalanceRequest`. _Example: PaymentInstrumentBalanceRequest_ ``` { "paymentMethodId": "COMMERCE_APP_GIFT_CARD", "provider": "givex", "providerProperties": { "balanceToken": "provider-issued-short-lived-token" } } ``` #### Responses * **200** Payment instrument balance retrieved successfully. Media type: `application/json`. Schema: `PaymentInstrumentBalanceResponse`. _Example: PaymentInstrumentBalance_ ``` { "amount": 50, "currency": "USD" } ``` * **400** Possible reasons: * the provided payment method is invalid or not applicable. * the provider-specific request properties are invalid or missing. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example BadRequest: same as GET /organizations/{organizationId}/payment-configuration 400 response._ _Example: InvalidPaymentInstrumentBalanceRequest_ ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The provided payment method is invalid or not applicable." } ``` ## Schemas ### OrganizationId An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### SiteId The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### CurrencyCode A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. Type: `string`. Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`. ### CountryCode A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard. Type: `string`. Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`. ### ZoneId The unique identifier for a Payments zone. Type: `string`. Minimum length: 1. Maximum length: 100. Example: `Amer-Zone`. ### Amount The transaction amount. Type: `number (double)`. Minimum: 0. Example: `100`. ### PaymentConfiguration * `zoneId` (_string_, nullable) The unique identifier for a Payments zone. Minimum length: 1. Maximum length: 100. Pattern: ^\[a-zA-Z0-9\\-\_\]{1,100}$. Example: `Amer-Zone`. * `paymentMethodSetAccounts` (_array of object_, required) List of payment method set accounts * `accountId` (_string_, required) Account identifier Minimum length: 1. Maximum length: 100. Example: `acct_1RegszI5I22eU0I3`. * `config` (_object_) Account configuration * `key` (_string_) API key for the payment processor Maximum length: 200. Example: `pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV`. * `bnCode` (_string_) Account BN code (optional, null if not a PayPal account) Maximum length: 100. Example: `Example_PPCP`. * `country` (_string_) The country associated with this payment account configuration Maximum length: 256. Example: `US`. * `paymentMethods` (_object_, nullable) Available payment methods from gateway (optional, null if not an Adyen account) * `live` (_boolean_, required) Whether the account is in live mode Example: `false`. * `vendor` (_string_, required) Payment vendor name Example: `Stripe`. * `paymentMethods` (_array of object_, required) Configured payment methods * `accountId` (_string_, required) Associated account identifier Minimum length: 1. Example: `acct_1RegszI5I22eU0I3`. * `paymentMethodType` (_string_, required) Type of payment method Example: `card`. * `paymentModes` (_array of string_, required) Supported payment modes Items: Example: `Multistep`. _Example_ ``` [ "Multistep" ] ``` ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### PaymentInstrumentBalanceRequest Request body for checking the balance of a payment instrument. The payment method ID and provider identify the payment provider. Provider-specific properties are defined and validated by that provider. * `paymentMethodId` (_string_, required) The payment method ID. Minimum length: 1. Maximum length: 256. Example: `COMMERCE_APP_GIFT_CARD`. * `provider` (_string_, required) Identifies the payment provider that handles the balance inquiry. Minimum length: 1. Maximum length: 256. Example: `givex`. * `providerProperties` (_object_, required) Provider-specific balance inquiry properties. Do not include PCI-relevant data, such as a primary account number (PAN), in this object. Use client-side tokenization or encrypted fields when payment-instrument data is required. ### PaymentInstrumentBalanceResponse Response containing the payment instrument balance information. * `amount` (_number_, required) The remaining balance on the payment instrument. Minimum: 0. Example: `50`. * `currency` (_object_, required) The three-letter currency code (ISO 4217) of the payment instrument balance. Includes all fields of `CurrencyCode`.