@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

package/node_modules/@salesforce/b2c-api-schemas/scapi/checkout/shopper-payments/v1.json

@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Shopper Payments",
-    "version": "1.6.0",
+    "description": "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-payments/shopper-payments-oas-v1-public.yaml)\n\n# API Overview\n\nUse the Shopper Payments API to:\n\n- Retrieve payment configuration information for storefronts when Salesforce Payments is enabled.\n\nThe API returns the available payment methods, merchant account details, and payment gateway configurations for a specific payment zone site assignment.\n\nThe response includes:\n\n- Zone ID: The unique identifier for the Payments zone.\n- Payment Method Set Accounts: List of configured payment processor accounts with API keys, vendor information (Stripe, Adyen, PayPal, etc.), and live/test mode indicators.\n- Payment Methods: List of available payment methods with their associated accounts, payment method types, and supported payment modes.\n\n## Authentication & Authorization\n\nThe 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).\n\nFor 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.\n\nYou 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)\n\n## Response Details\n\n### Personalization\n\nResponses from this API are not personalized via the Shopper Context API.\n\n### Caching\n\nResponses from this API are not cached.\n\n### Timeouts\n\nShopper 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)\n\n### Error Handling\n\nError 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)\n\n## Use Cases\n\n### Get Payment Configuration\n\nRetrieve the available payment methods for a site.\n\n```sh\ncurl \"https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-payments/v1/organizations/{organizationId}/payment-configuration?siteId=RefArch\" \\\n  -H \"Authorization: Bearer {access_token}\"\n```\n\n\n### Retrieve Payment Configuration\n\nRetrieve 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.\n\n## Related APIs\n\n- [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",
     "x-api-type": "Shopper",
     "x-api-family": "Checkout"
   },
@@ -11,6 +12,7 @@
       "url": "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-payments/v1",
       "variables": {
         "shortCode": {
+          "description": "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)",
           "default": "shortCode"
         }
       }
@@ -19,41 +21,58 @@
   "paths": {
     "/organizations/{organizationId}/payment-configuration": {
       "get": {
+        "summary": "Get payment configuration",
+        "description": "Retrieves the payment configuration for the organization.\n\n**Parameters:**\n- `siteId`: Required. The site identifier for context-specific configuration\n- `currency`: Required. Three-letter currency code (ISO 4217) for payment method configuration\n- `countryCode`: Optional. Two-letter country code (ISO 3166-1 alpha-2) for country-specific payment configuration\n- `amount`: Optional. Transaction amount for payment method configuration\n- `zoneId`: Optional. Payment zone identifier to retrieve zone-specific configuration\n\n**Response Behavior:**\n- Returns payment configuration data when available\n- Returns null values for missing data (e.g., when account not found or payments zone not found)",
         "operationId": "getPaymentConfiguration",
         "parameters": [
           {
             "name": "organizationId",
             "in": "path",
+            "description": "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).",
             "required": true,
             "style": "simple",
             "explode": false,
             "schema": {
               "$ref": "#/components/schemas/OrganizationId"
-            }
+            },
+            "example": "f_ecom_zzxy_prd"
           },
           {
             "name": "siteId",
             "in": "query",
+            "description": "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.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "examples": {
+              "SiteId": {
+                "value": "RefArch"
+              }
             }
           },
           {
             "name": "currency",
             "in": "query",
+            "description": "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.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/CurrencyCode"
+            },
+            "examples": {
+              "CurrencyCode": {
+                "value": "USD"
+              }
             }
           },
           {
             "name": "countryCode",
             "in": "query",
+            "description": "The country code (ISO 3166-1 alpha-2) for country-specific payment configuration filtering.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -64,16 +83,23 @@
           {
             "name": "zoneId",
             "in": "query",
+            "description": "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.",
             "required": false,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/ZoneId"
+            },
+            "examples": {
+              "ZoneId": {
+                "value": "Amer-Zone"
+              }
             }
           },
           {
             "name": "amount",
             "in": "query",
+            "description": "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.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -84,31 +110,20 @@
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "personalized",
             "in": "query",
+            "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
             "required": false,
             "style": "form",
             "explode": true,
@@ -116,12 +131,14 @@
               "type": "string",
               "enum": [
                 "none"
-              ]
+              ],
+              "example": "none"
             }
           },
           {
             "name": "sfdc_shopper_context",
             "in": "header",
+            "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
             "required": false,
             "style": "simple",
             "explode": false,
@@ -137,6 +154,20 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PaymentConfiguration"
+                },
+                "examples": {
+                  "stripeConfiguration": {
+                    "$ref": "#/components/examples/PaymentConfigurationGetForStripe"
+                  },
+                  "stripeAndPaypalConfiguration": {
+                    "$ref": "#/components/examples/PaymentConfigurationGetForStripeAndPaypal"
+                  },
+                  "adyenConfiguration": {
+                    "$ref": "#/components/examples/PaymentConfigurationGetForAdyen"
+                  },
+                  "noDataFound": {
+                    "$ref": "#/components/examples/PaymentConfigurationNoDataFound"
+                  }
                 }
               }
             }
@@ -147,6 +178,14 @@
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "BadRequest": {
+                    "$ref": "#/components/examples/BadRequest"
+                  },
+                  "InvalidPaymentConfigurationRequest": {
+                    "$ref": "#/components/examples/InvalidPaymentConfigurationRequest"
+                  }
                 }
               }
             }
@@ -172,56 +211,55 @@
     },
     "/organizations/{organizationId}/payment-instruments/balance": {
       "post": {
+        "summary": "Check payment instrument balance",
+        "description": "Checks the balance of a payment instrument.\n\n**Parameters:**\n- `siteId`: Required. Specifies the site identifier for context-specific configuration.\n\n**Request Body:**\n- `paymentMethodId`: Required. The payment method ID.\n- `provider`: Required. Identifies the payment provider that handles the balance inquiry.\n- `providerProperties`: Required. Provider-specific balance inquiry properties. Do not include PCI-relevant\n  data, such as a primary account number (PAN), in this object. Use client-side tokenization or encrypted\n  fields when payment-instrument data is required.\n\n**Response Behavior:**\n- Returns the balance amount and currency when the payment instrument is valid.",
         "operationId": "getPaymentInstrumentBalance",
         "parameters": [
           {
             "name": "organizationId",
             "in": "path",
+            "description": "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).",
             "required": true,
             "style": "simple",
             "explode": false,
             "schema": {
               "$ref": "#/components/schemas/OrganizationId"
-            }
+            },
+            "example": "f_ecom_zzxy_prd"
           },
           {
             "name": "siteId",
             "in": "query",
+            "description": "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.",
             "required": true,
             "style": "form",
             "explode": true,
             "schema": {
               "$ref": "#/components/schemas/SiteId"
+            },
+            "examples": {
+              "SiteId": {
+                "value": "RefArch"
+              }
             }
           },
           {
             "name": "sfdc_usid",
             "in": "header",
+            "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
             "required": false,
             "style": "simple",
             "explode": false,
             "schema": {
               "type": "string",
-              "format": "uuid"
-            }
-          },
-          {
-            "name": "sfdc_dw_dnt",
-            "in": "header",
-            "required": false,
-            "style": "simple",
-            "explode": false,
-            "schema": {
-              "type": "string",
-              "enum": [
-                "0",
-                "1"
-              ]
+              "format": "uuid",
+              "example": "550e8400-e29b-41d4-a716-446655440000"
             }
           },
           {
             "name": "sfdc_shopper_context",
             "in": "header",
+            "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
             "required": false,
             "style": "simple",
             "explode": false,
@@ -235,6 +273,11 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/PaymentInstrumentBalanceRequest"
+              },
+              "examples": {
+                "PaymentInstrumentBalanceRequest": {
+                  "$ref": "#/components/examples/PaymentInstrumentBalanceRequest"
+                }
               }
             }
           },
@@ -247,16 +290,29 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PaymentInstrumentBalanceResponse"
+                },
+                "examples": {
+                  "PaymentInstrumentBalance": {
+                    "$ref": "#/components/examples/PaymentInstrumentBalanceSuccess"
+                  }
                 }
               }
             }
           },
           "400": {
-            "description": "Possible reasons:\n- the provided payment method is invalid or not applicable.\n- the gift card details are invalid or missing when paymentMethodId is GIFT_CERTIFICATE.",
+            "description": "Possible reasons:\n- the provided payment method is invalid or not applicable.\n- the provider-specific request properties are invalid or missing.",
             "content": {
               "application/problem+json": {
                 "schema": {
                   "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "BadRequest": {
+                    "$ref": "#/components/examples/BadRequest"
+                  },
+                  "InvalidPaymentInstrumentBalanceRequest": {
+                    "$ref": "#/components/examples/InvalidPaymentInstrumentBalanceRequest"
+                  }
                 }
               }
             }
@@ -285,29 +341,41 @@
     "schemas": {
       "OrganizationId": {
         "type": "string",
+        "description": "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",
         "pattern": "^f_ecom_[a-z]{4}_(prd|stg|dev|s[0-9]{2}|[0-9]{3})$"
       },
       "SiteId": {
         "type": "string",
+        "description": "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": "RefArch",
         "maxLength": 32,
         "minLength": 1
       },
       "CurrencyCode": {
         "type": "string",
+        "description": "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": "USD",
         "pattern": "^([A-Z][A-Z][A-Z]|N/A)$"
       },
       "CountryCode": {
         "type": "string",
+        "description": "A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.",
+        "example": "US",
         "pattern": "^[A-Z][A-Z]$"
       },
       "ZoneId": {
         "type": "string",
+        "description": "The unique identifier for a Payments zone.",
+        "example": "Amer-Zone",
         "maxLength": 100,
         "minLength": 1
       },
       "Amount": {
         "type": "number",
         "format": "double",
+        "description": "The transaction amount.",
+        "example": 100,
         "minimum": 0
       },
       "PaymentConfiguration": {
@@ -315,47 +383,64 @@
         "properties": {
           "zoneId": {
             "type": "string",
+            "description": "The unique identifier for a Payments zone.",
+            "example": "Amer-Zone",
             "maxLength": 100,
             "minLength": 1,
             "pattern": "^[a-zA-Z0-9\\-_]{1,100}$"
           },
           "paymentMethodSetAccounts": {
             "type": "array",
+            "description": "List of payment method set accounts",
             "items": {
               "type": "object",
               "properties": {
                 "accountId": {
                   "type": "string",
+                  "description": "Account identifier",
+                  "example": "acct_1RegszI5I22eU0I3",
                   "maxLength": 100,
                   "minLength": 1
                 },
                 "config": {
                   "type": "object",
                   "additionalProperties": true,
+                  "description": "Account configuration",
                   "properties": {
                     "key": {
                       "type": "string",
+                      "description": "API key for the payment processor",
+                      "example": "pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV",
                       "maxLength": 200
                     },
                     "bnCode": {
                       "type": "string",
+                      "description": "Account BN code (optional, null if not a PayPal account)",
+                      "example": "Example_PPCP",
                       "maxLength": 100
                     },
                     "country": {
                       "type": "string",
+                      "description": "The country associated with this payment account configuration",
+                      "example": "US",
                       "maxLength": 256
                     },
                     "paymentMethods": {
                       "type": "object",
-                      "additionalProperties": true
+                      "additionalProperties": true,
+                      "description": "Available payment methods from gateway (optional, null if not an Adyen account)"
                     }
                   }
                 },
                 "live": {
-                  "type": "boolean"
+                  "type": "boolean",
+                  "description": "Whether the account is in live mode",
+                  "example": false
                 },
                 "vendor": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Payment vendor name",
+                  "example": "Stripe"
                 }
               },
               "required": [
@@ -367,20 +452,30 @@
           },
           "paymentMethods": {
             "type": "array",
+            "description": "Configured payment methods",
             "items": {
               "type": "object",
               "properties": {
                 "accountId": {
                   "type": "string",
+                  "description": "Associated account identifier",
+                  "example": "acct_1RegszI5I22eU0I3",
                   "minLength": 1
                 },
                 "paymentMethodType": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Type of payment method",
+                  "example": "card"
                 },
                 "paymentModes": {
                   "type": "array",
+                  "description": "Supported payment modes",
+                  "example": [
+                    "Multistep"
+                  ],
                   "items": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Multistep"
                   }
                 }
               },
@@ -403,17 +498,25 @@
         "properties": {
           "title": {
             "type": "string",
+            "description": "A short, human-readable summary of the problem\ntype.  It will not change from occurrence to occurrence of the \nproblem, except for purposes of localization\n",
+            "example": "You do not have enough credit",
             "maxLength": 256
           },
           "type": {
             "type": "string",
+            "description": "A URI reference [RFC3986] that identifies the\nproblem type.  This specification encourages that, when\ndereferenced, it provide human-readable documentation for the\nproblem type (e.g., using HTML [W3C.REC-html5-20141028]).  When\nthis member is not present, its value is assumed to be\n\"about:blank\". It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "NotEnoughMoney",
             "maxLength": 2048
           },
           "detail": {
-            "type": "string"
+            "type": "string",
+            "description": "A human-readable explanation specific to this occurrence of the problem.",
+            "example": "Your current balance is 30, but that costs 50"
           },
           "instance": {
             "type": "string",
+            "description": "A URI reference that identifies the specific\noccurrence of the problem.  It may or may not yield further\ninformation if dereferenced.  It accepts relative URIs; this means\nthat they must be resolved relative to the document's base URI, as\nper [RFC3986], Section 5.\n",
+            "example": "/account/12345/msgs/abc",
             "maxLength": 2048
           }
         },
@@ -423,62 +526,44 @@
           "type"
         ]
       },
-      "GiftCardRequest": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "brand": {
-            "type": "string",
-            "maxLength": 256
-          },
-          "cardNumber": {
-            "type": "string",
-            "maxLength": 40
-          },
-          "cvc": {
-            "type": "string",
-            "maxLength": 4
-          },
-          "expirationMonth": {
-            "type": "integer",
-            "format": "int32"
-          },
-          "expirationYear": {
-            "type": "integer",
-            "format": "int32"
-          }
-        },
-        "required": [
-          "brand",
-          "cardNumber",
-          "cvc"
-        ]
-      },
       "PaymentInstrumentBalanceRequest": {
         "type": "object",
+        "description": "Request body for checking the balance of a payment instrument.\n\nThe payment method ID and provider identify the payment provider. Provider-specific properties are defined and\nvalidated by that provider.",
         "properties": {
           "paymentMethodId": {
             "type": "string",
-            "maxLength": 256
+            "description": "The payment method ID.",
+            "example": "COMMERCE_APP_GIFT_CARD",
+            "maxLength": 256,
+            "minLength": 1
           },
-          "giftCard": {
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/GiftCardRequest"
-              }
-            ]
+          "provider": {
+            "type": "string",
+            "description": "Identifies the payment provider that handles the balance inquiry.",
+            "example": "givex",
+            "maxLength": 256,
+            "minLength": 1
+          },
+          "providerProperties": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Provider-specific balance inquiry properties. Do not include PCI-relevant data, such as a primary account\nnumber (PAN), in this object. Use client-side tokenization or encrypted fields when payment-instrument\ndata is required."
           }
         },
         "required": [
-          "giftCard",
-          "paymentMethodId"
+          "paymentMethodId",
+          "provider",
+          "providerProperties"
         ]
       },
       "PaymentInstrumentBalanceResponse": {
         "type": "object",
+        "description": "Response containing the payment instrument balance information.",
         "properties": {
           "amount": {
             "type": "number",
+            "description": "The remaining balance on the payment instrument.",
+            "example": 50,
             "minimum": 0
           },
           "currency": {
@@ -486,7 +571,8 @@
               {
                 "$ref": "#/components/schemas/CurrencyCode"
               }
-            ]
+            ],
+            "description": "The three-letter currency code (ISO 4217) of the payment instrument balance."
           }
         },
         "required": [
@@ -499,36 +585,51 @@
       "organizationId": {
         "name": "organizationId",
         "in": "path",
+        "description": "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).",
         "required": true,
         "style": "simple",
         "explode": false,
         "schema": {
           "$ref": "#/components/schemas/OrganizationId"
-        }
+        },
+        "example": "f_ecom_zzxy_prd"
       },
       "siteId": {
         "name": "siteId",
         "in": "query",
+        "description": "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.",
         "required": true,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/SiteId"
+        },
+        "examples": {
+          "SiteId": {
+            "value": "RefArch"
+          }
         }
       },
       "currency": {
         "name": "currency",
         "in": "query",
+        "description": "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.",
         "required": true,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/CurrencyCode"
+        },
+        "examples": {
+          "CurrencyCode": {
+            "value": "USD"
+          }
         }
       },
       "countryCode": {
         "name": "countryCode",
         "in": "query",
+        "description": "The country code (ISO 3166-1 alpha-2) for country-specific payment configuration filtering.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -539,16 +640,23 @@
       "zoneId": {
         "name": "zoneId",
         "in": "query",
+        "description": "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.",
         "required": false,
         "style": "form",
         "explode": true,
         "schema": {
           "$ref": "#/components/schemas/ZoneId"
+        },
+        "examples": {
+          "ZoneId": {
+            "value": "Amer-Zone"
+          }
         }
       },
       "amount": {
         "name": "amount",
         "in": "query",
+        "description": "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.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -559,31 +667,20 @@
       "sfdcUsid": {
         "name": "sfdc_usid",
         "in": "header",
+        "description": "A unique shopper identifier (USID) for tracking client context.\nUsed with endpoints secured with ShopperClientContextToken.\nThis header is required for all endpoints secured with ShopperClientContextToken.",
         "required": false,
         "style": "simple",
         "explode": false,
         "schema": {
           "type": "string",
-          "format": "uuid"
-        }
-      },
-      "sfdcDwDnt": {
-        "name": "sfdc_dw_dnt",
-        "in": "header",
-        "required": false,
-        "style": "simple",
-        "explode": false,
-        "schema": {
-          "type": "string",
-          "enum": [
-            "0",
-            "1"
-          ]
+          "format": "uuid",
+          "example": "550e8400-e29b-41d4-a716-446655440000"
         }
       },
       "personalized": {
         "name": "personalized",
         "in": "query",
+        "description": "Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.",
         "required": false,
         "style": "form",
         "explode": true,
@@ -591,12 +688,14 @@
           "type": "string",
           "enum": [
             "none"
-          ]
+          ],
+          "example": "none"
         }
       },
       "sfdcShopperContext": {
         "name": "sfdc_shopper_context",
         "in": "header",
+        "description": "Shopper context information (for example clientIP, sourceCode, and customQualifiers)\npassed in from a trusted backend application.",
         "required": false,
         "style": "simple",
         "explode": false,
@@ -605,9 +704,160 @@
         }
       }
     },
+    "examples": {
+      "PaymentConfigurationGetForStripe": {
+        "value": {
+          "zoneId": "Amer-Zone",
+          "paymentMethodSetAccounts": [
+            {
+              "accountId": "acct_1RegszI5I22eU0I3",
+              "config": {
+                "key": "pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV"
+              },
+              "live": false,
+              "vendor": "Stripe"
+            }
+          ],
+          "paymentMethods": [
+            {
+              "accountId": "acct_1RegszI5I22eU0I3",
+              "paymentMethodType": "card",
+              "paymentModes": [
+                "Multistep"
+              ]
+            }
+          ]
+        }
+      },
+      "PaymentConfigurationGetForStripeAndPaypal": {
+        "value": {
+          "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"
+              ]
+            }
+          ]
+        }
+      },
+      "PaymentConfigurationGetForAdyen": {
+        "value": {
+          "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"
+              ]
+            }
+          ]
+        }
+      },
+      "PaymentConfigurationNoDataFound": {
+        "value": {
+          "paymentMethodSetAccounts": [],
+          "paymentMethods": []
+        }
+      },
+      "BadRequest": {
+        "value": {
+          "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'."
+        }
+      },
+      "InvalidPaymentConfigurationRequest": {
+        "value": {
+          "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"
+        }
+      },
+      "PaymentInstrumentBalanceRequest": {
+        "value": {
+          "paymentMethodId": "COMMERCE_APP_GIFT_CARD",
+          "provider": "givex",
+          "providerProperties": {
+            "balanceToken": "provider-issued-short-lived-token"
+          }
+        }
+      },
+      "PaymentInstrumentBalanceSuccess": {
+        "value": {
+          "amount": 50,
+          "currency": "USD"
+        }
+      },
+      "InvalidPaymentInstrumentBalanceRequest": {
+        "value": {
+          "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."
+        }
+      }
+    },
     "securitySchemes": {
       "ShopperToken": {
         "type": "oauth2",
+        "description": "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. \nFor a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).\nA 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.\nThe `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.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token",
@@ -619,6 +869,7 @@
           "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",
             "scopes": {
               "sfcc.shopper-baskets-orders": "Scope granting read-access to shopper basket or orders endpoints",
               "sfcc.shopper-baskets-orders.rw": "Scope granting read and write access to shopper basket or orders endpoints"
@@ -628,6 +879,7 @@
       },
       "ShopperClientContextToken": {
         "type": "oauth2",
+        "description": "ShopperClientContextToken is a separate security scheme used to track and validate client context information.\nIt is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows.\nFor authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).\nThis token allows access to Shopper API endpoints for guest shoppers only.\n",
         "flows": {
           "clientCredentials": {
             "tokenUrl": "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client_context",