Payment settings API (BETA)

Use the payment settings API to retrieve and update configuration for payment methods, checkout behavior, policies, shipping, and fees.

Payment methods

Payment method settings control which payment methods are enabled for your account and which are set as the default option. You can retrieve and update default payment methods using the same endpoint. To retrieve your payment method settings settings, make a GET request to /commerce/payment-methods/2027-03-beta/settings. The response will return settings for all payment methods, including their active and supported currencies.

{
  "paymentMethodSettings": [
    {
      "commercePaymentMethod": "PADS",
      "isDefaultOn": false,
      "activeCurrencies": [
        "CAD"
      ],
      "supportedCurrencies": [
        "CAD"
      ]
    },
    {
      "commercePaymentMethod": "SEPA",
      "isDefaultOn": false,
      "activeCurrencies": [],
      "supportedCurrencies": [
        "EUR"
      ]
    },
    {
      "commercePaymentMethod": "KLARNA",
      "isDefaultOn": false,
      "activeCurrencies": [
        "USD"
      ],
      "supportedCurrencies": [
        "USD"
      ]
    },
    {
      "commercePaymentMethod": "AFFIRM",
      "isDefaultOn": false,
      "activeCurrencies": [
        "USD"
      ],
      "supportedCurrencies": [
        "USD"
      ]
    },
    {
      "commercePaymentMethod": "CARD",
      "isDefaultOn": true,
      "activeCurrencies": [
        "CAD",
        "USD"
      ],
      "supportedCurrencies": [
        "CAD",
        "USD",
        "AED",
        "AFN",
        "ALL",
        "AMD",
        "ANG",
        "AOA",
        "ARS",
        "AUD",
        "AWG",
        "AZN",
        "BAM",
        "BBD",
        "BDT",
        "BIF",
        "BMD",
        "BND",
        "BOB",
        "BRL",
        "BSD",
        "BWP",
        "BYN",
        "BZD",
        "CDF",
        "CHF",
        "CLP",
        "CNY",
        "COP",
        "CRC",
        "CVE",
        "CZK",
        "DJF",
        "DKK",
        "DOP",
        "DZD",
        "EGP",
        "ETB",
        "EUR",
        "FJD",
        "FKP",
        "GBP",
        "GEL",
        "GIP",
        "GMD",
        "GNF",
        "GTQ",
        "GYD",
        "HKD",
        "HNL",
        "HTG",
        "HUF",
        "IDR",
        "ILS",
        "INR",
        "JMD",
        "JPY",
        "KES",
        "KGS",
        "KHR",
        "KMF",
        "KRW",
        "KYD",
        "KZT",
        "LAK",
        "LBP",
        "LKR",
        "LRD",
        "LSL",
        "MAD",
        "MDL",
        "MGA",
        "MKD",
        "MMK",
        "MNT",
        "MOP",
        "MUR",
        "MVR",
        "MWK",
        "MXN",
        "MYR",
        "MZN",
        "NAD",
        "NGN",
        "NIO",
        "NOK",
        "NPR",
        "NZD",
        "PAB",
        "PEN",
        "PGK",
        "PHP",
        "PKR",
        "PLN",
        "PYG",
        "QAR",
        "RON",
        "RSD",
        "RUB",
        "RWF",
        "SAR",
        "SBD",
        "SCR",
        "SEK",
        "SGD",
        "SHP",
        "SOS",
        "SRD",
        "SZL",
        "THB",
        "TJS",
        "TOP",
        "TRY",
        "TTD",
        "TWD",
        "TZS",
        "UAH",
        "UYU",
        "UZS",
        "VND",
        "VUV",
        "WST",
        "XAF",
        "XCD",
        "XOF",
        "XPF",
        "YER",
        "ZAR",
        "ZMW"
      ]
    },
    {
      "commercePaymentMethod": "ACH",
      "isDefaultOn": true,
      "activeCurrencies": [
        "USD"
      ],
      "supportedCurrencies": [
        "USD"
      ]
    }
  ]
}

Field	Type	Description
`commercePaymentMethod`	String	The payment method type. Accepted values: `ACH`, `AFFIRM`, `BACS`, `CARD`, `CASH`, `CHECK`, `KLARNA`, `OTHER`, `PADS`, `SEPA`, `WIRE_TRANSFER`.
`isDefaultOn`	Boolean	Whether this payment method is set as the default option at checkout.
`activeCurrencies`	Array	The currencies that are both active on your account and compatible with this payment method. This is a subset of `supportedCurrencies` filtered to your account’s enabled currencies. Read-only.
`supportedCurrencies`	Array	The full list of currencies this payment method can support. Read-only.

To update payment method settings, make a PATCH request to /commerce/payment-methods/2027-03-beta/settings. In the request body, include a paymentMethodUpdates array containing your payment method updates.

{
  "paymentMethodUpdates": [
    {
      "commercePaymentMethod": "ACH",
      "isDefaultOn": true
    }
  ]
}

Field	Type	Description
`commercePaymentMethod`	String	The payment method type to update. Accepted values: `ACH`, `AFFIRM`, `BACS`, `CARD`, `CASH`, `CHECK`, `KLARNA`, `OTHER`, `PADS`, `SEPA`, `WIRE_TRANSFER`.
`isDefaultOn`	Boolean	Whether to set this payment method as the default option at checkout.

A successful PATCH request returns the updated settings in the same format as the GET response.

Billing settings

Billing settings control checkout behavior for your HubSpot account, including how buyer information is collected, stored, and tracked. You can retrieve and update these settings using the same endpoint: /commerce/payments-settings/2027-03-beta/payments-settings/billing

To retrieve settings, make a GET request to the endpoint. The response will return all current settings.
To update settings, make a PATCH request to the endpoint. In the request body, include the settings that you want to update.

{
  "checkoutPrefillEnabled": true,
  "collectFullBillingAddress": false,
  "collectPaymentMethodOnFile": true,
  "defaultFromEmailAddress": "billing@example.com",
  "paymentsGoogleAnalyticsEnabled": false,
  "recaptchaEnabled": true,
  "accountGoogleAnalyticsEnabled": false
}

Field	Type	Description
`checkoutPrefillEnabled`	Boolean	Whether checkout fields should be prefilled with known customer information.
`collectFullBillingAddress`	Boolean	Whether the full billing address should be collected during checkout.
`collectPaymentMethodOnFile`	Boolean	Whether a payment method should be stored on file for future transactions.
`defaultFromEmailAddress`	String	The default email address used for sending billing-related communications.
`paymentsGoogleAnalyticsEnabled`	Boolean	Whether Google Analytics tracking is enabled for payment transactions.
`recaptchaEnabled`	Boolean	Whether reCAPTCHA is enabled during checkout to prevent fraudulent activity.
`accountGoogleAnalyticsEnabled`	Boolean	Whether Google Analytics tracking is enabled for the account.

A successful PATCH request returns the updated settings in the same format as the GET response.

Shipping settings

Shipping settings control whether a shipping address is collected during checkout and which countries you ship to. You can retrieve and update these settings using the same endpoint: /commerce/payments-settings/2027-03-beta/payments-settings/shipping

To retrieve settings, make a GET request to the endpoint. The response will return all current settings.
To update settings, make a PATCH request to the endpoint. In the request body, include the settings that you want to update.

{
  "collectShippingAddressByDefault": true,
  "countriesShippedTo": ["US", "CA", "GB"]
}

Field	Type	Description
`collectShippingAddressByDefault`	Boolean	Whether a shipping address is collected by default during checkout.
`countriesShippedTo`	Array	The list of countries to which shipping is available. Use two-digit ISO country codes (e.g., `US`, `CA`, `GB`).

A successful PATCH request returns the updated settings in the same format as the GET response.

Policy settings

Policy settings control the terms, cancellation policy, and refund policy shown to buyers during checkout. You can retrieve and update these settings using the same endpoint: /commerce/payments-settings/2027-03-beta/payments-settings/policy

To retrieve settings, make a GET request to the endpoint. The response will return all current settings.
To update settings, make a PATCH request to the endpoint. In the request body, include the settings that you want to update.

{
  "acknowledgementRequired": true,
  "customPolicyEnabled": true,
  "cancellationPolicyText": "All sales are final. Cancellations must be requested within 24 hours of purchase.",
  "refundPolicyText": "Refunds are issued within 5-7 business days to the original payment method.",
  "termsOfServiceUrl": "https://example.com/terms"
}

Field	Type	Description
`acknowledgementRequired`	Boolean	Whether buyers must acknowledge the policy before completing checkout.
`customPolicyEnabled`	Boolean	Whether a custom policy is enabled and displayed during checkout.
`cancellationPolicyText`	String	The text of the cancellation policy shown to buyers.
`refundPolicyText`	String	The text of the refund policy shown to buyers.
`termsOfServiceUrl`	String	The URL of your terms of service page.

A successful PATCH request returns the updated settings in the same format as the GET response.

Checkout fees

Checkout fees are additional charges applied to payments at checkout, such as credit card surcharges. You can retrieve and update checkout fees using the same endpoint: /commerce/payments-settings/2027-03-beta/payments-settings/checkout-fees

To retrieve settings, make a GET request to the endpoint. The response will return all current checkout fees.
To update fees, make a PATCH request to the endpoint. In the request body, include a checkoutFees array with an object for each fee.

{
  "checkoutFees": [
    {
      "id": "fee_123",
      "name": "Credit card surcharge",
      "feeValue": 2.5,
      "feeValueType": "PERCENT",
      "appliesToPaymentType": "CARD"
    }
  ]
}

Field	Type	Description
`id`	String	The unique identifier for the checkout fee. Returned in `GET` responses; include when updating an existing fee via `PATCH`.
`name`	String	The display name of the checkout fee.
`feeValue`	Number	The percentage value of the fee.
`feeValueType`	String	How the fee value is applied. Accepted value: `PERCENT`.
`appliesToPaymentType`	String	The payment type this fee applies to. Accepted values: `CARD`, `DIRECT_DEBIT`, `ALL`, `BUY_NOW_PAY_LATER`.

A successful PATCH request returns the updated fees in the same format as the GET response.

Delete a checkout fee

To remove a specific checkout fee, make a DELETE request to /commerce/payments-settings/2027-03-beta/payments-settings/checkout-fees/{checkoutFeeId}, replacing {checkoutFeeId} with the id of the fee you want to remove. A successful DELETE request returns a 204 response with no body.

​Payment methods

​Billing settings

​Shipping settings

​Policy settings

​Checkout fees

​Delete a checkout fee

Payment methods

Billing settings

Shipping settings

Policy settings

Checkout fees

Delete a checkout fee