Android - MoonPay Developer Docs

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.

// build.gradle.kts (app level)
dependencies {
    implementation("com.google.crypto.tink:tink-android:1.12.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.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 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

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

        return webView
    }

    protected fun loadFrame(path: String, params: Map<String, String>) {
        val queryString = params.entries.joinToString("&") { "${it.key}=${it.value}" }
        val url = "$FRAME_ORIGIN$path?$queryString"

        webView.loadUrl(url)
    }

    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() {
        super.onDestroyView()
        webView.destroy()
    }

    inner class MoonPayBridge {
        @JavascriptInterface
        fun postMessage(data: String) {
            handler.post {
                try {
                    val json = JSONObject(data)
                    handleMessage(json)
                } catch (e: Exception) {
                    // Ignore malformed messages
                }
            }
        }
    }
}

Handle JavaScript dialogs

In test mode, the Apple Pay frame renders a mock button and uses window.confirm to simulate the Apple Pay payment sheet. Android’s WebView returns false for window.confirm, alert, and prompt unless you attach a WebChromeClient that handles them — so without this, every test transaction silently comes back with status: "failed". Surface the simulated payment sheet with an AlertDialog:

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

class MoonPayChromeClient(private val fragment: Fragment) : WebChromeClient() {
    override fun onJsConfirm(
        view: WebView?,
        url: String?,
        message: String?,
        result: JsResult
    ): Boolean {
        val context = fragment.context ?: return false
        AlertDialog.Builder(context)
            .setTitle("Test Mode")
            .setMessage(message?.takeIf { it.isNotEmpty() } ?: "Simulate Apple Pay?")
            .setPositiveButton("OK") { _, _ -> result.confirm() }
            .setNegativeButton("Cancel") { _, _ -> result.cancel() }
            .setOnCancelListener { result.cancel() }
            .show()
        return true
    }
}

OK simulates a successful test transaction (the frame emits complete with a non-failed status); Cancel simulates a failed transaction (the frame emits complete with status: "failed").

Attach the WebChromeClient even if you only plan to ship live mode. The default WebView behaviour 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 frame

The buy frame processes a card or bank-transfer payment for a quote. It is headless — rendered at zero size — while the customer completes payment. For cards, if 3-D Secure is required, the frame emits a challenge event with a URL you open in a separate challenge frame. For bank transfers (SEPA, EUR), quote with paymentMethod.type set to "sepa"; the complete event returns a transaction that stays pending and carries a bankTransferDepositInfo object you render natively so the customer can send the deposit. See the buy frame reference for event details, and Pay with bank transfer for the full bank-transfer walkthrough.

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.

What you’ll need

Before you initialize the buy frame, you need:

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

Buy fragment

import org.json.JSONObject

interface BuyFrameListener {
    fun onBuyComplete(transactionId: String, status: String)
    fun onBuyChallenge(url: String)
    fun onBuyError(code: String, message: String)
}

class MoonPayBuyFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    private var quoteSignature: String? = null
    private var externalTransactionId: String? = null
    var listener: BuyFrameListener? = 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,
        ): MoonPayBuyFragment {
            return MoonPayBuyFragment().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/buy", buildMap {
            put("clientToken", clientToken!!)
            put("channelId", channelId)
            put("signature", quoteSignature!!)
            externalTransactionId?.let { put("externalTransactionId", it) }
        })
    }

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

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> {
                val transaction = payload?.optJSONObject("transaction")
                listener?.onBuyComplete(
                    transaction?.optString("id") ?: "",
                    transaction?.optString("status") ?: ""
                )
            }
            "challenge" -> {
                val url = payload?.optString("url") ?: ""
                listener?.onBuyChallenge(url)
            }
            "error" -> {
                listener?.onBuyError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

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

Challenge handling

When the buy fragment receives a challenge URL, add a MoonPayChallengeFragment to present the 3-D Secure flow. On completion, cancellation, or error, remove both the challenge and buy fragments:

import org.json.JSONObject

interface ChallengeFrameListener {
    fun onChallengeComplete(transactionId: String, status: 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")
                listener?.onChallengeComplete(
                    transaction?.optString("id") ?: "",
                    transaction?.optString("status") ?: ""
                )
            }
            "cancelled" -> {
                listener?.onChallengeCancelled()
            }
            "error" -> {
                listener?.onChallengeError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

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

Usage with Activity

class BuyPaymentActivity : AppCompatActivity(), BuyFrameListener, ChallengeFrameListener {
    private var buyFragment: MoonPayBuyFragment? = null

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

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

        supportFragmentManager.beginTransaction()
            .add(R.id.frame_container, fragment, "buy")
            .commit()

        buyFragment = fragment
    }

    // BuyFrameListener implementation

    override fun onBuyComplete(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 onBuyChallenge(url: String) {
        val challengeFragment = MoonPayChallengeFragment.newInstance(
            url,
            CredentialsManager.clientToken!!
        )
        challengeFragment.listener = this

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

    override fun onBuyError(code: String, message: String) {
        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 onChallengeCancelled() {
        removeFragments()
    }

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

    private fun removeFragments() {
        val transaction = supportFragmentManager.beginTransaction()
        supportFragmentManager.findFragmentByTag("challenge")?.let { transaction.remove(it) }
        supportFragmentManager.findFragmentByTag("buy")?.let { transaction.remove(it) }
        transaction.commit()
    }
}

Google Pay frame

The Google Pay frame renders the Google Pay button and handles the payment flow. See Google Pay frame reference for event details.

Android WebView setup

Google Pay in a WebView requires enabling the Payment Request API and meeting the dependency, manifest, and version requirements on the Google Pay frame reference. Apply that setup in your base fragment before loading this frame or the Buy Button frame.

What you’ll need

Before you initialize the Google Pay frame, you need:

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

Google Pay fragment

import org.json.JSONObject

interface GooglePayFrameListener {
    fun onGooglePayReady()
    fun onGooglePayComplete(transactionId: String, status: String)
    fun onGooglePayFailed(reason: String)
    fun onGooglePayError(code: String, message: String)
    fun onGooglePayChallenge(url: String)
}

class MoonPayGooglePayFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    private var quoteSignature: String? = null
    private var externalTransactionId: String? = null
    var listener: GooglePayFrameListener? = 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,
        ): MoonPayGooglePayFragment {
            return MoonPayGooglePayFragment().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/google-pay", buildMap {
            put("clientToken", clientToken!!)
            put("channelId", channelId)
            put("signature", quoteSignature!!)
            externalTransactionId?.let { put("externalTransactionId", it) }
        })
    }

    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?.onGooglePayReady()
            }
            "complete" -> {
                val transaction = payload?.optJSONObject("transaction")
                val status = transaction?.optString("status") ?: ""

                if (status == "failed") {
                    listener?.onGooglePayFailed(
                        transaction?.optString("failureReason") ?: "Transaction failed"
                    )
                } else {
                    listener?.onGooglePayComplete(
                        transaction?.optString("id") ?: "",
                        status
                    )
                }
            }
            "challenge" -> {
                val url = payload?.optString("url") ?: ""
                listener?.onGooglePayChallenge(url)
            }
            "error" -> {
                listener?.onGooglePayError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

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

Usage with Activity

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

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

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

    override fun onGooglePayReady() {
        // Google Pay button is visible and ready
    }

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

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

    override fun onGooglePayError(code: String, message: String) {
        if (code == "quoteExpired") {
            // Fetch new quote and update the fragment
            return
        }
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }

    override fun onGooglePayChallenge(url: String) {
        // Open the challenge frame — see "Challenge handling" section
    }
}

Buy Button frame

The Buy Button frame consolidates Apple Pay, Google Pay, and card into a single MoonPay-hosted button that matches the payment method in your quote. It runs the same buy pipeline as the buy frame and supports guest checkout when your quote allows it. See buy button frame reference and Pay with the buy button. When your quote uses Google Pay, meet the Android WebView requirements on the Google Pay frame reference before loading the frame.

Buy Button fragment

import org.json.JSONObject

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

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

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

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

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

        loadFrame("/platform/v1/buy-button", buildMap {
            put("clientToken", clientToken!!)
            put("channelId", channelId)
            put("signature", quoteSignature!!)
        })
    }

    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")
                listener?.onBuyButtonComplete(
                    transaction?.optString("id") ?: "",
                    transaction?.optString("status") ?: ""
                )
            }
            "challenge" -> listener?.onBuyButtonChallenge(payload?.optString("url") ?: "")
            "error" -> listener?.onBuyButtonError(
                payload?.optString("code") ?: "unknown",
                payload?.optString("message") ?: "Unknown error"
            )
        }
    }

    override fun onFrameHandshakeComplete() {}
}

For 3-D Secure, reuse challenge handling from the Buy frame section.

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.
}

​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 frame

​What you’ll need

​Buy fragment

​Challenge handling

​Usage with Activity

​Google Pay frame

​Android WebView setup

​What you’ll need

​Google Pay fragment

​Usage with Activity

​Buy Button frame

​Buy Button fragment

​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 frame

What you’ll need

Buy fragment

Challenge handling

Usage with Activity

Google Pay frame

Android WebView setup

What you’ll need

Google Pay fragment

Usage with Activity

Buy Button frame

Buy Button fragment

Widget frame

What you’ll need

Widget fragment

Usage with Activity

Reset frame

Reset fragment

Usage