> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/guides/settings/overview/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Overview: Settings

> Configure your PaymentKit account settings to customize branding, billing behavior, notifications, and more.

# Account settings

Access settings through the dashboard sidebar under **Settings**.

## Brand & Identity

Customize how your business appears to customers:

| Setting           | Description                                       |
| ----------------- | ------------------------------------------------- |
| **Company name**  | Your business name shown on invoices and checkout |
| **Logo**          | Displayed on hosted pages, emails, and invoices   |
| **Primary color** | Brand color used in checkout and portal           |
| **Support email** | Contact email shown to customers                  |
| **Support URL**   | Link to your help center or support page          |

> **Tip**
>
> Upload a high-resolution logo (at least 512x512px) for best results across all devices and email clients.

## Custom domain

Use your own domain for hosted pages:

1. Navigate to **Settings > Custom Domain**
2. Enter your desired subdomain (e.g., `pay.yourcompany.com`)
3. Add the provided DNS records to your domain
4. Wait for verification (usually within an hour)

Once configured, your checkout and portal URLs will use your custom domain instead of `paymentkit.com`.

## Business details

Configure your business information for invoices and tax compliance:

| Field                | Description                                  |
| -------------------- | -------------------------------------------- |
| **Business address** | Your registered business address             |
| **Tax ID**           | VAT, GST, or other tax identification number |
| **Default currency** | Primary currency for new prices              |
| **Default timezone** | Used for reports and scheduled operations    |

# Billing settings

## Invoice settings

Configure default invoice behavior:

| Setting               | Default         | Description                              |
| --------------------- | --------------- | ---------------------------------------- |
| **Invoice numbering** | Sequential      | Number format (e.g., INV-0001, INV-0002) |
| **Invoice prefix**    | INV             | Prefix for invoice numbers               |
| **Footer text**       | Empty           | Custom text shown at bottom of invoices  |
| **Payment terms**     | Due immediately | Default days until payment is due        |

## Preview an invoice PDF

Generate a sample invoice PDF that uses your account's real invoice settings and branding (logo, address, tax IDs, footer) but with mock line-item data. Use it to iterate on invoice styling without issuing a real invoice.

```bash
curl -X POST https://app.paymentkit.com/api/accounts/{account_id}/invoice-pdf/preview \
  -H "Authorization: Bearer sk_live_..." \
  --output invoice-preview.pdf
```

The endpoint takes no request body and returns the PDF bytes directly (`Content-Type: application/pdf`, served inline as `invoice-preview.pdf`).

> **Note**
>
> The preview reflects your current **invoice settings** and **brand settings** — update those first, then regenerate the preview to see your changes.

> **Note**
>
> This endpoint requires the **Settings** · **View** permission.

## Dunning behavior

Configure what happens when payments fail:

| Behavior                                 | Subscription | Invoice       | Description                           |
| ---------------------------------------- | ------------ | ------------- | ------------------------------------- |
| **Cancel and mark uncollectible**        | Cancelled    | Uncollectible | Default - clean break                 |
| **Cancel and keep open**                 | Cancelled    | Open          | Pursue collection externally          |
| **Keep past due and mark uncollectible** | Past Due     | Uncollectible | Maintain service, write off debt      |
| **Keep past due and keep open**          | Past Due     | Open          | Maintain service, continue collection |

#### [Learn more about dunning](/guides/billing/dunning-recovery/automatic-retries-emails)

Understand how PaymentKit handles failed payments and recovery.

# Notification settings

Notification settings control the **merchant-facing** alerts your team receives about payment activity — both via **Slack** and via **email to your own team** (distinct from the customer-facing emails below). Configure them under **Settings > Notifications** or via the API.

## Slack notifications

Send real-time alerts to your team's Slack channels when payments succeed or fail. PaymentKit posts to one or more [Slack incoming webhook URLs](https://api.slack.com/messaging/webhooks).

## Get notification settings

```bash
curl https://app.paymentkit.com/api/accounts/{account_id}/notification-settings \
  -H "Authorization: Bearer sk_live_..."
```

Response:

```json
{
  "invoice": {
    "on_finalized": false,
    "on_paid": false
  },
  "dunning": {
    "failed_payment": false
  },
  "slack_enabled": true,
  "slack_webhook_urls": [
    "https://hooks.slack.com/services/T***/B***/***"
  ],
  "slack_payment_succeeded": true,
  "slack_payment_failed": true,
  "email_enabled": true,
  "emails_to_notify": ["ops@example.com"],
  "email_payment_succeeded": false,
  "email_payment_failed": true,
  "email_config": {
    "from_email": "billing@example.com",
    "reply_to_email": "support@example.com",
    "email_signature_name": "John Smith",
    "email_signature_title": "Billing Department",
    "cc_recipients": ["cc1@merchant.com"],
    "bcc_recipients": ["bcc1@merchant.com"],
    "primary_color": "#FF5733",
    "background_color": "#E8E8E8",
    "text_color": "#333333"
  }
}
```

> **Warning**
>
> Slack webhook URLs are **secrets**. The `GET` response redacts each stored URL to a masked sentinel (`https://hooks.slack.com/services/T***/B***/***`) so it never exposes the raw URL. Use it only to display *that* webhooks are configured — never re-send a masked value back to the API.

## Update notification settings

Send only the fields you want to change. Omitted fields are left untouched.

```bash
curl -X PATCH https://app.paymentkit.com/api/accounts/{account_id}/notification-settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slack_enabled": true,
    "slack_webhook_urls": [
      "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    ]
  }'
```

**Settings fields:**

| Field                     | Type      | Description                                                                                                                                                                                                                         |
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoice`                 | object    | Invoice notification toggles (`on_finalized`, `on_paid`; both boolean)                                                                                                                                                              |
| `dunning`                 | object    | Dunning notification toggles (`failed_payment`; boolean)                                                                                                                                                                            |
| `slack_enabled`           | boolean   | Master switch for Slack notifications (default: `false`)                                                                                                                                                                            |
| `slack_webhook_urls`      | string\[] | One or more Slack incoming webhook URLs to post to                                                                                                                                                                                  |
| `slack_payment_succeeded` | boolean   | Post to Slack when a payment succeeds                                                                                                                                                                                               |
| `slack_payment_failed`    | boolean   | Post to Slack when a payment fails                                                                                                                                                                                                  |
| `email_enabled`           | boolean   | Master switch for team email notifications (default: `false`)                                                                                                                                                                       |
| `emails_to_notify`        | string\[] | Team email addresses that receive notifications                                                                                                                                                                                     |
| `email_payment_succeeded` | boolean   | Email your team when a payment succeeds                                                                                                                                                                                             |
| `email_payment_failed`    | boolean   | Email your team when a payment fails                                                                                                                                                                                                |
| `email_config`            | object    | Email sender, signature, copy-recipient, and color settings (`from_email`, `reply_to_email`, `email_signature_name`, `email_signature_title`, `cc_recipients`, `bcc_recipients`, `primary_color`, `background_color`, `text_color`) |

> **Warning**
>
> Because `GET` returns masked webhook URLs, only include `slack_webhook_urls` in a `PATCH` when the user has actually entered or edited a URL. To keep existing webhooks unchanged, **omit** the field entirely. The API rejects any payload containing the redaction marker `***` to prevent silently overwriting a real webhook with a masked placeholder.

## Reset notification settings

Restore notification settings to their defaults with a `DELETE`. The response returns the reset (default) settings.

```bash
curl -X DELETE https://app.paymentkit.com/api/accounts/{account_id}/notification-settings \
  -H "Authorization: Bearer sk_live_..."
```

# Email settings

## Email notifications

Configure which emails are sent to customers:

| Email                      | Default | Description                         |
| -------------------------- | ------- | ----------------------------------- |
| **Invoice created**        | Enabled | When a new invoice is generated     |
| **Invoice paid**           | Enabled | Payment confirmation receipt        |
| **Payment failed**         | Enabled | Notification when payment fails     |
| **Subscription created**   | Enabled | Welcome email for new subscriptions |
| **Subscription cancelled** | Enabled | Confirmation of cancellation        |
| **Trial ending**           | Enabled | Reminder before trial period ends   |

## Email templates

Customize the content of customer emails:

1. Navigate to **Settings > Email Templates**
2. Select the template to customize
3. Edit the subject line and body content
4. Preview and save changes

> **Note**
>
> Use template variables like `{{customer_name}}` and `{{invoice_total}}` to personalize emails.

# Checkout settings

## Payment methods

Enable the payment methods available at checkout:

* **Credit/debit cards** - Visa, Mastercard, Amex, etc.
* **Digital wallets** - Apple Pay, Google Pay
* **Bank payments** - ACH, SEPA (where supported)
* **Buy now, pay later** - Klarna, Afterpay (where supported)

> **Tip**
>
> Available payment methods depend on your connected payment processors and their capabilities.

## Checkout options

| Setting                      | Description                                   |
| ---------------------------- | --------------------------------------------- |
| **Allow promotion codes**    | Let customers enter discount codes            |
| **Collect billing address**  | Require full billing address                  |
| **Collect shipping address** | Require shipping address (for physical goods) |
| **Terms and conditions URL** | Link to your terms (shown at checkout)        |

# Team settings

## Team members

Invite team members to access your PaymentKit account:

1. Navigate to **Settings > Team**
2. Click **Invite Member**
3. Enter their email and select a role
4. They'll receive an invitation email

## Roles and permissions

| Role          | Permissions                                        |
| ------------- | -------------------------------------------------- |
| **Owner**     | Full access, can manage billing and delete account |
| **Admin**     | Full access except account deletion                |
| **Developer** | API keys, webhooks, and test mode                  |
| **Support**   | Read-only access, can issue refunds                |
| **Viewer**    | Read-only access                                   |

# API settings

## API keys

Manage your API keys:

* **Create new keys** - Generate secret and publishable keys
* **Rotate keys** - Create new keys while keeping old ones active
* **Revoke keys** - Immediately disable compromised keys

> **Note**
>
> Always use separate API keys for test and production environments. Never share secret keys.

#### [Manage API tokens programmatically](/guides/integration/api-tokens)

Create, list, update, and revoke API tokens via the API to automate provisioning and rotation.

## Webhooks

Configure webhook endpoints to receive event notifications:

#### [Set up webhooks](/guides/integration/webhooks)

Learn how to configure and secure webhook endpoints.

# Test mode

Toggle between test and live modes at the top of the dashboard:

| Mode          | Description                              |
| ------------- | ---------------------------------------- |
| **Test mode** | Use test API keys, process test payments |
| **Live mode** | Use live API keys, process real payments |

> **Tip**
>
> Always test your integration thoroughly in test mode before going live. Test mode data is separate from live data.

## Sandbox accounts

Sandbox accounts are isolated child accounts linked to a parent account, used to test integrations without touching live data. Manage them under **Settings** or via the API.

Creating and archiving sandbox accounts require a signed-in user — these endpoints reject API keys and return `400` with `"API keys not supported for this endpoint"`. Use a user session token (not an `sk_live_...` API key) in the `Authorization` header for those two operations. Listing sandbox accounts accepts either a user session token or an API key.

### List sandbox accounts

Returns a paginated response. Accepts an API key or a user session token.

```bash
curl https://app.paymentkit.com/api/accounts/{account_id}/sandbox-accounts \
  -H "Authorization: Bearer sk_live_..."
```

### Create a sandbox account

Requires a signed-in user (API keys are rejected). The request body takes a required `name` and an optional `description`. Returns the created sandbox account object.

```bash
curl -X POST https://app.paymentkit.com/api/accounts/{account_id}/sandbox-accounts \
  -H "Authorization: Bearer <user_session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "QA sandbox", "description": "Integration testing" }'
```

### Archive a sandbox account

Requires a signed-in user (API keys are rejected). Archiving hides a sandbox from the UI and blocks further access. The underlying data is **preserved** in the database, not deleted.

```bash
curl -X POST https://app.paymentkit.com/api/accounts/{account_id}/sandbox-accounts/{sandbox_id}/archive \
  -H "Authorization: Bearer <user_session_token>"
```

A successful archive returns `204 No Content`.

> **Warning**
>
> Archiving a sandbox account is a **one-way** operation — the sandbox cannot be un-archived or accessed again afterward.

---