Upgrade to an easier 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, 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.

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
• KakaoPay
• Samsung Pay
• Payco
• Korean local cards

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.

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.

Previous workflow

Customer selects "Korean payment methods"

Customer chooses Naver Pay

Customer authenticates

Checkout complete

New workflow

Customer chooses Naver Pay directly on the checkout page

Customer authenticates

Checkout complete

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

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 to include the new payment method types. We recommend updating for the best integration experience.

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

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 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, you can get the latest payment method types by updating the payment method details component:

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

Review Korean local card subscription renewals

Customers can use Korean local cards 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

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 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.