Android

Use WebView to embed frames in native Android applications. The WebView communicates with frames via JavaScript interfaces and evaluateJavascript.

Read the manual integration overview for core concepts before you continue.

Setup

Dependencies

The examples below use Tink for cryptographic operations, but you can use any library that supports X25519 and AES-GCM. The base fragment uses AndroidX WebKit to enable the Payment Request API for Google Pay.

// build.gradle.kts (app level)
dependencies {
    implementation("com.google.crypto.tink:tink-android:1.12.0")
    implementation("androidx.webkit:webkit:1.14.0")
}

Key generation

import com.google.crypto.tink.subtle.X25519

data class MoonPayKeyPair(
    val privateKey: ByteArray,
    val publicKeyHex: String
)

object MoonPayCrypto {
    fun generateKeyPair(): MoonPayKeyPair {
        val privateKey = X25519.generatePrivateKey()
        val publicKey = X25519.publicFromPrivate(privateKey)
        val publicKeyHex = publicKey.joinToString("") { "%02x".format(it) }

        return MoonPayKeyPair(privateKey, publicKeyHex)
    }
}

Decryption utility

import android.util.Base64
import com.google.crypto.tink.subtle.Hkdf
import com.google.crypto.tink.subtle.X25519
import org.json.JSONObject
import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.SecretKeySpec

object MoonPayDecryptor {
    fun decrypt(encryptedValue: String, privateKey: ByteArray): String {
        // The frame returns the encrypted payload as a base64-encoded
        // JSON string. Decode the base64 first, then parse the JSON.
        val decodedJson = String(Base64.decode(encryptedValue, Base64.DEFAULT), Charsets.UTF_8)
        val encrypted = JSONObject(decodedJson)

        val iv = encrypted.getString("iv").hexToByteArray()
        val ephemeralPublicKey = encrypted.getString("ephemeralPublicKey").hexToByteArray()
        val ciphertext = encrypted.getString("ciphertext").hexToByteArray()

        // Derive shared secret using X25519
        val sharedSecret = X25519.computeSharedSecret(privateKey, ephemeralPublicKey)

        // Derive AES key using HKDF
        val aesKey = Hkdf.computeHkdf(
            "HMACSHA256",
            sharedSecret,
            ByteArray(0),
            ByteArray(0),
            32
        )

        // Decrypt using AES-GCM
        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
        val keySpec = SecretKeySpec(aesKey, "AES")
        val gcmSpec = GCMParameterSpec(128, iv)

        cipher.init(Cipher.DECRYPT_MODE, keySpec, gcmSpec)
        val decrypted = cipher.doFinal(ciphertext)

        return String(decrypted, Charsets.UTF_8)
    }

    private fun String.hexToByteArray(): ByteArray {
        return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
    }
}

Base frame fragment

Create a reusable base fragment for frame communication:

import android.annotation.SuppressLint
import android.net.Uri
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.webkit.JavascriptInterface
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.fragment.app.Fragment
import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
import org.json.JSONObject
import java.util.UUID

abstract class MoonPayFrameFragment : Fragment() {
    protected lateinit var webView: WebView
    protected val channelId: String = UUID.randomUUID().toString()

    private val handler = Handler(Looper.getMainLooper())

    companion object {
        const val FRAME_ORIGIN = "https://platform.moonpay.com"
    }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        webView = WebView(requireContext()).apply {
            settings.javaScriptEnabled = true
            settings.domStorageEnabled = true

            // Required for Google Pay in the buy button and challenge frames:
            // enables the Payment Request API, which is off by default
            if (WebViewFeature.isFeatureSupported(WebViewFeature.PAYMENT_REQUEST)) {
                WebSettingsCompat.setPaymentRequestEnabled(settings, true)
            }

            addJavascriptInterface(MoonPayBridge(), "MoonPayBridge")
            // Required for the test-mode Google Pay flow — see "Handle
            // JavaScript dialogs" below.
            webChromeClient = MoonPayChromeClient(this@MoonPayFrameFragment)
        }

        return webView
    }

    protected fun loadFrame(path: String, params: Map<String, String>) {
        // appendQueryParameter encodes each value, so tokens and signatures
        // that contain `&`, `=`, `+`, or spaces arrive intact
        val url = Uri.parse("$FRAME_ORIGIN$path").buildUpon().apply {
            params.forEach { (key, value) -> appendQueryParameter(key, value) }
        }.build()

        webView.loadUrl(url.toString())
    }

    protected fun sendMessage(kind: String, payload: JSONObject? = null) {
        val message = JSONObject().apply {
            put("version", 2)
            put("meta", JSONObject().put("channelId", channelId))
            put("kind", kind)
            payload?.let { put("payload", it) }
        }

        // Re-encode the JSON as a string literal. The frame's bridge
        // listens for `MessageEvent`s whose `data` is a string and
        // ignores anything else, so we must post a string — not an
        // object literal.
        val stringLiteral = JSONObject.quote(message.toString())

        val script = "window.postMessage($stringLiteral, '*');"
        webView.evaluateJavascript(script, null)
    }

    private fun handleMessage(data: JSONObject) {
        val meta = data.optJSONObject("meta") ?: return
        if (meta.optString("channelId") != channelId) return

        val kind = data.optString("kind")

        if (kind == "handshake") {
            sendMessage("ack")
            onFrameHandshakeComplete()
        }

        onFrameMessage(kind, data.optJSONObject("payload"))
    }

    // Abstract methods for subclasses
    protected abstract fun onFrameMessage(kind: String, payload: JSONObject?)
    protected abstract fun onFrameHandshakeComplete()

    override fun onDestroyView() {
        // Drop queued messages, then detach and destroy the WebView
        handler.removeCallbacksAndMessages(null)
        webView.apply {
            removeJavascriptInterface("MoonPayBridge")
            stopLoading()
            (parent as? ViewGroup)?.removeView(this)
            destroy()
        }
        super.onDestroyView()
    }

    inner class MoonPayBridge {
        // Called on a background thread. Hand the message to the main thread.
        @JavascriptInterface
        fun postMessage(data: String) {
            handler.post {
                // The page can still call the bridge while the view is torn
                // down, so skip messages that arrive after it's gone
                if (!isAdded || view == null) return@post

                try {
                    val json = JSONObject(data)
                    handleMessage(json)
                } catch (e: Exception) {
                    // Ignore malformed messages
                }
            }
        }
    }
}

Handle JavaScript dialogs

In test mode, the Buy Button frame renders a mock Google Pay button for a Google Pay quote and uses window.prompt to simulate the Google Pay payment sheet. Android’s WebView doesn’t show alert, confirm, or prompt unless you attach a WebChromeClient that handles them. Without one, every test transaction silently comes back with status: "failed". Override onJsPrompt and surface the simulated payment sheet with an AlertDialog. Return the entered text through JsPromptResult.confirm(), or call cancel() when the customer declines. The onJsConfirm handler covers any other dialog the frame might show:

import android.app.AlertDialog
import android.webkit.JsPromptResult
import android.webkit.JsResult
import android.webkit.WebChromeClient
import android.webkit.WebView
import android.widget.EditText
import androidx.fragment.app.Fragment

class MoonPayChromeClient(private val fragment: Fragment) : WebChromeClient() {
    // The test-mode Google Pay sheet: the message shows the total, and the
    // text field holds the billing address JSON
    override fun onJsPrompt(
        view: WebView?,
        url: String?,
        message: String?,
        defaultValue: String?,
        result: JsPromptResult
    ): Boolean {
        val context = fragment.context ?: return false
        val input = EditText(context).apply { setText(defaultValue) }
        AlertDialog.Builder(context)
            .setMessage(message)
            .setView(input)
            .setPositiveButton("OK") { _, _ -> result.confirm(input.text.toString()) }
            .setNegativeButton("Cancel") { _, _ -> result.cancel() }
            .setOnCancelListener { result.cancel() }
            .show()
        return true
    }

    override fun onJsConfirm(
        view: WebView?,
        url: String?,
        message: String?,
        result: JsResult
    ): Boolean {
        val context = fragment.context ?: return false
        AlertDialog.Builder(context)
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> result.confirm() }
            .setNegativeButton("Cancel") { _, _ -> result.cancel() }
            .setOnCancelListener { result.cancel() }
            .show()
        return true
    }
}

In the prompt, OK authorizes the test payment with the billing address in the text field (the frame emits complete with a non-failed status); Cancel declines it (the frame emits complete with status: "failed").

Attach the WebChromeClient even if you only plan to ship live mode. The default WebView behavior applies to any window.confirm, alert, or prompt the frame might surface, and makes test-mode debugging impossible without it.

Check frame

The check frame verifies whether a customer already has an active connection. It’s headless — no UI is rendered. Use it to skip the connect flow for returning customers. See check frame reference for event details.

Check fragment

import org.json.JSONObject

interface CheckFrameListener {
    fun onCheckActive(accessToken: String, clientToken: String, expiresAt: String)
    fun onCheckConnectionRequired(accessToken: String, clientToken: String)
    fun onCheckFailed(status: String, reason: String?)
    fun onCheckError(code: String, message: String)
}

class MoonPayCheckFragment : MoonPayFrameFragment() {
    private lateinit var keyPair: MoonPayKeyPair
    private var sessionToken: String? = null
    var listener: CheckFrameListener? = null

    companion object {
        private const val ARG_SESSION_TOKEN = "sessionToken"

        fun newInstance(sessionToken: String): MoonPayCheckFragment {
            return MoonPayCheckFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_SESSION_TOKEN, sessionToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        sessionToken = arguments?.getString(ARG_SESSION_TOKEN)
        keyPair = MoonPayCrypto.generateKeyPair()
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/check-connection", mapOf(
            "sessionToken" to sessionToken!!,
            "publicKey" to keyPair.publicKeyHex,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> handleComplete(payload)
            "error" -> {
                listener?.onCheckError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete, checking connection status
    }

    private fun handleComplete(payload: JSONObject?) {
        val status = payload?.optString("status") ?: return

        when (status) {
            "active" -> {
                val credentials = payload.optString("credentials")
                val expiresAt = payload.optString("expiresAt")
                val customer = payload.optJSONObject("customer")
                val country = customer?.optString("country")
                val administrativeArea = customer?.optString("administrativeArea")
                val area = customer?.optString("area")
                // payload.capabilities.ramps.requirements.paymentDisclosures is deprecated.

                try {
                    val decryptedPayload = MoonPayDecryptor.decrypt(credentials, keyPair.privateKey)
                    val credentials = JSONObject(decryptedPayload)
                    val accessToken = credentials.getString("accessToken")
                    val clientToken = credentials.getString("clientToken")
                    listener?.onCheckActive(accessToken, clientToken, expiresAt)
                } catch (e: Exception) {
                    listener?.onCheckError("decryption", "Failed to decrypt credentials")
                }
            }
            "connectionRequired" -> {
                val encryptedCredentials = payload.optString("credentials")
                // payload.optBoolean("mismatch") is true when the session's email and phone resolve to different customers — route through the connect flow first.

                try {
                    val decryptedPayload = MoonPayDecryptor.decrypt(encryptedCredentials, keyPair.privateKey)
                    val anonymousCredentials = JSONObject(decryptedPayload)
                    val accessToken = anonymousCredentials.getString("accessToken")
                    val clientToken = anonymousCredentials.getString("clientToken")
                    listener?.onCheckConnectionRequired(accessToken, clientToken)
                } catch (e: Exception) {
                    listener?.onCheckError("decryption", "Failed to decrypt anonymous credentials")
                }
            }
            "pending", "unavailable", "failed" -> {
                listener?.onCheckFailed(status, payload.optString("reason"))
            }
        }
    }
}

Usage

class SplashActivity : AppCompatActivity(), CheckFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayCheckFragment.newInstance("your-session-token")
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    override fun onCheckActive(accessToken: String, clientToken: String, expiresAt: String) {
        // Customer is already connected — skip to payment
        CredentialsManager.accessToken = accessToken
        CredentialsManager.clientToken = clientToken

        startActivity(Intent(this, PaymentActivity::class.java))
        finish()
    }

    override fun onCheckConnectionRequired(accessToken: String, clientToken: String) {
        // Store both tokens in memory, then show connect frame with the anonymous clientToken
        CredentialsManager.accessToken = accessToken
        CredentialsManager.clientToken = clientToken

        val intent = Intent(this, ConnectActivity::class.java).apply {
            putExtra("clientToken", clientToken)
        }
        startActivity(intent)
        finish()
    }

    override fun onCheckFailed(status: String, reason: String?) {
        // Handle terminal statuses (pending, unavailable, failed)
    }

    override fun onCheckError(code: String, message: String) {
        // Handle check errors
    }
}

Connect frame

The connect frame establishes a customer connection to your application. See connect frame reference for event details.

Connect fragment

import org.json.JSONObject

interface ConnectFrameListener {
    fun onConnectComplete(accessToken: String, clientToken: String, expiresAt: String)
    fun onConnectFailed(status: String, reason: String?)
    fun onConnectError(code: String, message: String)
}

class MoonPayConnectFragment : MoonPayFrameFragment() {
    private lateinit var keyPair: MoonPayKeyPair
    private var clientToken: String? = null
    var listener: ConnectFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"

        fun newInstance(clientToken: String): MoonPayConnectFragment {
            return MoonPayConnectFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        keyPair = MoonPayCrypto.generateKeyPair()
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/connect", mapOf(
            "clientToken" to clientToken!!,
            "publicKey" to keyPair.publicKeyHex,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> handleComplete(payload)
            "error" -> {
                listener?.onConnectError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete, waiting for customer interaction
    }

    private fun handleComplete(payload: JSONObject?) {
        val status = payload?.optString("status") ?: return

        when (status) {
            "active" -> {
                val credentials = payload.optString("credentials")
                val expiresAt = payload.optString("expiresAt")
                val customer = payload.optJSONObject("customer")
                val country = customer?.optString("country")
                val administrativeArea = customer?.optString("administrativeArea")
                val area = customer?.optString("area")
                // payload.capabilities.ramps.requirements.paymentDisclosures is deprecated.

                try {
                    val decryptedPayload = MoonPayDecryptor.decrypt(credentials, keyPair.privateKey)
                    val credentials = JSONObject(decryptedPayload)
                    val accessToken = credentials.getString("accessToken")
                    val clientToken = credentials.getString("clientToken")
                    listener?.onConnectComplete(accessToken, clientToken, expiresAt)
                } catch (e: Exception) {
                    listener?.onConnectError("decryption", "Failed to decrypt credentials")
                }
            }
            "pending", "unavailable", "failed" -> {
                listener?.onConnectFailed(status, payload.optString("reason"))
            }
        }
    }
}

Usage with Activity

class ConnectActivity : AppCompatActivity(), ConnectFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        // The clientToken is the anonymous token passed from the check frame's
        // `connectionRequired` response.
        val clientToken = intent.getStringExtra("clientToken")!!
        val fragment = MoonPayConnectFragment.newInstance(clientToken)
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    // ConnectFrameListener implementation

    override fun onConnectComplete(accessToken: String, clientToken: String, expiresAt: String) {
        // Store credentials in memory
        CredentialsManager.accessToken = accessToken
        CredentialsManager.clientToken = clientToken

        Toast.makeText(this, "Connected!", Toast.LENGTH_SHORT).show()

        // Navigate to next screen
        startActivity(Intent(this, PaymentActivity::class.java))
        finish()
    }

    override fun onConnectFailed(status: String, reason: String?) {
        AlertDialog.Builder(this)
            .setTitle("Connection $status")
            .setMessage(reason ?: "Please try again later.")
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }

    override fun onConnectError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }
}

Auth frame

The auth frame authenticates a customer with email or SMS one-time passcode and returns fully scoped credentials — without the hosted KYC UI in the connect frame. Launch it after the check frame returns connectionRequired, typically when you drive onboarding through the Customer API. See auth frame reference for event details.

Auth fragment

import org.json.JSONObject

interface AuthFrameListener {
    fun onAuthReady()
    fun onAuthComplete(status: String, accessToken: String?, clientToken: String?, customerId: String?)
    fun onAuthError(code: String, message: String)
    fun onAuthClose()
}

class MoonPayAuthFragment : MoonPayFrameFragment() {
    private lateinit var keyPair: MoonPayKeyPair
    private var clientToken: String? = null
    var listener: AuthFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"

        fun newInstance(clientToken: String): MoonPayAuthFragment {
            return MoonPayAuthFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        keyPair = MoonPayCrypto.generateKeyPair()
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        webView.visibility = View.INVISIBLE

        loadFrame("/v2/auth", mapOf(
            "clientToken" to clientToken!!,
            "publicKey" to keyPair.publicKeyHex,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "ready" -> {
                webView.visibility = View.VISIBLE
                listener?.onAuthReady()
            }
            "complete" -> handleComplete(payload)
            "error" -> {
                listener?.onAuthError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
            "close" -> listener?.onAuthClose()
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete — waiting for OTP
    }

    private fun handleComplete(payload: JSONObject?) {
        val status = payload?.optString("status") ?: return

        when (status) {
            "active" -> {
                val credentials = payload.optString("credentials")
                val customerId = payload.optJSONObject("customer")?.optString("id")

                try {
                    val decryptedPayload = MoonPayDecryptor.decrypt(credentials, keyPair.privateKey)
                    val credentialsJson = JSONObject(decryptedPayload)
                    listener?.onAuthComplete(
                        status,
                        credentialsJson.getString("accessToken"),
                        credentialsJson.getString("clientToken"),
                        customerId
                    )
                } catch (e: Exception) {
                    listener?.onAuthError("decryption", "Failed to decrypt credentials")
                }
            }
            "termsAcceptanceRequired", "pending", "unavailable" -> {
                listener?.onAuthComplete(status, null, null, null)
            }
        }
    }
}

Usage with Activity

class AuthActivity : AppCompatActivity(), AuthFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val clientToken = intent.getStringExtra("clientToken")!!
        val fragment = MoonPayAuthFragment.newInstance(clientToken)
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    override fun onAuthReady() {
        // Frame is visible — hide any loading UI
    }

    override fun onAuthComplete(
        status: String,
        accessToken: String?,
        clientToken: String?,
        customerId: String?
    ) {
        when (status) {
            "active" -> {
                CredentialsManager.accessToken = accessToken
                CredentialsManager.clientToken = clientToken
                Toast.makeText(this, "Authenticated!", Toast.LENGTH_SHORT).show()
                startActivity(Intent(this, HomeActivity::class.java))
                finish()
            }
            "termsAcceptanceRequired" -> {
                startActivity(Intent(this, TermsActivity::class.java))
                finish()
            }
            else -> {
                AlertDialog.Builder(this)
                    .setTitle("Auth $status")
                    .setMessage("Please try again later.")
                    .setPositiveButton("OK") { _, _ -> finish() }
                    .show()
            }
        }
    }

    override fun onAuthError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }

    override fun onAuthClose() {
        finish()
    }
}

Add Card frame

The add card frame lets a customer save a new card to their account. See add card frame reference for event details.

What you’ll need

Before you initialize the add card frame, you need:

A clientToken from a successful connect flow

Add Card fragment

import org.json.JSONObject

interface AddCardFrameListener {
    fun onAddCardComplete(cardId: String, brand: String, last4: String)
    fun onAddCardError(code: String, message: String)
}

class MoonPayAddCardFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    var listener: AddCardFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"

        fun newInstance(clientToken: String): MoonPayAddCardFragment {
            return MoonPayAddCardFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/add-card", mapOf(
            "clientToken" to clientToken!!,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> {
                val card = payload?.optJSONObject("card")
                listener?.onAddCardComplete(
                    card?.optString("id") ?: "",
                    card?.optString("brand") ?: "",
                    card?.optString("last4") ?: ""
                )
            }
            "error" -> {
                listener?.onAddCardError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete
    }
}

Usage with Activity

class SaveCardActivity : AppCompatActivity(), AddCardFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayAddCardFragment.newInstance(CredentialsManager.clientToken!!)
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    override fun onAddCardComplete(cardId: String, brand: String, last4: String) {
        Toast.makeText(this, "Card saved: $brand •••• $last4", Toast.LENGTH_SHORT).show()
        // Proceed to payment with the saved card
        finish()
    }

    override fun onAddCardError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }
}

Buy Button frame

The Buy Button frame takes a quote to payment. It renders the Google Pay or card button that matches the payment method in your quote, and supports guest checkout when your quote allows it. For card and bank transfer quotes, you can also run it in headless mode behind your own purchase button. See the Buy Button frame reference for event details, and Pay with the buy button for the full walkthrough.

Android WebView setup

Google Pay in a WebView needs the setup on Android WebView requirements. The base fragment already enables the Payment Request API with the AndroidX WebKit dependency from Dependencies. You still need to declare the Google Pay intent queries, meet the version requirements, and get your app approved before you load the Buy Button frame with a Google Pay quote.

What you’ll need

Before you initialize the Buy Button frame, you need:

A clientToken from a successful connect flow
A valid quote signature for the transaction

Buy Button fragment

Pass headless = true to newInstance to run the purchase without a button, as described in Headless mode.

import android.content.Context
import android.os.Bundle
import android.view.View
import org.json.JSONObject

interface BuyButtonFrameListener {
    fun onBuyButtonReady()
    fun onBuyButtonComplete(transactionId: String, status: String)
    fun onBuyButtonFailed(failureCode: String, reason: String)
    fun onBuyButtonChallenge(url: String)
    fun onBuyButtonCancelled()
    fun onBuyButtonError(code: String, message: String)
}

class MoonPayBuyButtonFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    private var quoteSignature: String? = null
    private var externalTransactionId: String? = null
    private var headless = false
    var listener: BuyButtonFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"
        private const val ARG_QUOTE_SIGNATURE = "quoteSignature"
        private const val ARG_EXTERNAL_TRANSACTION_ID = "externalTransactionId"
        private const val ARG_HEADLESS = "headless"

        fun newInstance(
            clientToken: String,
            quoteSignature: String,
            externalTransactionId: String? = null,
            headless: Boolean = false,
        ): MoonPayBuyButtonFragment {
            return MoonPayBuyButtonFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                    putString(ARG_QUOTE_SIGNATURE, quoteSignature)
                    putString(ARG_EXTERNAL_TRANSACTION_ID, externalTransactionId)
                    putBoolean(ARG_HEADLESS, headless)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        quoteSignature = arguments?.getString(ARG_QUOTE_SIGNATURE)
        externalTransactionId = arguments?.getString(ARG_EXTERNAL_TRANSACTION_ID)
        headless = arguments?.getBoolean(ARG_HEADLESS) ?: false
    }

    override fun onAttach(context: Context) {
        super.onAttach(context)
        // A recreated fragment loses the listener its host set, so fall back
        // to the host
        if (listener == null) listener = context as? BuyButtonFrameListener
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        if (headless && savedInstanceState != null) {
            // Recreated after a configuration change or process death. Loading
            // the headless frame again would start a second purchase, so remove
            // the fragment and look the attempt up through the API instead.
            parentFragmentManager.beginTransaction().remove(this).commit()
            return
        }

        loadFrame("/platform/v1/buy-button", buildMap {
            put("clientToken", clientToken!!)
            put("channelId", channelId)
            put("signature", quoteSignature!!)
            externalTransactionId?.let { put("externalTransactionId", it) }
            if (headless) put("headless", "true")
        })
    }

    fun updateQuote(signature: String) {
        quoteSignature = signature
        sendMessage("setQuote", JSONObject().put("quote", JSONObject().put("signature", signature)))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "ready" -> listener?.onBuyButtonReady()
            "complete" -> {
                val transaction = payload?.optJSONObject("transaction")
                val status = transaction?.optString("status") ?: ""

                if (status == "failed") {
                    // Branch on failureCode; failureReason is developer-facing only
                    listener?.onBuyButtonFailed(
                        transaction?.optString("failureCode") ?: "unknown",
                        transaction?.optString("failureReason") ?: "Transaction failed"
                    )
                } else {
                    listener?.onBuyButtonComplete(
                        transaction?.optString("id") ?: "",
                        status
                    )
                }
            }
            "challenge" -> listener?.onBuyButtonChallenge(payload?.optString("url") ?: "")
            // The customer dismissed the Google Pay sheet.
            // The button stays on screen, so the customer can tap it again.
            "cancelled" -> listener?.onBuyButtonCancelled()
            "error" -> listener?.onBuyButtonError(
                payload?.optString("code") ?: "unknown",
                payload?.optString("message") ?: "Unknown error"
            )
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete
    }
}

Challenge handling

When the Buy Button fragment receives a challenge URL, for example for 3-D Secure, add a MoonPayChallengeFragment to present the challenge. Opened without resume, as below, the challenge frame finishes the purchase for every payment method and sends complete. On completion, cancellation, or error, remove both the challenge and Buy Button fragments. To have the customer finish a Google Pay purchase on your buy button instead, see Finish on your buy button.

import org.json.JSONObject

interface ChallengeFrameListener {
    fun onChallengeComplete(transactionId: String, status: String)
    fun onChallengeFailed(failureCode: String, reason: String)
    fun onChallengeCancelled()
    fun onChallengeError(code: String, message: String)
}

class MoonPayChallengeFragment : MoonPayFrameFragment() {
    private var challengeUrl: String? = null
    private var clientToken: String? = null
    var listener: ChallengeFrameListener? = null

    companion object {
        private const val ARG_CHALLENGE_URL = "challengeUrl"
        private const val ARG_CLIENT_TOKEN = "clientToken"

        fun newInstance(challengeUrl: String, clientToken: String): MoonPayChallengeFragment {
            return MoonPayChallengeFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CHALLENGE_URL, challengeUrl)
                    putString(ARG_CLIENT_TOKEN, clientToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        challengeUrl = arguments?.getString(ARG_CHALLENGE_URL)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        val urlWithParams = Uri.parse(challengeUrl)
            .buildUpon()
            .appendQueryParameter("clientToken", clientToken)
            .appendQueryParameter("channelId", channelId)
            .toString()
        webView.loadUrl(urlWithParams)
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> {
                val transaction = payload?.optJSONObject("transaction")
                val status = transaction?.optString("status") ?: ""

                if (status == "failed") {
                    // A failed transaction may have no id.
                    // Branch on failureCode; failureReason is developer-facing only
                    listener?.onChallengeFailed(
                        transaction?.optString("failureCode") ?: "unknown",
                        transaction?.optString("failureReason") ?: "Transaction failed"
                    )
                } else {
                    listener?.onChallengeComplete(
                        transaction?.optString("id") ?: "",
                        status
                    )
                }
            }
            "cancelled" -> {
                listener?.onChallengeCancelled()
            }
            "error" -> {
                listener?.onChallengeError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete
    }
}

Usage with Activity

Give the button container a height of 44dp. See Size.

class BuyButtonActivity : AppCompatActivity(), BuyButtonFrameListener, ChallengeFrameListener {
    private var buyButtonFragment: MoonPayBuyButtonFragment? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_buy_button)

        // After a configuration change, the FragmentManager restores the
        // fragments but not their listeners. Reattach them, and don't add a
        // second buy button.
        val restored = supportFragmentManager.findFragmentByTag("buyButton") as? MoonPayBuyButtonFragment
        if (restored != null) {
            restored.listener = this
            buyButtonFragment = restored
            (supportFragmentManager.findFragmentByTag("challenge") as? MoonPayChallengeFragment)
                ?.listener = this
            return
        }

        val fragment = MoonPayBuyButtonFragment.newInstance(
            clientToken = CredentialsManager.clientToken!!,
            quoteSignature = currentQuote.signature
        )
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .add(R.id.buy_button_container, fragment, "buyButton")
            .commit()

        buyButtonFragment = fragment
    }

    // BuyButtonFrameListener implementation

    override fun onBuyButtonReady() {
        // The button is visible and ready
    }

    override fun onBuyButtonComplete(transactionId: String, status: String) {
        removeFragments()
        Toast.makeText(this, "Transaction $transactionId: $status", Toast.LENGTH_SHORT).show()
        // Navigate to transaction status screen or poll for updates
    }

    override fun onBuyButtonFailed(failureCode: String, reason: String) {
        removeFragments()
        AlertDialog.Builder(this)
            .setTitle("Payment Failed")
            .setMessage(reason)
            .setPositiveButton("OK", null)
            .show()
    }

    override fun onBuyButtonChallenge(url: String) {
        val challengeFragment = MoonPayChallengeFragment.newInstance(
            url,
            CredentialsManager.clientToken!!
        )
        challengeFragment.listener = this

        supportFragmentManager.beginTransaction()
            .add(R.id.frame_container, challengeFragment, "challenge")
            .commit()
    }

    override fun onBuyButtonCancelled() {
        // The button stays on screen, so there's nothing to clean up
    }

    override fun onBuyButtonError(code: String, message: String) {
        if (code == "quoteExpired") {
            lifecycleScope.launch {
                val newQuote = fetchNewQuote()
                buyButtonFragment?.updateQuote(newQuote.signature)
            }
            return
        }
        removeFragments()
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK", null)
            .show()
    }

    // ChallengeFrameListener implementation

    override fun onChallengeComplete(transactionId: String, status: String) {
        removeFragments()
        Toast.makeText(this, "Transaction $transactionId: $status", Toast.LENGTH_SHORT).show()
        // Navigate to transaction status screen or poll for updates
    }

    override fun onChallengeFailed(failureCode: String, reason: String) {
        removeFragments()
        AlertDialog.Builder(this)
            .setTitle("Payment Failed")
            .setMessage(reason)
            .setPositiveButton("OK", null)
            .show()
    }

    override fun onChallengeCancelled() {
        removeFragments()
    }

    override fun onChallengeError(code: String, message: String) {
        removeFragments()
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK", null)
            .show()
    }

    // The purchase ended: remove the frames. Add a new Buy Button fragment to retry.
    private fun removeFragments() {
        val transaction = supportFragmentManager.beginTransaction()
        supportFragmentManager.findFragmentByTag("challenge")?.let { transaction.remove(it) }
        supportFragmentManager.findFragmentByTag("buyButton")?.let { transaction.remove(it) }
        transaction.commit()
        buyButtonFragment = null
    }
}

Headless mode

For card and bank transfer quotes, you can draw your own purchase button and pass headless = true to newInstance. The frame loads with headless=true, renders nothing, and starts the purchase as soon as it loads. Add the fragment to a 1px container when the customer confirms the purchase in your UI, not before. See Headless mode. In headless mode, the frame:

Sends ready, then exactly one of complete, challenge, or error.
Never sends buttonPressed or cancelled.
Accepts card and bank transfer (SEPA) quotes only. A Google Pay quote returns error with unsupportedPaymentMethod.
Needs a connected customer. A guest checkout quote returns error with invalidQuote.
Reads setQuote only after an error with quoteExpired.

On challenge, add the challenge fragment without resume, as in challenge handling. It finishes the purchase and sends its own complete. For a bank transfer (SEPA) quote, onBuyButtonComplete receives the transaction id. Fetch the transaction by ID, and show the customer the bank details from bankTransferDepositInfo and the amount to send from source.amount natively so they can send the transfer. See Pay with bank transfer.

For bank transfers, the customer must include the payment reference from bankTransferDepositInfo with their transfer, or it is rejected. Render the deposit details, including the reference, in your own UI. See the transaction object.

Reuse the listener methods from the usage example above. They remove the fragments after the frame’s final event: complete, or an error other than quoteExpired. Add the fragment from your purchase button’s click handler:

private fun onConfirmPurchaseClicked() {
    // A purchase is already running, so ignore a second tap
    if (supportFragmentManager.findFragmentByTag("buyButton") != null) return

    val fragment = MoonPayBuyButtonFragment.newInstance(
        clientToken = CredentialsManager.clientToken!!,
        quoteSignature = currentQuote.signature,
        headless = true
    )
    fragment.listener = this

    // Headless mode renders nothing, so use a 1px x 1px FrameLayout, or 0px in
    // a parent other than ConstraintLayout (there, 0dp means match constraint).
    // Keep it VISIBLE: INVISIBLE or GONE marks the page hidden and throttles it.
    supportFragmentManager.beginTransaction()
        .add(R.id.headless_frame_container, fragment, "buyButton")
        // Commit now, so a second tap finds the fragment
        .commitNow()

    buyButtonFragment = fragment
}

Pass an externalTransactionId to newInstance as well. If the system recreates the fragment mid-purchase, it removes itself rather than start a second purchase, and the ID lets you find the interrupted attempt through the API.

Apple Pay is not available on Android. Use the widget frame instead to render the full MoonPay buy experience — including payment collection and transaction confirmation — for credit/debit card, Google Pay, bank transfers, and more. See pay with widget for a full walkthrough.

What you’ll need

Before you initialize the widget frame, you need:

A clientToken from a successful connect flow
A valid quote signature for the transaction

import org.json.JSONObject

interface WidgetFrameListener {
    fun onWidgetReady()
    fun onWidgetTransactionCreated(transactionId: String, status: String)
    fun onWidgetComplete(transactionId: String, status: String)
    fun onWidgetFailed(failureReason: String)
    fun onWidgetError(code: String, message: String)
}

class MoonPayWidgetFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    private var quoteSignature: String? = null
    private var externalTransactionId: String? = null
    var listener: WidgetFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"
        private const val ARG_QUOTE_SIGNATURE = "quoteSignature"
        private const val ARG_EXTERNAL_TRANSACTION_ID = "externalTransactionId"

        fun newInstance(
            clientToken: String,
            quoteSignature: String,
            externalTransactionId: String? = null,
        ): MoonPayWidgetFragment {
            return MoonPayWidgetFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                    putString(ARG_QUOTE_SIGNATURE, quoteSignature)
                    putString(ARG_EXTERNAL_TRANSACTION_ID, externalTransactionId)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        quoteSignature = arguments?.getString(ARG_QUOTE_SIGNATURE)
        externalTransactionId = arguments?.getString(ARG_EXTERNAL_TRANSACTION_ID)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/widget", buildMap {
            put("flow", "buy")
            put("clientToken", clientToken!!)
            put("quoteSignature", quoteSignature!!)
            put("channelId", channelId)
            externalTransactionId?.let { put("externalTransactionId", it) }
        })
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "ready" -> {
                listener?.onWidgetReady()
            }
            "transactionCreated" -> {
                val transaction = payload?.optJSONObject("transaction")
                listener?.onWidgetTransactionCreated(
                    transaction?.optString("id") ?: "",
                    transaction?.optString("status") ?: ""
                )
            }
            "complete" -> handleComplete(payload)
            "error" -> {
                listener?.onWidgetError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete, widget loading
    }

    private fun handleComplete(payload: JSONObject?) {
        val transaction = payload?.optJSONObject("transaction") ?: return
        val status = transaction.optString("status")

        if (status == "failed") {
            val reason = transaction.optString("failureReason", "Transaction failed")
            listener?.onWidgetFailed(reason)
        } else {
            val transactionId = transaction.optString("id")
            listener?.onWidgetComplete(transactionId, status)
        }
    }
}

Usage with Activity

class PaymentActivity : AppCompatActivity(), WidgetFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayWidgetFragment.newInstance(
            clientToken = CredentialsManager.clientToken!!,
            quoteSignature = currentQuote.signature
        )
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    // WidgetFrameListener implementation

    override fun onWidgetReady() {
        // Widget is loaded and visible
    }

    override fun onWidgetTransactionCreated(transactionId: String, status: String) {
        // Transaction initiated — customer may need to complete 3-D Secure
        Toast.makeText(this, "Transaction created: $transactionId", Toast.LENGTH_SHORT).show()
    }

    override fun onWidgetComplete(transactionId: String, status: String) {
        Toast.makeText(this, "Transaction $transactionId: $status", Toast.LENGTH_SHORT).show()
        // Navigate to transaction status screen or poll for updates
    }

    override fun onWidgetFailed(failureReason: String) {
        AlertDialog.Builder(this)
            .setTitle("Payment Failed")
            .setMessage(failureReason)
            .setPositiveButton("OK", null)
            .show()
    }

    override fun onWidgetError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK", null)
            .show()
    }
}

Reset frame

The reset frame is headless. Use it when the customer signs out to clear MoonPay session state on MoonPay’s domain. See reset frame reference. Pass your clientToken so your app is authorized to embed the frame. Do not block sign-out if reset fails.

Reset fragment

import org.json.JSONObject

interface ResetFrameListener {
    fun onResetComplete()
    fun onResetError(code: String, message: String)
}

class MoonPayResetFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    var listener: ResetFrameListener? = null

    companion object {
        fun newInstance(clientToken: String): MoonPayResetFragment {
            return MoonPayResetFragment().apply {
                arguments = Bundle().apply {
                    putString("clientToken", clientToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString("clientToken")
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        webView.visibility = View.GONE

        loadFrame("/platform/v1/reset", mapOf(
            "channelId" to channelId,
            "clientToken" to clientToken!!,
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> listener?.onResetComplete()
            "error" -> listener?.onResetError(
                payload?.optString("code") ?: "unknown",
                payload?.optString("message") ?: "Unknown error"
            )
        }
    }

    override fun onFrameHandshakeComplete() {}
}

Usage

fun signOut(clientToken: String) {
    clearLocalCredentials()

    val fragment = MoonPayResetFragment.newInstance(clientToken)
    fragment.listener = object : ResetFrameListener {
        override fun onResetComplete() { /* finish sign-out */ }
        override fun onResetError(code: String, message: String) { /* still finish sign-out */ }
    }
    // Add to a zero-size container during sign-out; remove after complete/error.
}

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Setup

Dependencies

Key generation

Decryption utility

Base frame fragment

Handle JavaScript dialogs

Check frame

Check fragment

Usage

Connect frame

Connect fragment

Usage with Activity

Auth frame

Auth fragment

Usage with Activity

Add Card frame

What you’ll need

Add Card fragment

Usage with Activity

Buy Button frame

Android WebView setup

What you’ll need

Buy Button fragment

Challenge handling

Usage with Activity

Headless mode

Widget frame

What you’ll need

Widget fragment

Usage with Activity

Reset frame

Reset fragment

Usage

​Setup

​Dependencies

​Key generation

​Decryption utility

​Base frame fragment

​Handle JavaScript dialogs

​Check frame

​Check fragment

​Usage

​Connect frame

​Connect fragment

​Usage with Activity

​Auth frame

​Auth fragment

​Usage with Activity

​Add Card frame

​What you’ll need

​Add Card fragment

​Usage with Activity

​Buy Button frame

​Android WebView setup

​What you’ll need

​Buy Button fragment

​Challenge handling

​Usage with Activity

​Headless mode

​Widget frame

​What you’ll need

​Widget fragment

​Usage with Activity

​Reset frame

​Reset fragment

​Usage

Setup

Dependencies

Key generation

Decryption utility

Base frame fragment

Handle JavaScript dialogs

Check frame

Check fragment

Usage

Connect frame

Connect fragment

Usage with Activity

Auth frame

Auth fragment

Usage with Activity

Add Card frame

What you’ll need

Add Card fragment

Usage with Activity

Buy Button frame

Android WebView setup

What you’ll need

Buy Button fragment

Challenge handling

Usage with Activity

Headless mode

Widget frame

What you’ll need

Widget fragment

Usage with Activity

Reset frame

Reset fragment

Usage