API Reference

Settings

The Settings API allows you to manage various configurations within PaymentKit, such as donation widgets or notification endpoints. This resource provides methods to create, retrieve, update, and delete settings objects.
The Setting Object#A setting object contains configuration details for a specific feature or component. The structure of the settings property varies depending on the type of the setting.
Attribute
Type
Description
id
string
Unique identifier for the setting.
type
string
The type of setting, e.g., 'donate', 'notification'. Determines the schema of the settings object.
mount_location
string
A unique string identifier for where the setting is used or mounted.
description
string
A human-readable description of the setting.
active
boolean
Whether the setting is currently active.
livemode
boolean
true if the object exists in live mode or false if it exists in test mode.
settings
object
An object containing the configuration specific to the setting's type.
component_did
string
Optional. The DID of the component associated with this setting.
created_at
string
Timestamp of when the setting was created.
updated_at
string
Timestamp of when the setting was last updated.
Create a Setting#Creates a new setting object. You must specify the type, mountLocation, and description.
Endpoint: POST /api/settings
Parameters
Name
Type
Description
type
string
Required. The type of setting to create (e.g., 'donate', 'notification').
mountLocation
string
Required. A unique identifier for the setting's location.
description
string
Required. A description of what this setting is for.
settings
object
Optional. An object with configuration specific to the type. See detailed properties below.
active
boolean
Optional. Whether the setting is active. Defaults to true.
livemode
boolean
Optional. The mode for this setting. Defaults to true.
componentDid
string
Optional. The DID of the component creating the setting.
DonateSetting Object Properties
When type is 'donate', the settings object can contain the following properties:
Name
Type
Description
amount
object
Configuration for donation amounts. See the amount object properties table below.
btnText
string
The text displayed on the donation button. Defaults to 'Donate'.
historyType
'table' | 'avatar'
How to display donation history. Defaults to 'avatar'.
amount Object Properties (for DonateSetting)
Name
Type
Description
presets
string[]
An array of predefined donation amounts. Required if custom is false. Defaults to ['1', '5', '10'].
preset
string
The default selected preset amount. Defaults to '5'.
custom
boolean
Required. Whether to allow custom donation amounts. Defaults to true.
minimum
string
The minimum allowed amount for custom donations. Required if custom is true. Defaults to '0.01'.
maximum
string
The maximum allowed amount for custom donations. Required if custom is true. Defaults to '100'.
NotificationSetting Object Properties
When type is 'notification', the settings object can contain the following properties:
Name
Type
Description
self_handle
boolean
Required. If true, indicates that the component will handle notifications itself. Defaults to false.
include_events
string[]
Optional. An array of event types to be included in notifications.
exclude_events
string[]
Optional. An array of event types to be excluded from notifications.
Returns
Returns the newly created TSetting object.
Example
import payment from '@blocklet/payment-js';

async function createDonateSetting() {
  try {
    const newSetting = await payment.settings.create({
      type: 'donate',
      mountLocation: 'site/sidebar',
      description: 'Donation button for the main site sidebar',
      active: true,
      settings: {
        amount: {
          presets: ['5', '10', '20'],
          preset: '10',
          custom: true,
          minimum: '1',
          maximum: '500',
        },
        btnText: 'Support Us',
      },
    });
    console.log('Setting created:', newSetting);
  } catch (error) {
    console.error('Error creating setting:', error.message);
  }
}

createDonateSetting();Example Response
{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "type": "donate",
  "mount_location": "site/sidebar",
  "description": "Donation button for the main site sidebar",
  "active": true,
  "livemode": true,
  "settings": {
    "amount": {
      "presets": [
        "5",
        "10",
        "20"
      ],
      "preset": "10",
      "minimum": "1",
      "maximum": "500",
      "custom": true
    },
    "btnText": "Support Us",
    "historyType": "avatar"
  },
  "component_did": null,
  "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.
Endpoint: GET /api/settings/{id}
Parameters
Name
Type
Description
id
string
Required. The unique identifier (id) or the mountLocation of the setting to retrieve.
Returns
Returns the TSetting object if found.
Example
import payment from '@blocklet/payment-js';

async function getSetting(settingIdentifier) {
  try {
    const setting = await payment.settings.retrieve(settingIdentifier);
    console.log('Retrieved setting:', setting);
  } catch (error) {
    console.error(`Error retrieving setting ${settingIdentifier}:`, error.message);
  }
}

// Retrieve by mountLocation
getSetting('site/sidebar');

// Or retrieve by ID
// getSetting('set_1J2K3L4M5N6O7P8Q');Example Response
{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "type": "donate",
  "mount_location": "site/sidebar",
  "description": "Donation button for the main site sidebar",
  "active": true,
  "livemode": true,
  "settings": {
    "amount": {
      "presets": [
        "5",
        "10",
        "20"
      ],
      "preset": "10",
      "minimum": "1",
      "maximum": "500",
      "custom": true
    },
    "btnText": "Support Us",
    "historyType": "avatar"
  },
  "component_did": null,
  "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.
Endpoint: PUT /api/settings/{id}
Parameters
Name
Type
Description
id
string
Required. The unique identifier (id) or the mountLocation of the setting to update.
updateData
object
Required. An object containing the fields to update.
updateData Object Properties
Name
Type
Description
settings
object
Optional. A partial settings object. The values will be merged with the existing settings.
active
boolean
Optional. The new active status for the setting.
description
string
Optional. The new description for the setting.
Returns
Returns the updated TSetting object.
Example
import payment from '@blocklet/payment-js';

async function updateSetting(settingIdentifier) {
  try {
    const updatedSetting = await payment.settings.update(settingIdentifier, {
      description: 'New updated description for the sidebar donation button',
      active: false,
    });
    console.log('Setting updated:', updatedSetting);
  } catch (error) {
    console.error(`Error updating setting ${settingIdentifier}:`, error.message);
  }
}

updateSetting('site/sidebar');Example Response
{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "type": "donate",
  "mount_location": "site/sidebar",
  "description": "New updated description for the sidebar donation button",
  "active": false,
  "livemode": true,
  "settings": {
    "amount": {
      "presets": [
        "5",
        "10",
        "20"
      ],
      "preset": "10",
      "minimum": "1",
      "maximum": "500",
      "custom": true
    },
    "btnText": "Support Us",
    "historyType": "avatar"
  },
  "component_did": null,
  "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.
Endpoint: DELETE /api/settings/{id}
Parameters
Name
Type
Description
id
string
Required. The unique identifier (id) or the mountLocation of the setting to delete.
Returns
Returns a confirmation message object.
Example
import payment from '@blocklet/payment-js';

async function deleteSetting(settingIdentifier) {
  try {
    const response = await payment.settings.del(settingIdentifier);
    console.log(response.message);
  } catch (error) {
    console.error(`Error deleting setting ${settingIdentifier}:`, error.message);
  }
}

deleteSetting('site/sidebar');Example Response
{
  "message": "Setting site/sidebar deleted"
}This guide covers the core functionalities of the Settings API, enabling you to manage dynamic configurations within your application.

Attribute	Type	Description
`id`	`string`	Unique identifier for the setting.
`type`	`string`	The type of setting, e.g., 'donate', 'notification'. Determines the schema of the `settings` object.
`mount_location`	`string`	A unique string identifier for where the setting is used or mounted.
`description`	`string`	A human-readable description of the setting.
`active`	`boolean`	Whether the setting is currently active.
`livemode`	`boolean`	`true` if the object exists in live mode or `false` if it exists in test mode.
`settings`	`object`	An object containing the configuration specific to the setting's `type`.
`component_did`	`string`	Optional. The DID of the component associated with this setting.
`created_at`	`string`	Timestamp of when the setting was created.
`updated_at`	`string`	Timestamp of when the setting was last updated.

Name	Type	Description
`type`	`string`	Required. The type of setting to create (e.g., `'donate'`, `'notification'`).
`mountLocation`	`string`	Required. A unique identifier for the setting's location.
`description`	`string`	Required. A description of what this setting is for.
`settings`	`object`	Optional. An object with configuration specific to the `type`. See detailed properties below.
`active`	`boolean`	Optional. Whether the setting is active. Defaults to `true`.
`livemode`	`boolean`	Optional. The mode for this setting. Defaults to `true`.
`componentDid`	`string`	Optional. The DID of the component creating the setting.

Name	Type	Description
`amount`	`object`	Configuration for donation amounts. See the `amount` object properties table below.
`btnText`	`string`	The text displayed on the donation button. Defaults to `'Donate'`.
`historyType`	`'table' \| 'avatar'`	How to display donation history. Defaults to `'avatar'`.

Name	Type	Description
`presets`	`string[]`	An array of predefined donation amounts. Required if `custom` is `false`. Defaults to `['1', '5', '10']`.
`preset`	`string`	The default selected preset amount. Defaults to `'5'`.
`custom`	`boolean`	Required. Whether to allow custom donation amounts. Defaults to `true`.
`minimum`	`string`	The minimum allowed amount for custom donations. Required if `custom` is `true`. Defaults to `'0.01'`.
`maximum`	`string`	The maximum allowed amount for custom donations. Required if `custom` is `true`. Defaults to `'100'`.

Name	Type	Description
`self_handle`	`boolean`	Required. If `true`, indicates that the component will handle notifications itself. Defaults to `false`.
`include_events`	`string[]`	Optional. An array of event types to be included in notifications.
`exclude_events`	`string[]`	Optional. An array of event types to be excluded from notifications.

Overview

Getting Started

SDK Structure

Environments

Core Concepts

API Reference

Settings

The Setting Object#

Create a Setting#

Retrieve a Setting#

Update a Setting#

Delete a Setting#

Webhook Endpoints

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

Name	Type	Description
`settings`	`object`	Optional. A partial settings object. The values will be merged with the existing settings.
`active`	`boolean`	Optional. The new active status for the setting.
`description`	`string`	Optional. The new description for the setting.