Configure account settings

Once a seller exists, configure account-level settings for them.

We recommend automatically configuring these settings as part of the onboarding process. You should also make these settings available to your platform agent, so your agent can change these settings based on changes the user makes.

Overview

Configure a seller account in three steps:

1. Update account settings, including default payment link
   Update the account settings for the seller's account. This includes the default payment link, which is required to open a checkout.
2. Set statement descriptor
   Update the name that customers see on their bank statement after making a purchase.
3. Enable payment methods Optional
   Choose the payment methods you want to offer to customers on the seller's checkout.

Account settings

Layer

Your platform, Your agent

Authentication

Seller API key

Environment

Sandbox, Live

The account settings endpoint lets you configure:

• Default payment link
• Whether prices are inclusive or exclusive of tax by default
• Primary brand color for checkout
• Whether customers can save payment methods

Use sensible defaults

We recommend automatically configuring these settings as part of the onboarding process using details you know about the user. You don't typically need to open a modal or present a workflow in your frontend.

Recommended defaults:

• Use location for whether prices are inclusive or exclusive of tax. This automatically presents prices as tax inclusive or exclusive based on the customer's region. For example, customers in the United States see prices exclusive of tax, and customers in Europe see them inclusive of tax.
• Infer primary brand color from a seller's app brand palette.
• Opt in to letting customers save payment methods. This improves conversion for repeat customers.

Set default payment link on sandbox

Setting a default payment link is required for opening a checkout on both sandbox and live. If not set, Paddle Checkout fails to launch with an error that says "Something went wrong."

When you onboard a seller initially, set the default payment link for sandbox only. You should come back to the default payment link for live when you're ready to take the seller live.

• On sandbox, you can set any URL as the default payment link. This includes localhost or a user's homepage. Paddle doesn't require approval for this link.
• On live, you must get the default payment link domain approved first. Paddle's automated systems review the domain before a checkout can be opened.

While a user is building out their integration using sandbox, they might not have deployed their app or have finished building it. This means that automated domain review would likely fail, so it's best to wait until you're ready to take a user live.

Send requests

Build a payload with the settings you want to configure for a seller, then send a PATCH request to the /settings/account endpoint.

Make this request to both the sandbox and live endpoints, but omit default_checkout_url on live.

If successful, Paddle responds with the updated settings for a seller.

{
  "default_checkout_url": "https://example.com/checkout",
  "default_tax_mode": "location",
  "primary_checkout_color": "#f0f0f0",
  "saved_payment_methods_enabled": true
}

{
  "data": {
    "default_checkout_url": "https://example.com/checkout",
    "default_tax_mode": "location",
    "primary_checkout_color": "#f0f0f0",
    "saved_payment_methods_enabled": true
  },
  "meta": {
    "request_id": "8295b301-8306-436d-813a-55f6ed03ccf8"
  }
}

Set statement descriptor

Layer

Your platform, Your agent

Authentication

Seller API key

Environment

Sandbox, Live

The bank statement descriptor is the name that customers see on their bank statement after making a purchase. The format is:

We recommend automatically setting this as part of the onboarding process using the seller's app name. You don't typically need to open a modal or present a workflow in your frontend. You should confirm the name that appears on the statement as part of the go-live process in the chat.

When setting a statement descriptor name, you should check:

• Length: 2-10 characters.
• Allowed characters: letters, digits, period, space. No other punctuation. For example, O'BRIEN is rejected for the apostrophe.
• Must contain at least one letter. Pure-digit values are rejected.

Build a payload with the name you want to use, then send a PATCH request to the /settings/statement-descriptor endpoint. Make this request to both the sandbox and live endpoints.

Only name can be set. The other fields are returned for your reference.

If successful, Paddle responds with the updated statement descriptor settings for a seller.

{
  "name": "AeroEdit"
}

{
  "data": {
    "name": "AeroEdit",
    "prefix": "PADDLE*",
    "paypal_override": "PAYPAL *PADDLE.NET"
  },
  "meta": {
    "request_id": "9a4ae02c-7d0f-4d2b-950d-b87e6f9fad7e"
  }
}

Enable payment methods Optional

Layer

Your platform, Your agent

Authentication

Seller API key

Environment

Sandbox, Live

As well as cards, Paddle supports a number of popular digital wallets and local payment methods. As a merchant of record, payment methods can be turned on or off without any integration changes, and with no need to sign up for payment platform accounts.

We recommend enabling all payment methods by default for the best conversion rates. You don't need to present this information to your user in a modal or workflow in your frontend.

Build a payload with the payment methods you want to enable for a seller, then send a PATCH request to the /settings/payment-methods endpoint. Make this request to both the sandbox and live endpoints.

If successful, Paddle responds with the updated payment method settings for a seller.

{
  "alipay": { "enabled_for_checkout": true },
  "apple_pay": { "enabled_for_checkout": true },
  "bancontact": { "enabled_for_checkout": true },
  "blik": { "enabled_for_checkout": true },
  "card": { "enabled_for_checkout": true },
  "google_pay": { "enabled_for_checkout": true },
  "ideal": { "enabled_for_checkout": true },
  "kakao_pay": { "enabled_for_checkout": true },
  "mb_way": { "enabled_for_checkout": true },
  "naver_pay": { "enabled_for_checkout": true },
  "payco": { "enabled_for_checkout": true },
  "paypal": { "enabled_for_checkout": true },
  "pix": { "enabled_for_checkout": true },
  "samsung_pay": { "enabled_for_checkout": true },
  "south_korea_local_card": { "enabled_for_checkout": true },
  "upi": { "enabled_for_checkout": true },
  "wechat_pay": { "enabled_for_checkout": true }
}

{
  "data": {
    "alipay": { "enabled_for_checkout": true },
    "apple_pay": { "enabled_for_checkout": true },
    "bancontact": { "enabled_for_checkout": true },
    "blik": { "enabled_for_checkout": true },
    "card": { "enabled_for_checkout": true },
    "google_pay": { "enabled_for_checkout": true },
    "ideal": { "enabled_for_checkout": true },
    "kakao_pay": { "enabled_for_checkout": true },
    "mb_way": { "enabled_for_checkout": true },
    "naver_pay": { "enabled_for_checkout": true },
    "payco": { "enabled_for_checkout": true },
    "paypal": { "enabled_for_checkout": true },
    "pix": { "enabled_for_checkout": true },
    "samsung_pay": { "enabled_for_checkout": true },
    "south_korea_local_card": { "enabled_for_checkout": true },
    "upi": { "enabled_for_checkout": true },
    "wechat_pay": { "enabled_for_checkout": true }
  },
  "meta": {
    "request_id": "6ef0b943-8c34-4ded-9107-7458c9e0d3fe"
  }
}