Payment Method Configurations

A Payment Method Configuration is the merchant-owned allowlist for future Checkout Sessions. It controls stablecoin and network pairs, transfer experiences, customer eligibility, amount limits and display order in the current test or live mode.

The configuration is not a provider readiness record. Operational token availability is evaluated when the API resolves the configuration, and each Checkout Session stores the resolved, customer-safe snapshot it was created with.

Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/payment_method_configurations/default`	Retrieve the current version and capability reasons.
`PUT`	`/api/v1/payment_method_configurations/default`	Publish the next version with optimistic concurrency.

Use a server secret key with payment_method_configurations.read or payment_method_configurations.update. Portal administrators can manage the same resource from Settings → Payment methods.

Retrieve the current configuration

const configuration =
  await paybytoken.paymentMethodConfigurations.getDefault()

The response contains the saved stablecoin policy and resolved capabilities. Capability reason values are:

Reason	Meaning
`available`	At least one configured option can be used now.
`temporarily_unavailable`	Configured, but the token or network is currently disabled.
`not_configured`	The merchant disabled the payment method.
`customer_ineligible`	The method requires an identified customer and this checkout has none.

Publish a new version

Pass the version you retrieved as if_version. If another administrator already saved a newer version, the API returns 409 instead of overwriting it.

const updated = await paybytoken.paymentMethodConfigurations.updateDefault({
  if_version: configuration.version,
  stablecoin: {
    enabled: true,
    display_order: 1,
    customer_eligibility: 'all',
    wallets: {
      browser_wallet: true,
      manual_transfer: true,
    },
    limits: {
      minimum_amount: '1.00',
      maximum_amount: '5000.00',
    },
    tokens: [
      { currency: 'USDC', chain: 'base' },
      { currency: 'USDC', chain: 'polygon' },
    ],
  },
})

At least one transfer experience and one known token/network pair must remain configured. Test and live settings are isolated.

Checkout resolution

When creating a Checkout Session, omit supported_tokens to accept every configured option. Pass it only when one order needs a narrower subset:

const session = await paybytoken.checkoutSessions.create({
  currency: 'usd',
  line_items: order.items,
  supported_tokens: [{ currency: 'USDC', chain: 'base' }],
})

A request cannot enable a token, network, wallet experience or customer class that the current configuration disallows. The response exposes:

payment_method_configuration: the configuration ID and version used;
payment_method_options: the immutable capability snapshot for hosted, embedded and custom UI;
supported_tokens: only the currently available token records the customer may confirm.

Changing the configuration never changes an existing Session. Create a new Session to apply a new version.