> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment settings API (BETA)

> Retrieve and update payment settings for your HubSpot account.

export const BetaDisclaimerBanner = () => <Warning>
        This functionality is currently in beta. By participating in this beta, you agree to HubSpot's <a href="https://legal.hubspot.com/developer-terms">Developer Terms</a> and <a href="https://legal.hubspot.com/developerbetaterms">Developer Beta Terms</a>. Note that the functionality is still under active development and is subject to change based on testing and feedback.
    </Warning>;

<BetaDisclaimerBanner />

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.

```json expandable theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.