For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling β€” append .md to any URL.

Skip to content
Docs

List payment methods for a customer

Returns a paginated list of payment methods that a customer has saved.

GET /customers/{customer_id}/payment-methods

Returns a paginated list of payment methods that a customer has saved. Use the query parameters to page through results.

Customers can choose to save payment methods when purchasing one-time items and subscriptions by checking a box when completing checkout. You can present customers with their saved payment methods when they make a purchase in the future.

Returns an empty list where customers have not saved any payment methods, or have deleted all previously saved payment methods.

Path parameters

customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$

Query parameters

afterstring
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
per_pageinteger
Default: 50

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 50; Maximum: 200.

Max: 200
address_idarray
Return entities related to the specified address. Use a comma-separated list to specify multiple address IDs.
order_bystring
Default: id[DESC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: id.

supports_checkoutboolean
Return entities that support being presented at checkout (true) or not (false).

Header parameters

Skip-Countstring
Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response (200)

dataarrayrequired
idstringrequired
Example: paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1
Unique Paddle ID for this payment method entity, prefixed with paymtd_.
Pattern: ^paymtd_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of the customer that this payment method is saved for, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$
address_idstringrequired
Example: add_01gm302t81w94gyjpjpqypkzkf
Paddle ID of the address for this payment method, prefixed with add_.
Pattern: ^add_[a-z\d]{26}$
typestringrequired
Type of payment method saved.
Values
  • alipay
    Alipay, popular in China.
  • apple_pay
    Apple Pay on a supported Apple device.
  • blik
    BLIK, a popular payment method in Poland.
  • card
    Credit or debit card.
  • google_pay
    Google Pay on a supported Android device, Chromebook, or Google Chrome browser.
+ Show all values
  • kakao_pay
    Kakao Pay, a popular payment method in South Korea.
  • korea_local
    Korean payment methods, which includes over 20 payment options for the Korean market. Check underlying_payment_method.korea_local for information about the Korean payment method used to pay.
  • south_korea_local_card
    Korean local credit or debit card.
  • mb_way
    MB WAY, a popular payment method in Portugal.
  • naver_pay
    Naver Pay, a popular payment method in South Korea.
  • payco
    Payco, a popular payment method in South Korea.
  • paypal
    PayPal.
  • pix
    Pix, popular in Brazil.
  • samsung_pay
    Samsung Pay, a popular payment method in South Korea.
  • upi
    Unified Payments Interface (UPI), popular in India.
  • wechat_pay
    WeChat Pay, a popular payment method in China.
cardobject | nullrequired
Card metadata
typestringrequired
Type of credit or debit card used to pay.
Values
  • american_express
    American Express
  • diners_club
    Diners Club
  • discover
    Discover Card
  • jcb
    JCB Card, popular in Japan
  • mada
    Mada Card, popular in Saudi Arabia
+ Show all values
  • maestro
    Maestro (debit card)
  • mastercard
    Mastercard
  • union_pay
    UnionPay, popular in China
  • unknown
    Card type unknown
  • visa
    Visa
last4stringrequired
Example: 4242
Last four digits of the card used to pay.
expiry_monthintegerrequired
Example: 12
Month of the expiry date of the card used to pay.
expiry_yearintegerrequired
Example: 2028
Year of the expiry date of the card used to pay.
cardholder_namestringrequired
The name on the card used to pay.
paypalobject | nullrequired
PayPal metadata
emailstringrequired
Example: john.doe@example.com
Email address associated with the PayPal account.
referencestringrequired
PayPal payment method identifier.
underlying_detailsobject | nulldeprecated
Information about the underlying payment method used to pay. Populated for payment methods that offer multiple payment options, like korea_local. Deprecated - use top-level type objects instead.
korea_localobject | nullrequired
Information about the Korean payment method used to pay. null unless the type is korea_local.
typestringrequired
Type of Korean payment method used to pay.
Values
  • bc
    BC Card (BCard), a kind of card issued in Korea. (λΉ„μ”¨μΉ΄λ“œ)
  • citi
    Card issued by Citi Bank in Korea. (ν•œκ΅­μ”¨ν‹°μ€ν–‰)
  • hana
    Card issued by Hana Bank in Korea. (ν•˜λ‚˜μΉ΄λ“œ)
  • hyundai
    Hyundai Card, a credit card issued by Hyundai in Korea. (ν˜„λŒ€μΉ΄λ“œ)
  • jeju
    Card issued by Jeju Bank in Korea. (μ œμ£Όμ€ν–‰)
+ Show all values
  • jeonbuk
    Card issued by Jeonbuk Bank in Korea. (전뢁은행)
  • kakaobank
    Card issued by Kakaobank in Korea. (μ£Όμ‹νšŒμ‚¬ μΉ΄μΉ΄μ˜€λ±…ν¬)
  • kakaopay
    KakaoPay digital wallet, popular in Korea. (카카였페이)
  • kbank
    Card issued by K Bank in Korea. (케이뱅크)
  • kdbbank
    Card issued by KDB Bank in Korea. (ν•œκ΅­μ‚°μ—…μ€ν–‰)
  • kookmin
    Card issued by Kookmin Bank in Korea. (ꡭ민은행)
  • kwangju
    Card issued by Kwangju Bank in Korea. (광주은행)
  • lotte
    Lotte Card, a credit card issued by the Lotte Corporation in Korea. (λ‘―λ°μΉ΄λ“œ)
  • mg
    Card issued by MG Community Credit Cooperatives (KFCC) in Korea. (MGμƒˆλ§ˆμ„κΈˆκ³ )
  • naverpaycard
    Card issued by Naver Pay in Korea. (넀이버 페이)
  • naverpaypoint
    Naver Pay digital wallet, popular in Korea. (넀이버 페이)
  • nh
    NH Card, a card issued by Nonghyup Bank in Korea. (NHλ†ν˜‘μ€ν–‰)
  • payco
    PayCo digital wallet, popular in Korea. (νŽ˜μ΄μ½”)
  • post
    Card issued by Korea Post. (μš°μ²΄κ΅­μ˜ˆκΈˆλ³΄ν—˜)
  • samsung
    Samsung Card, a card issued by Samsung in Korea. (μ‚Όμ„±μΉ΄λ“œ)
  • samsungpay
    Samsung Pay digital wallet, popular in Korea. (μ‚Όμ„± μ›”λ ›)
  • savingsbank
    Card issued by the Korean Federation of Savings Banks in Korea. (μ €μΆ•μ€ν–‰μ€‘μ•™νšŒ)
  • shinhan
    Card issued by Shinhan Bank in Korea. (μ£Όμ‹νšŒμ‚¬ μ‹ ν•œμ€ν–‰)
  • shinhyup
    Card issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (μ‹ ν•œμ€ν–‰ μ‹ ν˜‘)
  • suhyup
    Card issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (μˆ˜ν˜‘μ€ν–‰)
  • tossbank
    Card issued by Toss Bank in Korea. (ν† μŠ€λ±…ν¬)
  • unknown
    Underlying payment method not recognized.
  • woori
    Card issued by Woori Bank in Korea. (μ£Όμ‹νšŒμ‚¬ μš°λ¦¬μ€ν–‰)
south_korea_local_cardobject | nullrequired
Information about the Korean payment method used to pay.
typestring
Type of Korean payment method used to pay.
Values
  • bc
    BC Card (BCard), a kind of card issued in Korea. (λΉ„μ”¨μΉ΄λ“œ).
  • citi
    Card issued by Citi Bank in Korea. (ν•œκ΅­μ”¨ν‹°μ€ν–‰).
  • hana
    Card issued by Hana Bank in Korea. (ν•˜λ‚˜μΉ΄λ“œ).
  • hyundai
    Hyundai Card, a credit card issued by Hyundai in Korea. (ν˜„λŒ€μΉ΄λ“œ).
  • jeju
    Card issued by Jeju Bank in Korea. (μ œμ£Όμ€ν–‰).
+ Show all values
  • jeonbuk
    Card issued by Jeonbuk Bank in Korea. (전뢁은행).
  • kakaobank
  • kbank
    Card issued by K Bank in Korea. (케이뱅크).
  • kdbbank
    Card issued by KDB Bank in Korea. (ν•œκ΅­μ‚°μ—…μ€ν–‰).
  • kookmin
    Card issued by Kookmin Bank in Korea. (ꡭ민은행).
  • kwangju
    Card issued by Kwangju Bank in Korea. (광주은행).
  • lotte
    Lotte Card, a credit card issued by the Lotte Corporation in Korea. (λ‘―λ°μΉ΄λ“œ).
  • mg
    Card issued by MG Community Credit Cooperatives (KFCC) in Korea. (MGμƒˆλ§ˆμ„κΈˆκ³ ).
  • nh
    NH Card, a card issued by Nonghyup Bank in Korea. (NHλ†ν˜‘μ€ν–‰).
  • post
    Card issued by Korea Post. (μš°μ²΄κ΅­μ˜ˆκΈˆλ³΄ν—˜).
  • samsung
    Samsung Card, a card issued by Samsung in Korea. (μ‚Όμ„±μΉ΄λ“œ).
  • savingsbank
    Card issued by the Korean Federation of Savings Banks in Korea. (μ €μΆ•μ€ν–‰μ€‘μ•™νšŒ).
  • shinhan
    Card issued by Shinhan Bank in Korea. (μ£Όμ‹νšŒμ‚¬ μ‹ ν•œμ€ν–‰).
  • shinhyup
    Card issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (μ‹ ν•œμ€ν–‰ μ‹ ν˜‘).
  • suhyup
    Card issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (μˆ˜ν˜‘μ€ν–‰).
  • tossbank
    Card issued by Toss Bank in Korea. (ν† μŠ€λ±…ν¬).
  • unknown
    Underlying payment method not recognized.
  • woori
    Card issued by Woori Bank in Korea. (μ£Όμ‹νšŒμ‚¬ μš°λ¦¬μ€ν–‰).
last4string
Example: 4242
Last four digits of the card used to pay.
originstringrequired
Describes how this payment method was saved.
Values
  • saved_during_purchase
    The customer chose to save this payment method while purchasing a one-time item.
  • subscription
    The customer purchased a subscription, so this payment method was saved for future purchases.
  • subscription_saved_during_purchase
    The customer chose to save the payment method when purchasing a subscription.
saved_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was saved. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the after parameter that marks the starting point of the next page. Always returned, even if has_more is false.
has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999

Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns 100001 to indicate that more than 100,000 entities match. Returns -1 when counting is skipped or couldn't be calculated.

Use has_more and next to page through all results rather than relying on estimated_total for an exact count.

Response
{
  "data": [
    {
      "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
      "address_id": "add_01j2jfab8zcjy524w6e4s1knjy",
      "id": "paymtd_01j2jff1m3es31sdkejpaym164",
      "type": "card",
      "card": {
        "cardholder_name": "Sam Miller",
        "type": "visa",
        "last4": "4242",
        "expiry_month": 5,
        "expiry_year": 2025
      },
      "paypal": null,
      "origin": "saved_during_purchase",
      "saved_at": "2024-07-12T03:23:26Z",
      "updated_at": "2024-10-29T14:12:28.018784Z",
      "underlying_details": null,
      "south_korea_local_card": null
    }
  ],
  "meta": {
    "request_id": "0a5ed361-6e13-4cf0-bcad-cca2fca21dca",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/customers/ctm_01hv6y1jedq4p1n0yqn5ba3ky4/payment-methods?after=paymtd_01j2jff1m3es31sdkejpaym164",
      "has_more": false,
      "estimated_total": 1
    }
  }
}

Was this page helpful?