feat: Added additional support for local Korean payment methods

CHANGELOG.md

@@ -10,12 +10,18 @@ Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx
 
 ### Added
 
+- Added additional support for local Korean payment methods. See [related changelog](https://developer.paddle.com/changelog/2025/improved-korean-payment-methods?utm_source=dx&utm_medium=paddle-python-sdk)
 - Support for payout reconciliation reports and `remittance_reference`, see [changelog](https://developer.paddle.com/changelog/2025/payout-reconciliation-report?utm_source=dx&utm_medium=paddle-python-sdk)
 - Added `location` value for `price.tax_mode`, see [changelog](https://developer.paddle.com/changelog/2025/default-automatic-tax-setting?utm_source=dx&utm_medium=paddle-python-sdk)
 
 ### Fixed
 - Fixed `ReportsClient.create()` operation type
 
+### Deprecated
+
+- `korea_local` payment method type is deprecated. Use `south_korea_local_card`, `kakao_pay`, `naver_pay`, `payco`, or `samsung_pay` instead.
+- `underlying_details` is deprecated on `method_details` and saved `payment_method` responses. Use specific payment method fields such as `south_korea_local_card`.
+
 ## 1.11.0 - 2025-10-07
 
 ### Added

paddle_billing/Entities/PaymentMethod.py

@@ -10,6 +10,7 @@
     Paypal,
     SavedPaymentMethodOrigin,
     SavedPaymentMethodType,
+    SouthKoreaLocalCard,
 )
 
 
@@ -24,7 +25,8 @@ class PaymentMethod(Entity):
     origin: SavedPaymentMethodOrigin
     saved_at: datetime
     updated_at: datetime
-    underlying_details: PaymentMethodUnderlyingDetails | None
+    underlying_details: PaymentMethodUnderlyingDetails | None  # deprecated
+    south_korea_local_card: SouthKoreaLocalCard | None
 
     @staticmethod
     def from_dict(data: dict[str, Any]) -> PaymentMethod:
@@ -43,4 +45,9 @@ def from_dict(data: dict[str, Any]) -> PaymentMethod:
             origin=SavedPaymentMethodOrigin(data["origin"]),
             saved_at=datetime.fromisoformat(data["saved_at"]),
             updated_at=datetime.fromisoformat(data["updated_at"]),
+            south_korea_local_card=(
+                SouthKoreaLocalCard.from_dict(data["south_korea_local_card"])
+                if data.get("south_korea_local_card")
+                else None
+            ),
         )

paddle_billing/Entities/Shared/MethodDetails.py

@@ -5,13 +5,15 @@
 from paddle_billing.Entities.Shared.Card import Card
 from paddle_billing.Entities.Shared.PaymentMethodType import PaymentMethodType
 from paddle_billing.Entities.Shared.PaymentMethodUnderlyingDetails import PaymentMethodUnderlyingDetails
+from paddle_billing.Entities.Shared.SouthKoreaLocalCard import SouthKoreaLocalCard
 
 
 @dataclass
 class MethodDetails:
     type: PaymentMethodType
     card: Card | None
-    underlying_details: PaymentMethodUnderlyingDetails | None
+    underlying_details: PaymentMethodUnderlyingDetails | None  # deprecated
+    south_korea_local_card: SouthKoreaLocalCard | None
 
     @staticmethod
     def from_dict(data: dict[str, Any]) -> MethodDetails:
@@ -23,4 +25,9 @@ def from_dict(data: dict[str, Any]) -> MethodDetails:
                 if data.get("underlying_details")
                 else None
             ),
+            (
+                SouthKoreaLocalCard.from_dict(data["south_korea_local_card"])
+                if data.get("south_korea_local_card")
+                else None
+            ),
         )

paddle_billing/Entities/Shared/PaymentMethodType.py

@@ -9,11 +9,16 @@ class PaymentMethodType(PaddleStrEnum, metaclass=PaddleStrEnumMeta):
     Card: "PaymentMethodType" = "card"
     GooglePay: "PaymentMethodType" = "google_pay"
     Ideal: "PaymentMethodType" = "ideal"
+    KakaoPay: "PaymentMethodType" = "kakao_pay"
     KoreaLocal: "PaymentMethodType" = "korea_local"
     MbWay: "PaymentMethodType" = "mb_way"
+    NaverPay: "PaymentMethodType" = "naver_pay"
     Offline: "PaymentMethodType" = "offline"
+    Payco: "PaymentMethodType" = "payco"
     Paypal: "PaymentMethodType" = "paypal"
     Pix: "PaymentMethodType" = "pix"
+    SamsungPay: "PaymentMethodType" = "samsung_pay"
+    SouthKoreaLocalCard: "PaymentMethodType" = "south_korea_local_card"
     Unknown: "PaymentMethodType" = "unknown"
     Upi: "PaymentMethodType" = "upi"
     WireTransfer: "PaymentMethodType" = "wire_transfer"

paddle_billing/Entities/Shared/SavedPaymentMethodType.py

@@ -7,8 +7,13 @@ class SavedPaymentMethodType(PaddleStrEnum, metaclass=PaddleStrEnumMeta):
     Blik: "SavedPaymentMethodType" = "blik"
     Card: "SavedPaymentMethodType" = "card"
     GooglePay: "SavedPaymentMethodType" = "google_pay"
+    KakaoPay: "SavedPaymentMethodType" = "kakao_pay"
     KoreaLocal: "SavedPaymentMethodType" = "korea_local"
     MbWay: "SavedPaymentMethodType" = "mb_way"
+    NaverPay: "SavedPaymentMethodType" = "naver_pay"
+    Payco: "SavedPaymentMethodType" = "payco"
     Paypal: "SavedPaymentMethodType" = "paypal"
     Pix: "SavedPaymentMethodType" = "pix"
+    SamsungPay: "SavedPaymentMethodType" = "samsung_pay"
+    SouthKoreaLocalCard: "SavedPaymentMethodType" = "south_korea_local_card"
     Upi: "SavedPaymentMethodType" = "upi"

paddle_billing/Entities/Shared/SouthKoreaLocalCard.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+
+from paddle_billing.Entities.Shared.SouthKoreaLocalCardType import SouthKoreaLocalCardType
+
+
+@dataclass
+class SouthKoreaLocalCard:
+    type: SouthKoreaLocalCardType
+    last4: str
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> SouthKoreaLocalCard:
+        return SouthKoreaLocalCard(
+            type=SouthKoreaLocalCardType(data["type"]),
+            last4=data["last4"],
+        )

paddle_billing/Entities/Shared/SouthKoreaLocalCardType.py

@@ -0,0 +1,27 @@
+from paddle_billing.PaddleStrEnum import PaddleStrEnum, PaddleStrEnumMeta
+
+
+class SouthKoreaLocalCardType(PaddleStrEnum, metaclass=PaddleStrEnumMeta):
+    BC: "SouthKoreaLocalCardType" = "bc"
+    Citi: "SouthKoreaLocalCardType" = "citi"
+    Hana: "SouthKoreaLocalCardType" = "hana"
+    Hyundai: "SouthKoreaLocalCardType" = "hyundai"
+    Jeju: "SouthKoreaLocalCardType" = "jeju"
+    Jeonbuk: "SouthKoreaLocalCardType" = "jeonbuk"
+    KakaoBank: "SouthKoreaLocalCardType" = "kakaobank"
+    KBank: "SouthKoreaLocalCardType" = "kbank"
+    KDBBank: "SouthKoreaLocalCardType" = "kdbbank"
+    Kookmin: "SouthKoreaLocalCardType" = "kookmin"
+    Kwangju: "SouthKoreaLocalCardType" = "kwangju"
+    Lotte: "SouthKoreaLocalCardType" = "lotte"
+    MG: "SouthKoreaLocalCardType" = "mg"
+    NH: "SouthKoreaLocalCardType" = "nh"
+    Post: "SouthKoreaLocalCardType" = "post"
+    Samsung: "SouthKoreaLocalCardType" = "samsung"
+    SavingsBank: "SouthKoreaLocalCardType" = "savingsbank"
+    Shinhan: "SouthKoreaLocalCardType" = "shinhan"
+    Shinhyup: "SouthKoreaLocalCardType" = "shinhyup"
+    Suhyup: "SouthKoreaLocalCardType" = "suhyup"
+    TossBank: "SouthKoreaLocalCardType" = "tossbank"
+    Unknown: "SouthKoreaLocalCardType" = "unknown"
+    Woori: "SouthKoreaLocalCardType" = "woori"

paddle_billing/Entities/Shared/__init__.py

@@ -35,6 +35,8 @@
 from paddle_billing.Entities.Shared.PaymentAttemptStatus import PaymentAttemptStatus
 from paddle_billing.Entities.Shared.PaymentMethodType import PaymentMethodType
 from paddle_billing.Entities.Shared.PaymentMethodUnderlyingDetails import PaymentMethodUnderlyingDetails
+from paddle_billing.Entities.Shared.SouthKoreaLocalCard import SouthKoreaLocalCard
+from paddle_billing.Entities.Shared.SouthKoreaLocalCardType import SouthKoreaLocalCardType
 from paddle_billing.Entities.Shared.PayoutTotalsAdjustment import PayoutTotalsAdjustment
 from paddle_billing.Entities.Shared.Paypal import Paypal
 from paddle_billing.Entities.Shared.PriceQuantity import PriceQuantity

paddle_billing/Notifications/Entities/Shared/MethodDetails.py

@@ -5,13 +5,15 @@
 from paddle_billing.Notifications.Entities.Shared.Card import Card
 from paddle_billing.Notifications.Entities.Shared.PaymentMethodType import PaymentMethodType
 from paddle_billing.Notifications.Entities.Shared.PaymentMethodUnderlyingDetails import PaymentMethodUnderlyingDetails
+from paddle_billing.Notifications.Entities.Shared.SouthKoreaLocalCard import SouthKoreaLocalCard
 
 
 @dataclass
 class MethodDetails:
     type: PaymentMethodType
     card: Card | None
-    underlying_details: PaymentMethodUnderlyingDetails | None
+    underlying_details: PaymentMethodUnderlyingDetails | None  # deprecated
+    south_korea_local_card: SouthKoreaLocalCard | None
 
     @staticmethod
     def from_dict(data: dict[str, Any]) -> MethodDetails:
@@ -23,4 +25,9 @@ def from_dict(data: dict[str, Any]) -> MethodDetails:
                 if data.get("underlying_details")
                 else None
             ),
+            (
+                SouthKoreaLocalCard.from_dict(data["south_korea_local_card"])
+                if data.get("south_korea_local_card")
+                else None
+            ),
         )

paddle_billing/Notifications/Entities/Shared/PaymentMethodType.py

@@ -9,11 +9,16 @@ class PaymentMethodType(PaddleStrEnum, metaclass=PaddleStrEnumMeta):
     Card: "PaymentMethodType" = "card"
     GooglePay: "PaymentMethodType" = "google_pay"
     Ideal: "PaymentMethodType" = "ideal"
+    KakaoPay: "PaymentMethodType" = "kakao_pay"
     KoreaLocal: "PaymentMethodType" = "korea_local"
     MbWay: "PaymentMethodType" = "mb_way"
+    NaverPay: "PaymentMethodType" = "naver_pay"
     Offline: "PaymentMethodType" = "offline"
+    Payco: "PaymentMethodType" = "payco"
     Paypal: "PaymentMethodType" = "paypal"
     Pix: "PaymentMethodType" = "pix"
+    SamsungPay: "PaymentMethodType" = "samsung_pay"
+    SouthKoreaLocalCard: "PaymentMethodType" = "south_korea_local_card"
     Unknown: "PaymentMethodType" = "unknown"
     Upi: "PaymentMethodType" = "upi"
     WireTransfer: "PaymentMethodType" = "wire_transfer"

paddle_billing/Notifications/Entities/Shared/SavedPaymentMethodType.py

@@ -7,8 +7,13 @@ class SavedPaymentMethodType(PaddleStrEnum, metaclass=PaddleStrEnumMeta):
     Blik: "SavedPaymentMethodType" = "blik"
     Card: "SavedPaymentMethodType" = "card"
     GooglePay: "SavedPaymentMethodType" = "google_pay"
+    KakaoPay: "SavedPaymentMethodType" = "kakao_pay"
     KoreaLocal: "SavedPaymentMethodType" = "korea_local"
     MbWay: "SavedPaymentMethodType" = "mb_way"
+    NaverPay: "SavedPaymentMethodType" = "naver_pay"
+    Payco: "SavedPaymentMethodType" = "payco"
     Paypal: "SavedPaymentMethodType" = "paypal"
     Pix: "SavedPaymentMethodType" = "pix"
+    SamsungPay: "SavedPaymentMethodType" = "samsung_pay"
+    SouthKoreaLocalCard: "SavedPaymentMethodType" = "south_korea_local_card"
     Upi: "SavedPaymentMethodType" = "upi"

paddle_billing/Notifications/Entities/Shared/SouthKoreaLocalCard.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+
+from paddle_billing.Notifications.Entities.Shared.SouthKoreaLocalCardType import SouthKoreaLocalCardType
+
+
+@dataclass
+class SouthKoreaLocalCard:
+    type: SouthKoreaLocalCardType
+    last4: str
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> SouthKoreaLocalCard:
+        return SouthKoreaLocalCard(
+            type=SouthKoreaLocalCardType(data["type"]),
+            last4=data["last4"],
+        )

paddle_billing/Notifications/Entities/Shared/SouthKoreaLocalCardType.py

@@ -0,0 +1,27 @@
+from paddle_billing.PaddleStrEnum import PaddleStrEnum, PaddleStrEnumMeta
+
+
+class SouthKoreaLocalCardType(PaddleStrEnum, metaclass=PaddleStrEnumMeta):
+    BC: "SouthKoreaLocalCardType" = "bc"
+    Citi: "SouthKoreaLocalCardType" = "citi"
+    Hana: "SouthKoreaLocalCardType" = "hana"
+    Hyundai: "SouthKoreaLocalCardType" = "hyundai"
+    Jeju: "SouthKoreaLocalCardType" = "jeju"
+    Jeonbuk: "SouthKoreaLocalCardType" = "jeonbuk"
+    KakaoBank: "SouthKoreaLocalCardType" = "kakaobank"
+    KBank: "SouthKoreaLocalCardType" = "kbank"
+    KDBBank: "SouthKoreaLocalCardType" = "kdbbank"
+    Kookmin: "SouthKoreaLocalCardType" = "kookmin"
+    Kwangju: "SouthKoreaLocalCardType" = "kwangju"
+    Lotte: "SouthKoreaLocalCardType" = "lotte"
+    MG: "SouthKoreaLocalCardType" = "mg"
+    NH: "SouthKoreaLocalCardType" = "nh"
+    Post: "SouthKoreaLocalCardType" = "post"
+    Samsung: "SouthKoreaLocalCardType" = "samsung"
+    SavingsBank: "SouthKoreaLocalCardType" = "savingsbank"
+    Shinhan: "SouthKoreaLocalCardType" = "shinhan"
+    Shinhyup: "SouthKoreaLocalCardType" = "shinhyup"
+    Suhyup: "SouthKoreaLocalCardType" = "suhyup"
+    TossBank: "SouthKoreaLocalCardType" = "tossbank"
+    Unknown: "SouthKoreaLocalCardType" = "unknown"
+    Woori: "SouthKoreaLocalCardType" = "woori"

paddle_billing/Notifications/Entities/Shared/__init__.py

@@ -27,6 +27,8 @@
 from paddle_billing.Notifications.Entities.Shared.Original import Original
 from paddle_billing.Notifications.Entities.Shared.PaymentAttemptStatus import PaymentAttemptStatus
 from paddle_billing.Notifications.Entities.Shared.PaymentMethodType import PaymentMethodType
+from paddle_billing.Notifications.Entities.Shared.SouthKoreaLocalCard import SouthKoreaLocalCard
+from paddle_billing.Notifications.Entities.Shared.SouthKoreaLocalCardType import SouthKoreaLocalCardType
 from paddle_billing.Notifications.Entities.Shared.PayoutTotalsAdjustment import PayoutTotalsAdjustment
 from paddle_billing.Notifications.Entities.Shared.Paypal import Paypal
 from paddle_billing.Notifications.Entities.Shared.PriceQuantity import PriceQuantity

tests/Functional/Resources/PaymentMethods/_fixtures/response/full_entity_card.json

@@ -12,6 +12,7 @@
         "cardholder_name": "Sam Miller"
       },
       "paypal": null,
+      "south_korea_local_card": null,
       "origin": "subscription",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-04T11:50:23.422Z",

tests/Functional/Resources/PaymentMethods/_fixtures/response/full_entity_korea_local.json

@@ -7,6 +7,7 @@
         "type": "korea_local",
         "card": null,
         "paypal": null,
+        "south_korea_local_card": null,
         "origin": "subscription",
         "saved_at": "2024-05-03T11:50:23.422Z",
         "updated_at": "2024-05-04T11:50:23.422Z",

tests/Functional/Resources/PaymentMethods/_fixtures/response/full_entity_paypal.json

@@ -9,6 +9,7 @@
         "email": "sam@example.com",
         "reference": "some-reference"
       },
+      "south_korea_local_card": null,
       "origin": "saved_during_purchase",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-04T11:50:23.422Z"

tests/Functional/Resources/PaymentMethods/_fixtures/response/full_entity_south_korea_local_card.json

@@ -0,0 +1,22 @@
+{
+  "data": {
+    "id": "paymtd_01hs8zx6x377xfsfrt2bqsevbw",
+    "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
+    "address_id": "add_01hv8h6jj90jjz0d71m6hj4r9z",
+    "type": "south_korea_local_card",
+    "card": null,
+    "paypal": null,
+    "south_korea_local_card": {
+      "type": "kookmin",
+      "last4": "4242"
+    },
+    "origin": "subscription",
+    "saved_at": "2024-05-03T11:50:23.422Z",
+    "updated_at": "2024-05-04T11:50:23.422Z"
+  },
+  "meta": {
+    "request_id": "03dae283-b7e9-47dc-b8c0-229576d90139"
+  }
+}
+
+

tests/Functional/Resources/PaymentMethods/_fixtures/response/list_default.json

@@ -13,6 +13,7 @@
       },
       "cardholder_name": "Sam Miller",
       "paypal": null,
+      "south_korea_local_card": null,
       "origin": "saved_during_purchase",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-03T11:50:23.422Z"
@@ -30,6 +31,7 @@
       },
       "cardholder_name": "Sam Miller",
       "paypal": null,
+      "south_korea_local_card": null,
       "origin": "saved_during_purchase",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-03T11:50:23.422Z"

tests/Functional/Resources/PaymentMethods/_fixtures/response/list_paginated_page_one.json

@@ -13,6 +13,7 @@
       },
       "cardholder_name": "Sam Miller",
       "paypal": null,
+      "south_korea_local_card": null,
       "origin": "saved_during_purchase",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-03T11:50:23.422Z"
@@ -30,6 +31,7 @@
       },
       "cardholder_name": "Sam Miller",
       "paypal": null,
+      "south_korea_local_card": null,
       "origin": "saved_during_purchase",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-03T11:50:23.422Z"

tests/Functional/Resources/PaymentMethods/_fixtures/response/list_paginated_page_two.json

@@ -13,6 +13,7 @@
       },
       "cardholder_name": "Sam Miller",
       "paypal": null,
+      "south_korea_local_card": null,
       "origin": "saved_during_purchase",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-03T11:50:23.422Z"
@@ -30,6 +31,7 @@
       },
       "cardholder_name": "Sam Miller",
       "paypal": null,
+      "south_korea_local_card": null,
       "origin": "saved_during_purchase",
       "saved_at": "2024-05-03T11:50:23.422Z",
       "updated_at": "2024-05-03T11:50:23.422Z"