Settings

The Settings API allows you to manage various configurations within PaymentKit, such as creating donation widgets or setting up notification handlers. Each setting is a configurable resource identified by its type and mountLocation.

The Setting Object#

A Setting object contains the configuration for a specific feature.

Attribute	Type	Description
id	string	Unique identifier for the setting object.
type	string	The type of setting, e.g., 'donate', 'notification'.
mount_location	string	A unique identifier for where the setting is used, often a URL path or component name.
description	string	A human-readable description of the setting.
settings	object	An object containing the specific configuration for this setting type. See details below.
active	boolean	Whether the setting is currently active.
livemode	boolean	true if the object exists in live mode, false if it exists in test mode.
component_did	string	The DID of the component that created this setting.
created_at	string	Timestamp of when the setting was created.
updated_at	string	Timestamp of when the setting was last updated.

The settings object for donate#

Attribute	Type	Description
amount	object	Configuration for donation amounts.
btnText	string	The text displayed on the donation button. Default: 'Donate'.
historyType	'table' | 'avatar'	The display style for donation history. Default: 'avatar'.

amount object properties

Attribute	Type	Description
presets	string[]	An array of predefined donation amounts. Required if custom is false.
preset	string	The default selected amount from the presets.
custom	boolean	Whether to allow custom donation amounts.
minimum	string	The minimum allowed amount for custom donations. Required if custom is true.
maximum	string	The maximum allowed amount for custom donations. Required if custom is true.

The settings object for notification#

Attribute	Type	Description
self_handle	boolean	If true, indicates that the component will handle the notification events itself.
include_events	string[]	An array of event types to be included in notifications.
exclude_events	string[]	An array of event types to be excluded from notifications.

Create a Setting#

Creates a new setting object.

const setting = await payment.settings.create({
  type: 'donate',
  mountLocation: '/community/donate',
  description: 'Community Donation Page',
  settings: {
    amount: {
      presets: ['5', '10', '25'],
      preset: '10',
      custom: true,
      minimum: '1',
      maximum: '1000',
    },
    btnText: 'Support Us',
  },
});

Parameters

Name	Type	Description
type	string	Required. The type of setting to create (e.g., 'donate', 'notification').
mountLocation	string	Required. A unique identifier for where the setting will be used.
description	string	Required. A description for the setting.
settings	object	Optional. An object with configuration specific to the type.
active	boolean	Optional. Whether the setting is active. Defaults to true.
livemode	boolean	Optional. Specifies the mode. Defaults to true.
componentDid	string	Optional. The DID of the component creating the setting.

Returns

The newly created setting object.

{
  "id": "set_1a2b3c4d5e6f7g8h",
  "type": "donate",
  "mount_location": "/community/donate",
  "description": "Community Donation Page",
  "settings": {
    "amount": {
      "presets": ["5", "10", "25"],
      "preset": "10",
      "custom": true,
      "minimum": "1",
      "maximum": "1000"
    },
    "btnText": "Support Us",
    "historyType": "avatar"
  },
  "active": true,
  "livemode": true,
  "component_did": "z1...",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

Retrieve a Setting#

Retrieves the details of an existing setting by its ID or mountLocation.

const settingId = 'set_1a2b3c4d5e6f7g8h';
const setting = await payment.settings.retrieve(settingId);

Parameters

Name	Type	Description
id	string	Required. The unique identifier or mountLocation of the setting to retrieve.

Returns

The setting object if found, otherwise an error is thrown.

{
  "id": "set_1a2b3c4d5e6f7g8h",
  "type": "donate",
  "mount_location": "/community/donate",
  "description": "Community Donation Page",
  "settings": {
    "amount": {
      "presets": ["5", "10", "25"],
      "preset": "10",
      "custom": true,
      "minimum": "1",
      "maximum": "1000"
    },
    "btnText": "Support Us",
    "historyType": "avatar"
  },
  "active": true,
  "livemode": true,
  "component_did": "z1...",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

Update a Setting#

Updates the specified setting by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

const settingId = 'set_1a2b3c4d5e6f7g8h';
const updatedSetting = await payment.settings.update(settingId, {
  description: 'Updated Community Donation Page',
  active: false,
  settings: {
    btnText: 'Donate Now',
  },
});

Parameters

Name	Type	Description
id	string	Required. The unique identifier or mountLocation of the setting to update.
data	object	Required. An object containing the fields to update.

data object properties

Name	Type	Description
description	string	Optional. An updated description for the setting.
active	boolean	Optional. Whether the setting is active.
settings	object	Optional. An object with setting-specific fields to update. This will be merged with the existing settings.

Returns

The updated setting object.

{
  "id": "set_1a2b3c4d5e6f7g8h",
  "type": "donate",
  "mount_location": "/community/donate",
  "description": "Updated Community Donation Page",
  "settings": {
    "amount": {
      "presets": ["5", "10", "25"],
      "preset": "10",
      "custom": true,
      "minimum": "1",
      "maximum": "1000"
    },
    "btnText": "Donate Now",
    "historyType": "avatar"
  },
  "active": false,
  "livemode": true,
  "component_did": "z1...",
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}

Delete a Setting#

Permanently deletes a setting. It cannot be undone.

const settingId = 'set_1a2b3c4d5e6f7g8h';
const response = await payment.settings.del(settingId);

Parameters

Name	Type	Description
id	string	Required. The unique identifier or mountLocation of the setting to delete.

Returns

A confirmation message.

{
  "message": "Setting set_1a2b3c4d5e6f7g8h deleted"
}