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. The previous customer experience is now deprecated.
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:
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've been automatically opted in to the five new direct payment methods if you had Korean payment methods enabled. 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 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_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.
We've updated 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 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 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:
121git fetch upstream
2git checkout upstream/main -- src/components/dashboard/subscriptions/components/payment-method-details.tsxView the payment method details component on GitHub.
3Review 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.
4Test 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.