> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List buyer payment methods

The native SDKs provide a convenient way to retrieve all stored payment methods for a specific buyer, filtered by the checkout's currency and country. This allows you to display previously saved payment methods to returning customers for a faster checkout experience.

## Use cases

List buyer payment methods to:

* Display saved payment methods to returning customers
* Allow buyers to select from their stored cards and payment methods
* Filter payment methods by country and currency for the current checkout
* Show payment method details (last 4 digits, expiration date, card brand)
* Sort payment methods by last used date or other criteria

### Implementation

Create a request with buyer identification (buyer ID or external identifier) and optional filters to retrieve stored payment methods.

<CodeGroup>
  ```swift Swift (iOS) theme={"system"}
  let gr4vy = try Gr4vy(
      gr4vyId: "example",
      token: "your_jwt_token",
      merchantId: "merchant_123", // Set the default merchant ID
      server: .sandbox,
      debugMode: true
  )

  // Create payment methods criteria
  let paymentMethods = Gr4vyBuyersPaymentMethods(
      buyerId: "buyer_123",
      buyerExternalIdentifier: "external_456",
      sortBy: .lastUsedAt,
      orderBy: .desc,
      country: "US",
      currency: "USD"
  )

  // Create request
  let request = Gr4vyBuyersPaymentMethodsRequest(
      paymentMethods: paymentMethods,
      merchantId: "merchant_123", // Optional
      timeout: 30.0
  )

  // Async/await
  do {
      let paymentMethodsList = try await gr4vy.paymentMethods.list(request: request)
      print("Found \(paymentMethodsList.count) payment methods")
  } catch {
      print("Error fetching payment methods: \(error)")
  }

  // Completion handler
  gr4vy.paymentMethods.list(request: request) { result in
      switch result {
      case .success(let paymentMethodsList):
          print("Found \(paymentMethodsList.count) payment methods")
      case .failure(let error):
          print("Error fetching payment methods: \(error)")
      }
  }
  ```

  ```kotlin Kotlin (Android) theme={"system"}
  val gr4vy = Gr4vy(
      gr4vyId = "example",
      token = "your_jwt_token",
      merchantId = "merchant_123", // Set the default merchant ID
      server = Gr4vyServer.SANDBOX,
      debugMode = true
  )

  // Create payment methods criteria
  val paymentMethods = Gr4vyBuyersPaymentMethods(
      buyerId = "buyer_123",
      buyerExternalIdentifier = "external_456",
      sortBy = Gr4vySortBy.LAST_USED_AT.value,
      orderBy = Gr4vyOrderBy.DESC.value,
      country = "US",
      currency = "USD"
  )

  // Create request
  val request = Gr4vyBuyersPaymentMethodsRequest(
      merchantId = "merchant_123", // Optional
      timeout = 30.0,
      paymentMethods = paymentMethods
  )

  // Suspend function
  lifecycleScope.launch {
      try {
          val paymentMethodsList = gr4vy.paymentMethods.list(request)
          println("Found ${paymentMethodsList.data.items.size} payment methods")
      } catch (error: Gr4vyError) {
          println("Error fetching payment methods: $error")
      }
  }

  // Callback version
  gr4vy.paymentMethods.list(request) { result ->
      when {
          result.isSuccess -> {
              val paymentMethodsList = result.getOrNull()
              println("Found ${paymentMethodsList?.data?.items?.size} payment methods")
          }
          result.isFailure -> {
              println("Error fetching payment methods: ${result.exceptionOrNull()}")
          }
      }
  }
  ```
</CodeGroup>

## Best practices

* **Buyer identification**: Use either `buyerId` (internal Gr4vy ID) or `buyerExternalIdentifier` (your system's ID) to identify the buyer.
* **Filter appropriately**: Apply country and currency filters to show only payment methods relevant to the current transaction.
* **Sort by usage**: Sort by `lastUsedAt` to show the most recently used payment methods first for better user experience.
* **Error handling**: Always handle network and HTTP errors gracefully and show appropriate messages to users.
* **Timeout configuration**: Use custom timeouts for payment methods requests if your network conditions require it.
* **Display clearly**: Show payment method details (card brand, last 4 digits, expiration date) to help users identify their preferred method.