> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Upgrade to an easier payment experience for Korean customers

Korean payment methods like KakaoPay and Naver Pay now appear as individual options at checkout, providing a smoother payment experience for Korean customers.

---

## What's new?

We've improving the Korean payment experience by presenting payment methods as individual options directly on Paddle Checkout. This means customers can pay with [Naver Pay](https://developer.paddle.com/concepts/payment-methods/korean/naver-pay.md), [KakaoPay](https://developer.paddle.com/concepts/payment-methods/korean/kakaopay.md), [Samsung Pay](https://developer.paddle.com/concepts/payment-methods/korean/samsung-pay.md), [Payco](https://developer.paddle.com/concepts/payment-methods/korean/payco.md), and [Korean local cards](https://developer.paddle.com/concepts/payment-methods/korean/local-cobranded-cards.md) 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.

## 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 previous Korean payment methods workflow, customers selected "Korean payment methods" then chose their preferred method on an intermediary screen. You could toggle all Korean payment methods in the dashboard, but you couldn't toggle individual Korean payment methods.

We've rolled out a new workflow that shows Korean payment methods as individual options directly on Paddle Checkout:

* [Naver Pay](https://developer.paddle.com/concepts/payment-methods/korean/naver-pay.md)
* [KakaoPay](https://developer.paddle.com/concepts/payment-methods/korean/kakaopay.md)
* [Samsung Pay](https://developer.paddle.com/concepts/payment-methods/korean/samsung-pay.md)
* [Payco](https://developer.paddle.com/concepts/payment-methods/korean/payco.md)
* [Korean local cards](https://developer.paddle.com/concepts/payment-methods/korean/local-cobranded-cards.md)

This creates a smoother, more intuitive payment experience for customers in South Korea. You can turn these options on or off in the dashboard, giving you more granular control over which Korean payment methods to offer.

{% callout type="info" %}
To avoid any impact on your revenue, you've been automatically opted in to the five new direct payment methods if you had Korean payment methods enabled. New values are returned for `type` for each of the new payment methods, which you may need to handle in your integration.
{% /callout %}

## Example

This example shows how the new checkout workflow looks for [Naver Pay](https://developer.paddle.com/concepts/payment-methods/korean/naver-pay.md), but the workflow is the same for all of the new direct Korean payment methods.

{% journey-comparison %}

{% comparison-column title="Previous workflow" %}

{% comparison-step title="Customer selects \"Korean payment methods\"" %}

{% /comparison-step %}

{% comparison-step title="Customer chooses Naver Pay" %}

{% /comparison-step %}

{% comparison-step title="Customer authenticates" %}

{% /comparison-step %}

{% comparison-step title="Checkout complete" %}

{% /comparison-step %}

{% /comparison-column %}

{% comparison-column title="New workflow" %}

{% comparison-step title="Customer chooses Naver Pay directly on the checkout page" %}

{% /comparison-step %}

{% comparison-step title="Customer authenticates" %}

{% /comparison-step %}

{% comparison-step title="Checkout complete" %}

{% /comparison-step %}

{% /comparison-column %}

{% /journey-comparison %}

## 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've been automatically opted in to the five new direct payment methods if you had Korean payment methods enabled. This means that customers in South 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 need to make any changes to your integration. However, if you've built more advanced workflows or custom billing information screens, you 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_local` in data reporting, analytics, or business intelligence pipelines

### Review and potentially update

* You've built custom billing information screens that display payment method details
* You have fulfillment or provisioning workflows that check for `korea_local`
* You store payment method types in your database for active subscriptions
* You use `korea_local` in data reporting, analytics, or business intelligence pipelines

### Update your SDKs and Paddle.js package {% step=true %}

Our SDKs are built to handle new unknown values and keys gracefully, so they shouldn't break.

We've updated [our SDKs and Paddle.js package](https://developer.paddle.com/resources/overview.md) to include the new payment method types. We recommend updating for the best integration experience.

| Library                                                    | Example update command                        |
| ---------------------------------------------------------- | --------------------------------------------- |
| [Paddle.js](https://github.com/PaddleHQ/paddle-js-wrapper) | `npm install @paddle/paddle-js@latest`        |
| [Node.js](https://github.com/PaddleHQ/paddle-node-sdk)     | `npm install @paddle/paddle-node-sdk@latest`  |
| [Python](https://github.com/PaddleHQ/paddle-python-sdk)    | `pip install --upgrade paddle-python-sdk`     |
| [Go](https://github.com/PaddleHQ/paddle-go-sdk)            | `go get -u github.com/PaddleHQ/paddle-go-sdk` |
| [PHP](https://github.com/PaddleHQ/paddle-php-sdk)          | `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.

### Review and update subscription and billing workflows {% step=true %}

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)](#change-fields)

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](https://developer.paddle.com/concepts/customer-portal.md), 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 need to update to use the new payment method types instead.
* **Data reporting pipelines.**  
   If you use `korea_local` as part of data reporting pipelines, you need to update them to use the new payment method types too.

If you [forked the Next.js starter kit](https://github.com/PaddleHQ/paddle-nextjs-starter-kit), you can get the latest payment method types by updating the payment method details component:

```bash
git fetch upstream
git checkout upstream/main -- src/components/dashboard/subscriptions/components/payment-method-details.tsx
```

View the payment method details component on GitHub.

[Learn more](https://github.com/PaddleHQ/paddle-nextjs-starter-kit/blob/main/src/components/dashboard/subscriptions/components/payment-method-details.tsx)

### Review Korean local card subscription renewals {% step=true %}

Customers can use [Korean local cards](https://developer.paddle.com/concepts/payment-methods/korean/local-cobranded-cards.md) to pay for subscriptions. Now that we've deprecated the previous `korea_local` payment method type, new transactions for subscription renewals, upgrades and downgrades, one-time charges, and other changes 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.

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.

### Test on sandbox {% step=true %}

Test the new payment method types in sandbox:

* Open [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md) and take a test payment using the test details for the [new payment method types](https://developer.paddle.com/concepts/payment-methods/overview#list-korean-market.md).
* Use [webhook simulator](https://developer.paddle.com/webhooks/test-webhooks.md) to test subscription renewals and other subscription lifecycle events for the new payment method types.

## Next steps

This change is available on all accounts now. It was released to sandbox accounts ahead of the release on live accounts, giving you time to test before going to production. We emailed users who had Korean payment methods enabled to let them know that they may need to make changes to their integration ahead of the release on live accounts.

To avoid impacting your revenue, you've been automatically opted in to the five new direct payment methods when we deprecated 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 backward compatible change, meaning that historic transactions aren't impacted. However, new transactions return the new payment method types.

For help, contact our [seller support team](mailto:sellers@paddle.com).
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `payments[].method_details.type` | Enum value | added | Transaction | Returns south_korea_local_card, kakao_pay, naver_pay, samsung_pay, and payco for Korean payment methods. |
| `payments[].method_details.type` | Enum value | deprecated | Transaction | korea_local no longer returned for new entities. |
| `payments[].method_details.south_korea_local_card` | Field | added | Transaction | Returns information about the Korean local card used to pay. |
| `payments[].method_details.underlying_details` | Field | deprecated | Transaction | underlying_details is now deprecated. |
| `available_payment_methods` | Enum value | added | Transaction | Returns south_korea_local_card, kakao_pay, naver_pay, samsung_pay, and payco for Korean payment methods. |
| `available_payment_methods` | Enum value | deprecated | Transaction | korea_local no longer returned. |
| `allowedPaymentMethods` | Enum value | added | Paddle.Checkout.open() | south_korea_local_card, kakao_pay, naver_pay, samsung_pay, and payco for Korean payment methods. |
| `allowedPaymentMethods` | Enum value | deprecated | Paddle.Checkout.open() | korea_local no longer a valid value. |