# Android SDK integration

A guide to integrating the Peach Orchestration mobile SDK into a native Android app using Kotlin and the `io.peachpayments` SDK. Minimum: Android 7.0 (API 24)+.

## What this page covers
- Ten sections: Prerequisites, Installation, Configuration, Basic integration, Payment methods, Saved cards, Error handling, Customisation, Testing, Troubleshooting
- Android Studio/Kotlin prerequisites and getting Dashboard credentials (publishable key `pk_snd_xxx`/`pk_prd_xxx`)
- Gradle setup, the Peach Maven registry, and ProGuard/R8 rules
- Creating and presenting the `PaymentSheet` with a `client_secret` from your backend
- Payment methods: cards, Google Pay, direct wallet buttons (`BasePaymentWidget`), bank redirects (deep links), PayJustNow (BNPL)
- Saved cards via customer configuration + ephemeral keys, and Setup Intents (`presentWithSetupIntent`)
- Theming with `PaymentSheet.Appearance`, dark mode, error handling, testing and troubleshooting

## Key steps / API

Current versions: Android SDK **1.5.0**, Peach Gradle plugin **0.2.9**. The plugin bump is required, not optional — it carries the SDK version pin inside its own artifact, so an older plugin keeps resolving an older SDK.

Dependency: `implementation("io.peachpayments:hyperswitch-sdk-android:1.5.0")`. The Maven group moved from `io.hyperswitch` to `io.peachpayments`; the artifact name is unchanged. ProGuard: `-keep class io.peachpayments.** { *; }`.

The SDK and Gradle plugin come from the Peach GitLab Maven registry, not Maven Central. **Reads are anonymous — no token or credentials:**

```kotlin
maven { url = uri("https://gitlab.com/api/v4/projects/81506485/packages/maven") }
maven { url = uri("https://maven.juspay.in/hyper-sdk/") }  // transitive scan-card deps
maven { url = uri("https://jitpack.io") }
```

`hyperswitch-sdk-android` is the only Peach artifact you declare. It pulls in `hyperswitch-sdk-android-api` (1.1.0), `hyperswitch-sdk-android-logger` (1.0.4), and the `sentry_react-native` / `react-native-inappbrowser-reborn` / `react-native-svg` artifacts (1.0.1) transitively.

```kotlin
import io.peachpayments.PaymentSession
import io.peachpayments.paymentsheet.PaymentSheet
import io.peachpayments.paymentsheet.PaymentSheetResult

// 1. Build the session with your publishable key
paymentSession = PaymentSession.Builder(this, "pk_test_your_publishable_key")
    .customBackendUrl("https://app.sandbox-next.peachpayments.com/api")
    .build()

// 2. Initialise with a client secret fetched from your server
paymentSession.initPaymentSession(clientSecret)

// 3. Present the payment sheet
paymentSession.presentPaymentSheet { result ->
    when (result) {
        is PaymentSheetResult.Completed -> { /* success */ }
        is PaymentSheetResult.Canceled  -> { /* user dismissed */ }
        is PaymentSheetResult.Failed    -> { /* result.error */ }
    }
}
```

Other real API surface referenced in the source:
- `PaymentSheet.Configuration(merchantDisplayName, googlePay, paymentMethodOrder, customer, allowsDelayedPaymentMethods)`
- `PaymentSheet.GooglePayConfiguration(environment, countryCode, currencyCode, merchantName)`
- `PaymentSheet.CustomerConfiguration(id, ephemeralKeySecret)` for saved cards
- `paymentSheet.presentWithPaymentIntent(...)` / `paymentSheet.presentWithSetupIntent(...)`
- Theming: `PaymentSheet.Appearance` with `PaymentSheet.Colors`, `PaymentSheet.Shapes(cornerRadiusDp)`, `PaymentSheet.Typography`, `PaymentSheet.PrimaryButton`
- Deep-link handling in `onNewIntent(...)` for redirect-based payments

### Direct wallet buttons

A branded Google Pay / express-checkout button embedded in your own checkout, with no payment sheet. No new API — a view plus a launcher:

```xml
<io.peachpayments.view.BasePaymentWidget
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:paymentMethod="google_pay" />
```

`app:paymentMethod` accepts `google_pay`, `paypal`, `expressCheckout`, `card`. Then `UnifiedPaymentLauncher.createGooglePayLauncher(...)` (or `createExpressCheckoutLauncher(...)`) with your `readyCallback` / `resultCallback`. `presentForPayment(clientSecret)` starts the flow programmatically.

Two gotchas:
- **`PaymentConfiguration.init(context, publishableKey)` is required.** `UnifiedPaymentLauncher` reads the publishable key from there, not from `PaymentSession`; without it `getInstance()` throws.
- **Use `wrap_content`.** Don't pin a height — the SDK reports what it needs.

The button may render nothing: availability is decided by the SDK (wallet enabled for the merchant, connector returns a session token, wallet usable on the device). The widget collapses to zero height — a normal empty state, not an error. Treat `readyCallback` as the usability signal and always keep a card fallback.

Sandbox API base is `https://app.sandbox-next.peachpayments.com/api`; production is `https://app.next.peachpayments.com/api`. Mobile SDK V2 Google Pay requires your own Google Pay merchant ID from the [Google Pay & Wallet Console](https://pay.google.com/business/console) (enforced in production only). Complete the business profile, send Peach Payments the merchant ID, and submit for production access before going live. See Google's [web](https://developers.google.com/pay/api/web/guides/tutorial) and [Android](https://developers.google.com/pay/api/android/guides/tutorial) integration guides. Samsung Pay (Mobile SDK V2) requires your own service ID and certificates: register an Online / In-App service at [Samsung Pay Developers](https://pay.samsung.com/developers), then [contact support](https://support.peachpayments.com/support/tickets/new?ticket_form=log_a_support_ticket) for a CSR ([console](https://developer.samsung.com/pay), [docs](https://developer.samsung.com/pay/online/gettingStarted.html)). Create the `PaymentSession` in the Activity's `onCreate()`.

## Related
- [Android SDK customisation](/sdk-customization-android.md): live simulator that restyles the Android payment sheet
- [iOS SDK](/sdk-mobile-ios.md): native iOS equivalent
- [Web SDK](/sdk-web.md): browser integration
- [API Playground](/playground.md): create a payment intent and get a `client_secret`
- [Testing](/docs/testing.md): test cards and sandbox guidance

---

Interactive version: https://playground.peachpayments.com/sdk-mobile/android