Settings | ArcBlock

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.

Create a new setting

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.

Response

{
  "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.

Retrieve a setting

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.

Response

{
  "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.

Update a setting

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.

Response

{
  "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.

Delete a setting

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.

Response

{
  "message": "Setting set_1a2b3c4d5e6f7g8h deleted"
}