Action required
Upgrade to an easier payment experience for Korean customers
Korean payment methods like KakaoPay and Naver Pay will appear as individual options at checkout, providing a smoother payment experience for Korean customers. The previous customer experience is being deprecated, so you may need to make changes to your integration.
What's new?
We're improving the Korean payment experience by presenting payment methods as individual options directly on Paddle Checkout. This means customers can pay with Naver Pay, KakaoPay, Samsung Pay, Payco, and Korean local cards without having to select "Korean payment methods" first.
We've updated the Paddle API to return the new payment method types when customers pay with Korean payment methods. This change is available on sandbox accounts now, and will be released on live accounts on November 18, 2025. You'll be automatically opted in to avoid any impact on your revenue.
How it works
South Korea is one of the fastest-growing major economies, with a highly urbanized and tech-savvy population. It has its own unique payments market, with nine main local card networks — alternatives to Visa, Mastercard, and other international networks — and local digital wallets built into chat or other apps.
With our existing Korean payment methods workflow, customers select "Korean payment methods" then choose their preferred method on an intermediary screen. You can toggle all Korean payment methods in the dashboard, but you can't toggle individual Korean payment methods.
We're rolling out a new workflow that shows Korean payment methods as individual options directly on Paddle Checkout:
This creates a smoother, more intuitive payment experience for customers in Korea. You can turn these options on or off in the dashboard, giving you more granular control over which Korean payment methods to offer.
Example
This example shows how the new checkout workflow looks for Naver Pay, but the workflow is the same for all of the new direct Korean payment methods.
Summary of changes
API and webhooks
This is a summary of the changes to fields in the Paddle API and webhooks.
Transaction entity
| Field | Change | Notes |
|---|---|---|
payments[].method_details.type | New allowed values | Returns south_korea_local_card, kakao_pay, naver_pay, samsung_pay, and payco for Korean payment methods. |
payments[].method_details.type | Deprecated allowed value | korea_local no longer returned for new entities. |
payments[].method_details.south_korea_local_card | New field | Returns information about the Korean local card used to pay. |
payments[].method_details.underlying_details | Deprecated field | underlying_details is now deprecated. |
Transaction preview object
| Field | Change | Notes |
|---|---|---|
available_payment_methods | New allowed values | Returns south_korea_local_card, kakao_pay, naver_pay, samsung_pay, and payco for Korean payment methods. |
available_payment_methods | Deprecated allowed value | korea_local no longer returned. |
Paddle.js
When calling Paddle.Initialize() or Paddle.Checkout.open(), the checkout settings object now accepts the new payment method types.
| Parameter | Change | Notes |
|---|---|---|
allowedPaymentMethods | New allowed values | south_korea_local_card, kakao_pay, naver_pay, samsung_pay, and payco for Korean payment methods. |
allowedPaymentMethods | Deprecated allowed value | korea_local no longer a valid value. |
Implementation details
We're deprecating the previous workflow and the single "Korean payment methods" option in favor of the new workflow and the five new direct payment methods.
To avoid disruption to your revenue, you'll automatically be opted in to the five new direct payment methods. This means that customers in Korea can still make purchases using payment methods that are familiar to them, with an improved checkout experience that's designed to increase conversion rates.
Do you need to take action?
In most cases, we don't anticipate that you'll need to make any changes to your integration. However, if you've built more advanced workflows or custom billing information screens, you'll need to review and update them to support the new payment method types.
Use this checklist to determine if you need to make changes:
Minimal or no action needed
You only use Paddle Checkout and the Paddle-hosted customer portal
You don't have custom logic for Korean payment methods
You don't store or process payment method types in your database
You don't rely on
korea_localin data reporting, analytics, or business intelligence pipelines
Review and potentially update
1Update your SDKs and Paddle.js package
Our SDKs are built to handle new unknown values and keys gracefully, so they shouldn't break.
In the coming days, we'll update our SDKs and Paddle.js package to include the new payment method types. We recommend updating for the best integration experience.
| Library | Example update command |
|---|---|
| Paddle.js | npm install @paddle/paddle-js@latest |
| Node.js | npm install @paddle/paddle-node-sdk@latest |
| Python | pip install --upgrade paddle-python-sdk |
| Go | go get -u github.com/PaddleHQ/paddle-go-sdk |
| PHP | composer update paddle/paddle-php-sdk |
Review the full list of changes in the CHANGELOG.md file in each SDK repository on GitHub as there may be other changes since you last updated.
2Review and update subscription and billing workflows
We've made changes to the transaction.payments[].method_details object in the Paddle API and webhooks to support the new payment methods. You can find full details in Summary of changes (above)
You should check:
Custom billing information screens.
If you present users with details about their payment method in billing information screens or other workflows, you may need to update them to show the new payment method types. If you've integrated using the customer portal, you don't need to make any changes — it supports all the new types.
Fulfillment workflows.
If you've built fulfillment workflows specifically for Korean payment methods, you'll need to update to use the new payment method types instead.
Data reporting pipelines.
If you use
korea_localas part of data reporting pipelines, you'll need to update them to use the new payment method types too.
3Review Korean local card subscription renewals
Customers can use Korean local cards to pay for subscriptions. After we deprecate the previous korea_local payment method type, new transactions for subscription renewals, upgrades and downgrades, one-time charges, and other changes will use south_korea_local_card instead.
There's no disruption to customers paying with Korean local cards or impact on your revenue. Customers will continue to be charged using the Korean local card they saved when they signed up for the subscription.
If you store the payment method type for a subscription in your database, update it when you receive related transaction webhooks after the deprecation date.
There's a new south_korea_local_card object that returns details about the Korean local card used to pay, like the last 4 digits of the card number and the card brand.
4Test on sandbox
We've enabled the new payment methods on all sandbox accounts ahead of the release on live accounts on November 18, 2025 so you can test before going to production.
Before the go-live date, test the new payment method types in sandbox:
- Open Paddle Checkout and take a test payment using the test details for the new payment method types.
- Use webhook simulator to test subscription renewals and other subscription lifecycle events for the new payment method types.
Next steps
This change is available on sandbox accounts now. It's scheduled to be released to live accounts on November 18, 2025. We've emailed users who have Korean payment methods enabled to let them know that they may need to make changes to their integration.
To avoid impacting your revenue, you'll automatically be opted in to the five new direct payment methods when we deprecate the previous workflow. Customers paying for subscriptions using Korean local cards won't experience any disruption or difference in the way they pay.
It's a backwards compatible change, meaning that historic transactions are not impacted. However, new transactions will return the new payment method types.
For help, contact our seller support team.