> ## 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 payment options

The native SDKs provide a convenient way to retrieve available payment options for your checkout. This allows you to display all payment methods that are available for the transaction to your users.

## Use cases

List payment options to:

* Display available payment methods at checkout
* Filter payment options based on merchant, country, currency, and amount
* Determine which payment methods to present to your customer
* Implement dynamic payment method selection UI

### Implementation

Create a request with your checkout details and retrieve available payment options.

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

  let request = Gr4vyPaymentOptionRequest(
      merchantId: "merchant_123", // Optional, uses SDK merchantId if not provided
      metadata: ["order_id": "12345"],
      country: "US",
      currency: "USD",
      amount: 1299,
      locale: "en-US",
      cartItems: nil
  )

  // Async/await
  do {
      let paymentOptions = try await gr4vy.paymentOptions.list(request: request)
      print("Available payment options: \(paymentOptions.count)")
  } catch {
      print("Error fetching payment options: \(error)")
  }

  // Completion handler
  gr4vy.paymentOptions.list(request: request) { result in
      switch result {
      case .success(let paymentOptions):
          print("Available payment options: \(paymentOptions.count)")
      case .failure(let error):
          print("Error fetching payment options: \(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 request
  val request = Gr4vyPaymentOptionRequest(
      merchantId = "merchant_123", // Optional, uses SDK merchantId if not provided
      metadata = mapOf("order_id" to "12345"),
      country = "US",
      currency = "USD",
      amount = 1299,
      locale = "en-US",
      cartItems = null
  )

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

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

## Best practices

* **Cache results**: Store payment options locally to reduce API calls when the country, currency, and amount haven't changed.
* **Error handling**: Always handle network and HTTP errors gracefully and show appropriate messages to users.
* **Timeout configuration**: Use custom timeouts for payment options requests if your network conditions require it.
* **Localization**: Use the appropriate locale to ensure payment option labels are displayed in the correct language.